Capture Drift de Tool-Schema em 10 Minutos (Demonstração Ao Vivo + Opcional)

Seu stack de agentes pode parecer saudável enquanto o contrato subjacente já está quebrado.

HTTP 200 em /health. Nenhum deploy falhou. CI verde. Então tools/call começa a retornar resultados vazios porque um mantenedor renomeou um parâmetro ou removeu uma ferramenta de tools/list — e ninguém fixou uma linha de base.

Construímos o ToolSchema Kit como um pequeno laboratório reprodutível para esse modo de falha: um servidor Go MCP com saída de ferramenta versionada que você pode quebrar de propósito. Este walkthrough leva cerca de 10 minutos e funciona inteiramente no endpoint hospedado gratuito — nenhuma chave de API de fornecedor é necessária.

Se você quiser monitoramento contínuo após o exercício, a última seção mostra como apontar DriftGuard para a mesma URL.

O que você irá construir

Repositórios envolvidos:

• Servidor de demonstração: github.com/kioie/toolschema-kit
• Diff + cliente MCP: github.com/kioie/driftguard
• Monitoramento hospedado: driftguard.org/start (um watch gratuito em teste)

Por que isso é importante (contexto de 30 segundos)

Equipes OpenAPI já diferenciam especificações em CI com ferramentas como OASDiff. Integrações MCP raramente recebem a mesma disciplina:

• tools/list é a coisa mais próxima de uma especificação publicada
• Os fornecedores nem sempre registram mudanças de esquema
• Agentes ignoram erros estruturados como tentativas ou silêncio

ToolSchema Kit permite que você pratique essa lacuna localmente antes que aconteça com Stripe, GitHub ou seu MCP interno de operações.

Passo 1 — Use o catálogo MCP ao vivo (sem instalação)

Uma implantação gratuita do Render já está em execução:

https://toolschema-kit.onrender.com/mcp

Verificação de saúde:

curl -s https://toolschema-kit.onrender.com/health
# {"ok":true,"schema":"2026.06.01"}

Ou execute localmente:

git clone https://github.com/kioie/toolschema-kit.git
cd toolschema-kit
CATALOG_MCP_TRANSPORT=http go run ./cmd/catalog-mcp
# MCP: http://127.0.0.1:8080/mcp

O servidor expõe duas ferramentas:

Passo 2 — Conectar o Cursor

Adicione a .cursor/mcp.json (troque a URL por localhost se você executou localmente):

{
  "mcpServers": {
    "commerce-catalog": {
      "url": "https://toolschema-kit.onrender.com/mcp"
    }
  }
}

Recarregue o MCP no Cursor, então pergunte:

Chame get_product e list_skus. Resuma os campos SKU que você vê.

Você deve obter uma única linha de SKU sob o esquema 2026.06.01. Esse caminho feliz é onde a maioria das equipes para de testar após o primeiro dia.

Passo 3 — Capturar o contrato

Trate tools/list como um arquivo OpenAPI que você versiona no git.

Captura manual — salve o JSON do seu inspetor MCP ou sessão de agente.

Com DriftGuard OSS (diff local apenas, sem conta):

git clone https://github.com/kioie/driftguard
cd driftguard && npm ci && npm run build

Use compare_json via MCP ou CLI quando você tiver cargas úteis antes/depois. O modelo mental: linha de base agora, diff depois.

Para URLs de produção, o DriftGuard hospedado armazena essa linha de base e faz polling em uma programação — mas o exercício de laboratório funciona sem se inscrever.

Passo 4 — Simular deriva silenciosa

A versão do esquema 2026.06.02 altera a saída de list_skus: uma linha de SKU extra e campos renomeados. A saúde HTTP permanece {"ok":true}.

Local:

CATALOG_SCHEMA_VERSION=2026.06.02 CATALOG_MCP_TRANSPORT=http go run ./cmd/catalog-mcp

Re-execute list_skus no Cursor. O agente pode ainda ter sucesso — mas a forma JSON mudou. Isso é deriva silenciosa: nenhum alarme de código de status, suposições quebradas a montante.

Diff as duas cargas úteis com o CLI do DriftGuard:

npm run check -- diff \
  '{"schemaVersion":"2026.06.01","skus":[{"id":"sku-pro","label":"Pro"}]}' \
  '{"schemaVersion":"2026.06.02","skus":[{"id":"sku-pro","label":"Pro Plan"},{"id":"sku-team","label":"Team"}]}'

Classificação de exemplo:

Tabela de versão completa: docs/simulate-drift.md no repositório do kit.

Passo 5 — Opcional: watch sempre ativo

Quando o exercício fizer sentido, promova a mesma URL para