Ferramentas/lista não é um check de prontidão para servidores MCP

A primeira versão do mcp-probe verificou as coisas óbvias:

• o servidor MCP pode ser inicializado?
• o tools/list funciona?
• os esquemas de ferramentas estão presentes?

Isso foi útil, mas não o suficiente.

Quanto mais eu testava fluxos de trabalho reais do MCP, mais claro o problema se tornava:

tools/list é auto-relato. O CI precisa de um recibo.

Um servidor MCP pode anunciar um catálogo de ferramentas limpo e ainda falhar em cada chamada real porque a transferência de OAuth, escopos, credenciais de downstream, limites de linha, limites de inquilinos ou formatos de resposta estão quebrados.

Portanto, o último lançamento do mcp-probe se concentra menos em "o processo começa?" e mais em "o CI está fazendo cumprir o contrato do qual um agente realmente depende?"

O novo fluxo de inicialização

npx @k08200/mcp-probe@latest init \
  --target @your-org/your-mcp-server \
  --discover \
  --lock-tools \
  --github-actions

Isso cria:

• mcp-probe.config.json
• .mcp-probe.json
• .github/workflows/mcp-probe.yml

A parte importante é o que acontece durante --discover.

mcp-probe conecta-se ao servidor, lê o catálogo ao vivo de tools/list e gera um contrato inicial a partir dos esquemas de ferramentas observados.

Amostras de sidecar cientes de esquema

Amostras geradas mais antigas eram ingênuas demais. Se um esquema dissesse:

{
  "type": "object",
  "required": ["location", "count"],
  "properties": {
    "location": { "type": "string", "enum": ["Chicago", "Nova York"] },
    "count": { "type": "integer", "minimum": 1 }
  }
}

o fallback antigo poderia produzir strings vazias ou valores zero. Isso frequentemente atingia a validação de entrada e nunca testava o caminho de chamada real.

v1.11.0 agora usa dicas de esquema:

• default
• enum
• numérico minimum
• string minLength
• objetos aninhados
• array minItems

Assim, a amostra gerada se torna:

{
  "location": "Chicago",
  "count": 1
}

Ainda é apenas um ponto de partida. Você deve revisar as amostras geradas antes de executá-las com credenciais de produção, especialmente para ferramentas de mutação, administração, exportação ou inspeção de ambiente.

Bloqueio de catálogo

A outra nova peça é --lock-tools.

Com --discover, o mcp-probe agora escreve os nomes das ferramentas observadas em expectedTools, para que o CI falhe se uma ferramenta necessária desaparecer.

Com --lock-tools, ele também escreve allowedTools, para que o CI falhe se ferramentas inesperadas aparecerem.

Isso é importante para superfícies de agente de baixa confiança. Se um servidor de repente expõe delete_user, export_all ou rotate_api_key, eu não quero que isso se torne disponível para um agente apenas porque tools/list ainda retorna JSON válido.

Configuração de exemplo:

{
  "timeoutMs": 10000,
  "servers": [
    {
      "name": "meu-servidor-mcp",
      "target": "@your-org/your-mcp-server",
      "probeTools": true,
      "toolsFile": ".mcp-probe.json",
      "expectedTools": ["search", "read_record"],
      "allowedTools": ["search", "read_record"]
    }
  ]
}

Recibos

Para o CI, o fluxo de trabalho também pode persistir um artefato de recibo redigido:

npx @k08200/mcp-probe@latest \
  --config mcp-probe.config.json \
  --github-summary \
  --fail-on-warn \
  --receipt-file mcp-probe.receipt.json

Esse recibo é a coisa que eu quero que o CI