mcp-flightcheck

Intenta romper tu servidor MCP antes de que lo hagan tus usuarios. Ejecuta el inicio normal del cliente y luego envía lo que un cliente normalmente no enviaría: una llamada sin nombre de herramienta, un método desconocido, una llamada a herramienta con argumentos obligatorios faltantes, y observa si hay fallos, bloqueos y herramientas que se ejecutan cuando no deberían. Obtienes una tarjeta de puntuación donde cada hallazgo cita la cláusula de la especificación que lo respalda, y un código de salida distinto de cero para CI.

Lo ejecuté contra todos los servidores remotos del registro oficial, 6.892 de ellos. De los que siquiera aceptan una conexión, una cuarta parte falla una verificación y uno de cada siete está simplemente roto: fallan, se cuelgan o ejecutan un tools/call que no nombra ninguna herramienta. El Inspector oficial es interactivo, nada falla una compilación, por lo que nada de esto se detecta antes del lanzamiento.

$ npx mcp-flightcheck node dist/server.js

mcp-flightcheck | my-server 1.4.0 (node dist/server.js)

Protocol conformance
  PASS  Declared capabilities actually work - declared capabilities respond: tools
  PASS  Responds to ping - ping answered
  PASS  Rejects unknown methods - unknown method rejected with -32601 (method not found)
  WARN  Rejects malformed request params - malformed params surfaced as -32603, expected -32602

Tool quality
  PASS  tools/list works - listed 12 tools
  FAIL  Every tool has a valid input schema - 3 of 12 tools have missing or broken input schemas
          delete_item: no inputSchema at all (official SDK clients reject the entire tool list over this)
  PASS  Tool names are unique and well-formed - all tool names unique and well-formed

Reliability
  PASS  Responds quickly - median tools/list latency 11ms
  FAIL  Tools reject invalid arguments cleanly - invalid arguments crashed the server (probed 10 tools)
          update_config: server crashed
  FAIL  Server still healthy after all probes - server is gone after probing, it crashed somewhere above

Hygiene
  PASS  Server identifies itself - my-server 1.4.0
  WARN  Every tool has a description - 2 of 12 tools have no description

NOT READY  7 pass, 2 warn, 3 fail, 0 skip (1840ms)

Instalación

npx mcp-flightcheck <your server>     # no install
npm i -D mcp-flightcheck              # or as a dev dependency

Node 20+.

Related MCP server: mcp-test-server

Uso

mcp-flightcheck node dist/server.js           # stdio server
mcp-flightcheck python -m my_mcp_server       # any command, any language
mcp-flightcheck https://example.com/mcp       # Streamable HTTP server

mcp-flightcheck --json node dist/server.js    # machine-readable report
mcp-flightcheck --strict node dist/server.js  # warnings also fail the run
mcp-flightcheck --no-probe node server.js     # skip invalid-argument probing
mcp-flightcheck --timeout 30000 slow-server   # per-request timeout in ms

Autenticación (prueba tu propio servidor con acceso restringido en CI)

La mayoría de los servidores remotos en producción requieren un token, que es exactamente lo que quieres restringir en CI. Pasa uno con --bearer, o establece encabezados arbitrarios con --header (repetible):

mcp-flightcheck --strict --bearer "$MCP_TOKEN" https://your-server/mcp
mcp-flightcheck --header "X-Api-Key: $API_KEY" --header "X-Tenant: acme" https://your-server/mcp

Mantén los tokens en secretos de CI y pásalos mediante variable de entorno, como se muestra arriba. mcp-flightcheck nunca imprime los valores de los encabezados, y el informe JSON identifica el objetivo solo por URL. Las banderas de autenticación aplican a objetivos remotos (http); un servidor stdio recibe las credenciales a través de su propio entorno y argumentos.

Códigos de salida: 0 limpio, 1 hallazgos, 2 no se pudo conectar o error de uso. Úsalo directamente en CI:

- run: npx mcp-flightcheck --strict node dist/server.js

Qué verifica

Conformidad con el protocolo

