Chaos-MCP

What it does ​

Code coverage measures which lines execute, rather than which behaviours the tests verify. For example, replacing > with >= may leave the suite passing. That result identifies a change the current tests do not detect.

Chaos-MCP applies these changes systematically through three tools: audit_code_resilience audits one file, triage_test_coverage ranks a source tree by test weakness, and estimate_audit estimates mutant counts and run time before an audit. Each surviving mutant identifies a line and change that the tests did not detect, providing a concrete starting point for review.

Every run uses a sandbox without modifying your working tree. Before an engine runs, Chaos-MCP verifies that the target file's resolved path is inside the sandbox. 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. Container execution does not require the engine toolchain on the host.

Quick start ​

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

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 ​

These two calls were executed against the Chaos-MCP source code.

Estimate the number of mutants without running mutation testing:

Call (estimate_audit):

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

Result:

{
  "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):

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

Result:

{
  "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 ​

The Rust estimate is exact because cargo-mutants --list enumerates the mutants it will generate; the other three estimate from a source heuristic. The audit may score fewer Rust mutants than the estimate when compilation failures remove mutants from the denominator. These are reported as incompetent rather than counted as killed.

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 throwing an error when the threshold is not met.

Configuration ​

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

{
  "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 set how many surviving mutants a report shows, and from which severity upward it shows them. container.mode: "auto" uses a container whenever the configured runtime is reachable, and falls back to native execution otherwise.