mcp-drill

mcp-drill

Injeção de falhas e testes de confiabilidade para servidores MCP e agentes de IA. Envolva qualquer servidor Model Context Protocol em um único comando; injete timeouts, JSON-RPC malformado, respostas truncadas e corrompidas-mas-válidas de ferramentas; meça se o servidor degrada de forma limpa — e se seu agente percebe ou age silenciosamente com base no lixo.

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

MCP é JSON-RPC sobre stdio/SSE com notificações bidirecionais, então injetores de falhas HTTP comuns e ferramentas de caos não se aplicam. mcp-drill fala MCP: ele se posiciona de forma transparente entre um cliente MCP e um servidor backend e perturba o tráfego, para que você possa testar caminhos de falha em CI sem um LLM ao vivo.

Descoberta: em 31 servidores MCP populares (incluindo Microsoft Learn, Hugging Face, Cloudflare e DeepWiki), apenas 3% das ferramentas declaram um contrato de saída que rejeitaria uma resposta corrompida. Veja o placar ao vivo.

Por quê

Implementações MCP reais falham de maneiras que os testes de integração nunca cobrem: uma ferramenta expira, um servidor retorna um payload bem-formado-mas-errado, uma resposta é truncada no meio do fluxo. A maioria dos agentes nunca foi exercitada contra esses caminhos. mcp-drill os torna reproduzíveis:

• 🧪 Injeção de falhas — injete deterministicamente timeouts, respostas malformadas/grandes/truncadas, payloads corrompidos-mas-válidos-no-esquema, ferramentas removidas e latência.
• 🎬 CI em primeiro lugar — uma CLI e uma GitHub Action; nenhum modelo ao vivo ou chaves de API necessários no fluxo.
• 📊 Placar de confiabilidade — uma varredura sem modelo que avalia como um servidor responde a entradas ruins e quão verificáveis por máquina são seus contratos de saída de ferramentas.

Instalação

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

Início 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

O que ele mede (sem modelo)

O comando scan é determinístico e não envolve nenhum modelo de linguagem, então seus números são propriedades do servidor e do protocolo — não de qualquer agente que por acaso o chame:

1. Conformidade de erros — em solicitações inválidas (método desconhecido, ferramenta desconhecida, argumentos obrigatórios ausentes), o servidor retorna um erro JSON-RPC em conformidade com a especificação, um erro de ferramenta adequado, ou ele trava / quebra / responde como se nada estivesse errado?
2. Cobertura do contrato de saída — que fração das ferramentas de um servidor declara um outputSchema verificável por máquina? Ferramentas sem um não dão nada para validadores downstream verificarem.
3. Aplicabilidade do contrato de saída — das ferramentas que declaram um outputSchema, quantas realmente rejeitariam uma resposta corrompida (bem-tipada mas errada)? Muitos esquemas declarados validam apenas a forma, então um payload corrompido ainda passa no contrato do próprio servidor.

Status

Desenvolvimento inicial. O núcleo do proxy/injetor é stdlib puro; a pontuação de esquemas usa jsonschema (o extra scan). Telemetria está desligada — a ferramenta nunca envia dados para casa. Veja vs mcp-scan para saber como mcp-drill (conformidade de contrato) difere de mcp-scan (segurança).

Licença

Apache-2.0 (veja LICENSE).