• Los métodos desconocidos son rechazados con -32601, no con un bloqueo, un fallo o un falso éxito.

• Los parámetros de solicitud mal formados devuelven un error JSON-RPC limpio.

• Se responde a ping, como exige la especificación.

• Cada capacidad que el servidor declara (herramientas, recursos, prompts) realmente responde. Declarar lo que no se puede servir rompe a los clientes.

Calidad de las herramientas

• tools/list funciona y pagina sin bucles.

• Cada herramienta incluye un inputSchema que se compila como JSON Schema, con una raíz de objeto. Los servidores sin esquemas son rechazados directamente por los clientes oficiales del SDK, y enviar esquemas tipados es el separador de calidad más fuerte medido entre los servidores públicos.

• Los nombres de las herramientas son únicos y están bien formados. Existen descripciones, porque el modelo enruta basándose en ellas.

Fiabilidad

• Sondeo de argumentos inválidos: cada herramienta con argumentos obligatorios es llamada sin ellos. Un servidor bien construido rechaza la llamada antes de que se ejecute algo. mcp-flightcheck marca las herramientas que se ejecutan de todos modos, se cuelgan hasta agotar el tiempo de espera o tumban todo el proceso.

• Latencia mediana de tools/list, porque los agentes la pagan en cada sesión.

• Una verificación de salud final prueba que el servidor sobrevivió a sus propias rutas de error.

La taxonomía de fallos coincide con lo que se rompe en el mundo real: desajuste de esquema, tiempo de espera, fallo, violación del protocolo.

Los hallazgos citan la especificación

Cada hallazgo lleva la cláusula que aplica, citada textualmente con un enlace:

WARN  Rejects malformed request params - malformed params surfaced as -32603, expected -32602
        MUST: -32602 Invalid params: Invalid method parameter(s). (JSON-RPC 2.0, which MCP messages MUST follow)
        https://www.jsonrpc.org/specification#error_object

Las reglas sin una cláusula que las respalde se etiquetan como HEURÍSTICA, para que siempre puedas distinguir una violación de la especificación de una decisión subjetiva. Las dos verificaciones sin base normativa (salud posterior al sondeo, latencia) no llevan ninguna cita en lugar de una inventada.

Por qué el sondeo está activado por defecto

El sondeo envía solo entrada inválida (argumentos obligatorios faltantes). Un servidor con cualquier validación de entrada lo rechaza antes de que puedan ocurrir efectos secundarios. Un servidor que se ejecuta de todos modos tiene un error que quieres conocer ahora, no en producción. Si tus herramientas tienen efectos secundarios incluso con entrada inválida, ejecuta --no-probe y soluciona eso.

API programática

import { runChecks } from "mcp-flightcheck";

const report = await runChecks(client, "my-server", {
  timeoutMs: 10_000,
  probe: true,
  probeLimit: 10,
});
console.log(report.summary); // { pass, warn, fail, skip }

Cómo se prueba

mcp-flightcheck se valida contra un corpus de conformidad: una galería de servidores MCP ficticios en examples/, cada uno representando un arquetipo (limpio, esquema faltante, sin validación de entrada, falla al llamar, se cuelga al llamar, miente sobre capacidades, sin ping, herramientas sin documentar, anónimo, se cuelga en método desconocido). Cada uno está vinculado al veredicto exacto que mcp-flightcheck debe devolver, y test/corpus.test.ts afirma que mcp-flightcheck reproduce cada uno. Esta es la propia puerta de precisión/recuperación de mcp-flightcheck: una regresión que deja de detectar un defecto, o comienza a marcar un servidor limpio, falla la compilación.

Ve toda la galería ejecutarse en vivo contra cada arquetipo:

npm run demo

Hoja de ruta

• Verificaciones de negociación de versiones entre revisiones del protocolo

• Validación de contenido de recursos y prompts

• --report md para comentarios en PR

• Validación de salida estructurada para herramientas que declaran outputSchema

• Conjunto de datos de fiabilidad público: mcp-flightcheck ejecutado en todo el registro oficial

Licencia

MIT