Chaos-MCP

Break your code on purpose, and find out what your tests never noticed.

Chaos (Χάος) is the first thing that existed in Greek cosmogony, the yawning void Hesiod puts before everything else in the Theogony. Order came out of it, not the other way round. The name means 'gap' or 'chasm', which is also what this tool looks for.
  • TypeScript
  • MCP
  • StrykerJS
  • cosmic-ray
  • cargo-mutants
  • Infection

LiveMIT

GitHub (opens in a new tab)README (opens in a new tab)Changelog (opens in a new tab)

What it does ​

Chaos-MCP is an MCP server with three tools: audit_code_resilience (audit one file), triage_test_coverage (rank a whole tree weakest-first), and estimate_audit (a cheap pre-flight mutant count and timing estimate). It runs isolated mutation testing against your source: it deliberately injects small logical faults, such as changing > to >=, and checks whether your existing tests catch them. A mutant that survives marks a gap your coverage number never showed you.

Every run happens in a sandbox: your real working tree is never touched, and the target file's real path is verified to sit inside that sandbox before any engine runs. Four mutation engines cover four ecosystems: StrykerJS for TypeScript and JavaScript, cosmic-ray for Python, cargo-mutants for Rust, and Infection for PHP, each usable natively or through a pinned container image, so the host never needs the toolchain installed.

Quick start ​

Chaos-MCP is not yet published to npm, so install it from source.

bash
git clone https://github.com/AraneaDev/Chaos-MCP.git
cd Chaos-MCP
npm install
npm run build
claude mcp add chaos-mcp -- node /absolute/path/to/Chaos-MCP/build/index.js

Examples ​

Two calls, both run for real against Chaos-MCP's own source.

A quick pre-flight estimate, with no mutation run involved:

Call (estimate_audit):

json
{ "filePath": "src/utils/path-safety.ts" }

Result:

json
{
  "target": "src/utils/path-safety.ts",
  "language": "typescript",
  "mutants": 36,
  "fidelity": "approx",
  "basis": "source heuristic: 31 constructs",
  "note": "Approximate mutant count from a source-parse heuristic; the real audit may differ. Run audit_code_resilience for exact results."
}

A full audit of a small file:

Call (audit_code_resilience):

json
{ "filePath": "src/utils/ignore-dirs.ts", "maxSurvivors": 5 }

Result:

json
{
  "target": "src/utils/ignore-dirs.ts",
  "mutationScore": "100.00%",
  "summary": { "total": 8, "killed": 8, "survived": 0 },
  "survivors": [],
  "noCoverage": [],
  "note": "No surviving mutants — the test suite caught every mutation.",
  "runId": "f17fcb15"
}

Capabilities ​

ToolWhat it does
audit_code_resilienceMutates one file and reports, per line, which mutants your tests killed and which survived
triage_test_coverageRanks a whole tree weakest-first, with optional git-diff scoping
estimate_auditA quick estimate of the mutant count and, optionally, the run time, ahead of a full run
LanguageEngineestimate_audit fidelity
TypeScript/JavaScriptStrykerJSapprox
Pythoncosmic-rayapprox
Rustcargo-mutantsexact
PHPInfectionapprox

Every audit can run inside a pinned container instead of natively on the host. A runId from an earlier audit lets you re-verify exactly those surviving mutants once you have added tests. Mutants that are logically equivalent to the original can be suppressed, after which they stay out of the score. minScore turns any audit or triage into a pass/fail field for CI, without ever throwing an error itself.

Configuration ​

Chaos-MCP reads chaos-mcp.config.json from your workspace root.

json
{
  "defaultTimeoutMs": 300000,
  "mutatorDenylist": ["StringLiteral"],
  "concurrency": 4,
  "defaultMaxFiles": 25,
  "defaultMaxSurvivors": 10,
  "defaultSeverityFloor": "medium",
  "container": {
    "mode": "auto",
    "runtime": "docker",
    "cpus": 2,
    "memoryMb": 4096
  }
}

mutatorDenylist excludes mutator types globally. defaultMaxSurvivors and defaultSeverityFloor cap how many surviving mutants a report shows and from which severity upward. container.mode: "auto" uses a container whenever the configured runtime is reachable, and falls back to native execution otherwise.