mcp-drill

mcp-drill

Inyección de fallos y pruebas de fiabilidad para servidores MCP y agentes de IA. Envuelve cualquier servidor del Model Context Protocol con un solo comando; inyecta tiempos de espera, JSON-RPC malformado, respuestas truncadas y corruptas pero válidas; mide si el servidor se degrada limpiamente — y si tu agente nota el problema o actúa silenciosamente sobre la basura.

uvx mcp-drill wrap --faults timeout,corrupt -- npx -y @modelcontextprotocol/server-filesystem /tmp

MCP es JSON-RPC sobre stdio/SSE con notificaciones bidireccionales, por lo que los inyectores de fallos HTTP ordinarios y las herramientas de caos no encajan. mcp-drill habla MCP: se sitúa de forma transparente entre un cliente MCP y un servidor backend y perturba el tráfico, para que puedas probar rutas de fallo en CI sin un LLM en vivo.

Hallazgo: en 31 servidores MCP populares (incluyendo Microsoft Learn, Hugging Face, Cloudflare y DeepWiki), solo 3% de las herramientas declaran un contrato de salida que rechazaría una respuesta corrupta. Consulta el marcador en vivo.

Por qué

Las implementaciones MCP reales fallan de maneras que las pruebas de integración nunca cubren: una herramienta agota el tiempo, un servidor devuelve un payload bien formado pero incorrecto, una respuesta se trunca a mitad de transmisión. La mayoría de los agentes nunca fueron ejercitados contra estas rutas. mcp-drill las hace reproducibles:

• 🧪 Inyección de fallos — inyecta de forma determinista tiempos de espera, respuestas malformadas/sobredimensionadas/truncadas, payloads corruptos pero válidos según esquema, herramientas eliminadas y latencia.
• 🎬 CI primero — una CLI y una GitHub Action; no se requiere modelo en vivo ni claves API en el bucle.
• 📊 Marcador de fiabilidad — un escaneo sin modelo que califica cómo responde un servidor a entradas malas y qué tan comprobables por máquina son sus contratos de salida de herramientas.

Instalación

pip install mcp-drill[scan]        # or: pipx install mcp-drill[scan]
uvx mcp-drill scan -- --help       # no install, run once
npm i -g mcp-drill                 # shim: prints version + points to PyPI

Inicio rápido

# wrap a server and inject faults into its responses
mcp-drill wrap --faults timeout,truncate -- npx -y @modelcontextprotocol/server-everything

# score a local (stdio) server's fault handling and output-schema hygiene (no LLM involved)
mcp-drill scan -- npx -y @modelcontextprotocol/server-filesystem /tmp

# score a remote server over Streamable HTTP (add --header for auth if needed)
mcp-drill scan --url https://mcp.deepwiki.com/mcp

# emit a shields.io badge for a server's output-contract grade
mcp-drill scan --badge --url https://mcp.deepwiki.com/mcp

Qué mide (sin modelo)

El comando scan es determinista y no involucra ningún modelo de lenguaje, por lo que sus números son propiedades del servidor y del protocolo — no del agente que casualmente lo invoque:

1. Conformidad de errores — ante solicitudes inválidas (método desconocido, herramienta desconocida, argumentos requeridos faltantes), ¿el servidor devuelve un error JSON-RPC conforme a la especificación, un error de herramienta adecuado, o se cuelga / se bloquea / responde como si nada estuviera mal?
2. Cobertura del contrato de salida — ¿qué fracción de las herramientas de un servidor declara un outputSchema comprobable por máquina? Las herramientas sin uno no dan nada que verificar a los validadores posteriores.
3. Aplicabilidad del contrato de salida — de las herramientas que declaran un outputSchema, ¿cuántas realmente rechazarían una respuesta corrupta (bien tipada pero incorrecta)? Muchos esquemas declarados validan solo la forma, por lo que un payload corrupto aún pasa el propio contrato del servidor.

Estado

Desarrollo temprano. El núcleo del proxy/inyector es stdlib puro; la puntuación de esquemas usa jsonschema (el extra scan). La telemetría está desactivada — la herramienta nunca se comunica a casa. Consulta vs mcp-scan para ver cómo mcp-drill (cumplimiento de contrato) difiere de mcp-scan (seguridad).

Licencia

Apache-2.0 (ver LICENSE).