Como registrei um servidor MCP para 3.760 varejistas — e o que aprendi

Ontem, o CLI Market era um pacote PyPI.
Esta semana, é um servidor oficial do Registro MCP:

Veja o que foi necessário para ser listado, como é a validação do registro e por que o MCP é a camada que falta entre o comércio eletrônico e os agentes de IA.

**

O Registro MCP: o que foi necessário para ser listado

**
O Registro do Protocolo de Contexto do Modelo em registry.modelcontextprotocol.io é o diretório canônico
de servidores MCP. Ser listado não se trata apenas de ter um servidor funcionando — o registro valida a propriedade, verifica a conformidade do esquema e confirma que o pacote realmente existe.

*Passo 1: O arquivo mcp.json
*
Cada servidor MCP precisa de um mcp.json na raiz do repositório. O nosso:
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json"
,
"name": "io.github.Treevu-ai/cli-market",
"title": "CLI Market",
"version": "1.0.1",
"description": "12 ferramentas MCP para buscar, comparar e comprar em 3.760 varejistas em 67 c
países",
"repository": {
"url": "https://github.com/Treevu-ai/cli-market-world",
"source": "github"
},
"packages": [{
"registryType": "pypi",
"identifier": "cli-market",
"version": "1.0.17",
"transport": { "type": "stdio" }
}]
}

Decisões chave:

• Formato do nome: io.github.{org}/{project} — reverse-DNS, escopo da org
• registryType: pypi — CLI Market é um pacote Python no PyPI
• transport: stdio — o servidor MCP se comunica via entrada/saída padrão
• versão fixa — sem intervalos, correspondência exata de versão

*Passo 2: Provando a propriedade
*
O registro não confia que cli-market no PyPI pertence a Treevu-ai no GitHub. Ele valida escaneando o README do pacote PyPI em busca de um comentário HTML específico:

<!-- mcp-name: io.github.Treevu-ai/cli-market -->

Esta linha deve aparecer no README que é renderizado no PyPI. O registro busca o pacote, analisa o README e verifica se a anotação corresponde ao nome do servidor. Se não corresponder — rejeitado.

Adicionamos isso ao nosso README, aumentamos a versão para 1.0.17 e fizemos o upload para o PyPI. O registro validou em menos de um segundo.

*Passo 3: Validação do esquema
*
O endpoint de publicação executa o validador completo do esquema ServerJSON. Cada campo é verificado:

descrição máxima de 100 caracteres, o nome deve corresponder a ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$,
packages[].identifier deve ser resolvido no registro, packages[].transport.type deve ser stdio/
streamable-http/sse.

Uma coisa que nos atrapalhou: o esquema mudou entre mcp.json (o formato do lado do repositório) e ServerJSON (o formato da API do registro). No repositório, você declara comando, args, tipo. Na API do registro, isso vai dentro de packages[].transport e packages[] requer registryType + identifier + transport. Acertar isso levou algumas rodadas.

*Passo 4: Autenticação
*
O registro usa OAuth do GitHub. Trocamos um token do GitHub por um JWT do registro:
POST /v0.1/auth/github-at → { registry_token: "eyJ..." }

Então publicamos:
POST /v0.1/publish → { server: {...}, _meta: { status: "active" } }

O token expira, então para atualizações você re-autentica. Todo o fluxo pode ser scriptado em menos de 10 linhas de bash.

As 12 ferramentas: arquitetura

Todas as 12 ferramentas estão sobre um conector VTEX unificado que normaliza as APIs de 3.760 varejistas em um único esquema JSON.

_Quatro ferramentas merecem atenção especial:
_

• - market_compare — Não é uma simples busca de preço. Primeiro normaliza SKUs entre varejistas (o mesmo produto tem IDs internos diferentes no Carrefour Brasil e no Sainsbury's Reino Unido), deduplica e retorna um conjunto de preços canônicos. Três etapas em uma única chamada MCP.
• market_checkout — Cadeias: validação do carrinho → verificação de estoque → resolução do método de pagamento → confirmação do pedido. Tudo em uma invocação. Mas nunca completa autonomamente — V1 requer aprovação humana explícita antes da execução.
• market_ask — A ferramenta mais composta. Entrada em linguagem natural → busca semântica → comparação entre varejistas → construção de carrinho → prontidão para checkout. "Comprar arroz" percorre todo o pipeline.

O padrão de composição — As ferramentas são suficientemente atômicas para serem compostas, compostas o suficiente para não afogar o agente. 12 ferramentas. Não 1 mega-ferramenta. Não 100 endpoints REST individuais.

───

O que eu faria diferente

1. Leia a especificação OpenAPI primeiro. O esquema do endpoint de publicação está documentado em /docs. Eu adivinhei a partir do formato mcp.json e cometi 5 erros de validação antes de acertar.

2. Configure a anotação do PyPI cedo. O comentário mcp-name é a prova de propriedade. Adicione-o ao seu README antes de publicar no registro.

3. Script o fluxo de autenticação. Token do GitHub → JWT do registro → publicação. Três chamadas curl. Envolva-as em um alvo Makefile e esqueça disso.

───

CLI Market está no registro.
O agente agora pode buscar, comparar e comprar em 3.760 varejistas em 67 países — tudo via chamadas de ferramentas estruturadas com zero scraping.

pip install cli-market
io.github.Treevu-ai/cli-market
github.com/Treevu-ai/cli-market-world

Ricardo Cuba
Fundador & Líder de Produto | CLI Market
CEO Sinapsis Innovadora
Trujillo, Peru