api-test-mcp

api-test-mcp

Um servidor MCP que dá ao Claude Code, Cursor, Windsurf ou qualquer agente de IA compatível com MCP a capacidade de realmente chamar sua API e verificar a resposta contra o que sua especificação OpenAPI promete — não apenas ler a documentação e adivinhar.

Sem chaves de API, sem configuração, sem custo. Funciona com qualquer especificação OpenAPI/Swagger 3.x (URL ou arquivo local).

Por que isso existe

Agentes de IA são ótimos em ler uma especificação OpenAPI e escrever código para ela — mas eles estão adivinhando se a API real realmente se comporta da maneira que a especificação diz. Isso dá a um agente (ou a você, em um chat normal) uma maneira de descobrir de verdade: chamar o endpoint ao vivo e verificar se a resposta realmente corresponde ao esquema documentado.

Instalação

git clone <this repo>
cd api-test-mcp
npm install

Adicione-o à configuração do seu cliente MCP, por exemplo, para o Claude Code:

claude mcp add api-test -- node /absolute/path/to/api-test-mcp/src/index.js

Ou nas configurações de MCP do claude_desktop_config.json / Cursor:

{
  "mcpServers": {
    "api-test": {
      "command": "node",
      "args": ["/absolute/path/to/api-test-mcp/src/index.js"]
    }
  }
}

Ferramentas

Ferramenta	O que faz
load_api_spec	Carrega e desreferencia uma especificação OpenAPI/Swagger de uma URL ou caminho local. Retorna o título da API, servidores e cada endpoint documentado. Chame isso primeiro.
list_endpoints	Lista cada endpoint atualmente carregado.
call_endpoint	Faz uma chamada HTTP real para um endpoint documentado. Retorna o status real, cabeçalhos e corpo.
validate_response	Verifica um corpo de resposta contra o esquema JSON documentado para um método + caminho + status específicos.
test_endpoint	call_endpoint + validate_response em uma única etapa. A ferramenta principal — "este endpoint realmente funciona como documentado?"
run_all_tests	Passagem de teste de contrato de melhor esforço em todos os endpoints GET que não exigem parâmetros obrigatórios. Passe includeMutating: true para também gerar automaticamente exemplos de parâmetros/corpos a partir do esquema e tentar POST/PUT/PATCH (desativado por padrão — pode escrever dados reais). Endpoints que ainda precisam de entrada manual são listados como ignorados, com o motivo.
check_health	Ping único em um conjunto de endpoints (ou em cada GET sem parâmetros na especificação carregada): relata acessibilidade e latência. Útil antes de uma demonstração ou como etapa de CI.
diff_api_specs	Compara duas versões de uma especificação (por exemplo, uma tag antiga vs. main) e sinaliza mudanças provavelmente quebradas — endpoints removidos, campos recém-obrigatórios, mudanças de tipo, valores de enum removidos — versus mudanças aditivas seguras.

Todas as ferramentas acima aceitam um preset opcional de auth (bearer, apiKey em um cabeçalho ou parâmetro de consulta, ou basic) para que APIs autenticadas não fiquem limitadas à construção manual de cabeçalhos brutos, e um timeoutMs opcional.

Exemplo (como é uma conversa com um agente)

Você: Carregue minha especificação de API em https://api.example.com/openapi.json e verifique se /users/{id} realmente retorna o que documenta.

Agente: (chama load_api_spec, depois test_endpoint com um ID de usuário real) → "Chamei — obtive um 200, mas a resposta está faltando o campo created_at que sua especificação marca como obrigatório, e role está documentado como um enum de 3 valores, mas a API retornou "superadmin", que não é um deles."

Para uma API autenticada:

Você: Execute uma passagem completa de teste de contrato contra minha API de staging usando este token de portador e inclua os endpoints de escrita.

Agente: (chama run_all_tests com { auth: { type: "bearer", token: "..." }, includeMutating: true }) → "12 passaram, 2 falharam, 3 ignorados. POST /orders falhou na validação de esquema — total_cents veio como uma string, não o inteiro que sua especificação documenta."

Testado contra tráfego real ao vivo

npm test executa três verificações reais, sem mocks, sem fixtures prontas fingindo ser um servidor:

• test/smoke-test.js — carrega uma especificação, faz chamadas HTTPS reais a uma API pública ao vivo, valida a resposta real e deliberadamente alimenta uma resposta quebrada para confirmar que a validação realmente detecta incompatibilidades (não apenas uma verificação de caminho feliz).
• test/new-features-test.js — presets de autenticação aplicados a uma URL de solicitação de saída real, um timeout/abort de rede real, uma chamada real de verificação de saúde e testes offline determinísticos para a lógica de diff de especificação.
• test/mcp-protocol-test.js — inicia o servidor MCP real como um subprocesso e conversa com ele pelo protocolo MCP real, da mesma forma que o Claude Code ou o Cursor fariam.

O CI executa a suíte completa em cada push/PR contra Node 18, 20 e 22.

Roadmap

A v1.0 entregou teste de contrato, presets de autenticação, dados de exemplo gerados automaticamente para endpoints de mutação, diff de especificação e verificações de saúde. Ideias para o que vem a seguir:

• Modo de saída YAML / um pequeno wrapper de CLI para uso não-MCP
• Retry/backoff configurável para endpoints instáveis em run_all_tests e check_health
• Geração de exemplos ciente de padrões (respeitar pattern do JSON Schema em vez de uma string de espaço reservado)
• Histórico persistente de verificações de saúde (atualmente apenas único)

Contribuições são bem-vindas — veja CONTRIBUTING.md. Viu um tipo de endpoint ou peculiaridade de especificação que isso não trata bem? Abra uma issue.

Licença

MIT