TimurRakhmatullin86/mcp-drill

**Fault injection and reliability testing for MCP servers and AI agents.**
Wrap any Model Context Protocol server in one command; inject timeouts, malformed JSON-RPC,
truncated and corrupted-but-valid tool outputs; measure whether the server degrades cleanly —
and whether your agent *notices* or silently acts on the garbage.
MCP is JSON-RPC over stdio/SSE with bidirectional notifications, so ordinary HTTP fault-injectors
and chaos tools don't fit. mcp-drill speaks MCP: it sits transparently between an MCP client and
a backend server and perturbs the traffic, so you can test failure paths in CI without a live LLM.
> **Finding:** across 31 popular MCP servers (including Microsoft Learn, Hugging Face, Cloudflare and
> DeepWiki), only **3% of tools declare an output contract that would reject a corrupted response**.
> See the live scorecard.
Why
Real MCP deployments fail in ways integration tests never cover: a tool times out, a server
returns a well-formed-but-wrong payload, a response is truncated mid-stream. Most agents were
never exercised against these paths. mcp-drill makes them reproducible:
- 🧪 **Fault injection** — deterministically inject timeouts, malformed/oversized/truncated
responses, corrupted-but-schema-valid payloads, dropped tools, and latency.
- 🎬 **CI-first** — a CLI and a GitHub Action; no live model or API keys required in the loop.
- 📊 **Reliability scorecard** — a model-free scan that grades how a server responds to bad
input and how machine-checkable its tool output contracts are.
Install
Quickstart
What it measures (model-free)
The scan command is deterministic and involves no language model, so its numbers are properties
of the server and the protocol — not of whichever agent happens to call it:
1. **Error conformance** — on invalid requests (unknown method, unknown tool, missing required
arguments), does the server return a spec-compliant JSON-RPC error, a proper tool error, or
does it hang / crash / answer as if nothing was wrong?
2. **Output-contract coverage** — what fraction of a server's tools declare a machine-checkable
outputSchema at all? Tools without one give downstream validators nothing to check.
3. **Output-contract enforceability** — of the tools that declare an outputSchema, how many would