api-test-mcp

api-test-mcp

Un servidor MCP que le da a Claude Code, Cursor, Windsurf, o cualquier agente de IA compatible con MCP la capacidad de llamar realmente a tu API y verificar la respuesta contra lo que tu especificación OpenAPI promete — no solo leer la documentación y adivinar.

Sin claves de API, sin configuración, sin costo. Funciona con cualquier especificación OpenAPI/Swagger 3.x (URL o archivo local).

Por qué existe esto

Los agentes de IA son excelentes para leer una especificación OpenAPI y escribir código basado en ella — pero están adivinando si la API real realmente se comporta como dice la especificación. Esto le da a un agente (o a ti, en un chat normal) una forma de descubrirlo de verdad: llamar al endpoint en vivo y verificar si la respuesta realmente coincide con el esquema documentado.

Instalación

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

Agrégalo a la configuración de tu cliente MCP, por ejemplo para Claude Code:

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

O en la configuración de MCP de claude_desktop_config.json / Cursor:

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

Herramientas

Herramienta	Qué hace
load_api_spec	Carga y desreferencia una especificación OpenAPI/Swagger desde una URL o ruta local. Devuelve el título de la API, los servidores y cada endpoint documentado. Llama a esto primero.
list_endpoints	Lista cada endpoint actualmente cargado.
call_endpoint	Realiza una llamada HTTP real a un endpoint documentado. Devuelve el estado real, los encabezados y el cuerpo.
validate_response	Verifica un cuerpo de respuesta contra el esquema JSON documentado para un método + ruta + estado determinados.
test_endpoint	call_endpoint + validate_response en un solo paso. La herramienta principal — "¿este endpoint realmente funciona como está documentado?"
run_all_tests	Prueba de contrato de mejor esfuerzo en todos los endpoints GET que no requieren parámetros obligatorios. Pasa includeMutating: true para también auto-generar parámetros/cuerpos de ejemplo a partir del esquema e intentar POST/PUT/PATCH (desactivado por defecto — puede escribir datos reales). Los endpoints que aún necesitan entrada manual se listan como omitidos, con el motivo.
check_health	Ping de una sola vez a través de un conjunto de endpoints (o cada GET sin parámetros en la especificación cargada): informa accesibilidad y latencia. Útil antes de una demostración o como paso de CI.
diff_api_specs	Compara dos versiones de una especificación (por ejemplo, una etiqueta antigua vs. main) y señala cambios potencialmente disruptivos — endpoints eliminados, campos recién obligatorios, cambios de tipo, valores de enumeración eliminados — versus cambios aditivos seguros.

Todas las anteriores aceptan un preset opcional de auth (bearer, apiKey en un encabezado o parámetro de consulta, o basic) para que las APIs autenticadas no se limiten a construir encabezados crudos manualmente, y un timeoutMs opcional.

Ejemplo (cómo se ve una conversación con un agente)

Tú: Carga mi especificación de API en https://api.example.com/openapi.json y verifica si /users/{id} realmente devuelve lo que documenta.

Agente: (llama a load_api_spec, luego a test_endpoint con un ID de usuario real) → "Lo llamé — obtuve un 200, pero la respuesta no tiene el campo created_at que tu especificación marca como obligatorio, y role está documentado como una enumeración de 3 valores pero la API devolvió "superadmin", que no es uno de ellos."

Para una API autenticada:

Tú: Ejecuta una prueba de contrato completa contra mi API de staging usando este token de portador, e incluye los endpoints de escritura.

Agente: (llama a run_all_tests con { auth: { type: "bearer", token: "..." }, includeMutating: true }) → "12 aprobados, 2 fallidos, 3 omitidos. POST /orders falló la validación de esquema — total_cents devolvió una cadena, no el entero que tu especificación documenta."

Probado contra tráfico real en vivo

npm test ejecuta tres verificaciones reales, sin simulaciones, sin accesorios prefabricados que pretendan ser un servidor:

• test/smoke-test.js — carga una especificación, hace llamadas HTTPS reales a una API pública en vivo, valida la respuesta real, y deliberadamente introduce una respuesta rota para confirmar que la validación realmente detecta discrepancias (no solo una verificación de ruta feliz).
• test/new-features-test.js — presets de autenticación aplicados a una URL de solicitud saliente real, un tiempo de espera/aborto de red real, una llamada de verificación de salud real, y pruebas fuera de línea deterministas para la lógica de diferencias de especificación.
• test/mcp-protocol-test.js — inicia el servidor MCP real como un subproceso y se comunica con él a través del protocolo MCP real, de la misma manera que lo harían Claude Code o Cursor.

CI ejecuta la suite completa en cada push/PR contra Node 18, 20 y 22.

Hoja de ruta

v1.0 incluyó pruebas de contrato, presets de autenticación, datos de ejemplo auto-generados para endpoints de mutación, diferencias de especificación y verificaciones de salud. Ideas para lo que sigue:

• Modo de salida YAML / un pequeño envoltorio CLI para uso no MCP
• Reintentos/retroceso configurables para endpoints inestables en run_all_tests y check_health
• Generación de ejemplos consciente de patrones (respetar pattern de JSON Schema en lugar de una cadena de marcador de posición)
• Historial de verificaciones de salud persistido (actualmente solo de una sola vez)

Las contribuciones son bienvenidas — consulta CONTRIBUTING.md. ¿Ves un tipo de endpoint o peculiaridad de especificación que esto no maneja bien? Abre un issue.

Licencia

MIT