变异测试MCP服务

Mutmut MCP

A Model Context Protocol (MCP) server for managing mutation testing with mutmut. This tool provides a set of programmatic APIs for running mutation tests, analyzing results, and improving test coverage in Python projects. It targets mutmut 3.x: mutants are named (mymodule.x_add__mutmut_1), reported per mutant with a status (killed / survived / no tests / timeout / suspicious / skipped / segfault), and configured through [tool.mutmut] in pyproject.toml.

Features

• Run mutation testing sessions against the projects mutmut 3.x is configured for (source_paths in [tool.mutmut]), not per-target CLI flags
• Show results per mutant name and status, and list surviving mutations, including a labelled section for mutants no test covers
• Show the code diff for a single mutant and rerun one mutant, all survivors, or the survivors no test covers
• Rank survivors and uncovered mutants by likely materiality so an agent knows what to look at first
• Clean mutmut's per-project state (mutants/ and the legacy cache) without touching other projects
• Serialize concurrent runs: two mutmut operations against the same project never race; the second gets a structured busy error
• Classify every failure by its explicit channel — non-zero exit, exception, or local validation — never by sniffing output text
• Practices what it preaches: this repository's own CI runs the server against itself with source_paths = ["mutmut_mcp.py"] and fails on mutation-strength regressions (see How this server tests itself)

Install

# Run directly from GitHub (no install needed)
uvx --from git+https://github.com/wdm0006/mutmut-mcp mutmut-mcp

# Or install from source
git clone https://github.com/wdm0006/mutmut-mcp
cd mutmut-mcp
uv sync
uv run mutmut_mcp.py

Installing via Smithery

To install mutmut-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @wdm0006/mutmut-mcp --client claude

MCP Client Configuration

{
  "mcpServers": {
    "mutmut": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/wdm0006/mutmut-mcp", "mutmut-mcp"]
    }
  }
}

API / Tools

The following tools are available:

• run_mutmut(target, options="", venv_path=None, project_path=None) – Run a mutation testing session (mutmut run) for the project; survivors are expected and are a result, not a failure
• show_results(venv_path=None, project_path=None) – Show the last campaign's results per mutant name and status
• show_survivors(venv_path=None, project_path=None) – List surviving mutations, plus a labelled section for mutants no test covers
• rerun_mutmut_on_survivor(mutation_id=None, venv_path=None, project_path=None) – Rerun a specific mutant (mutmut run <name>) or all surviving mutants
• clean_mutmut_cache(venv_path=None, project_path=None) – Remove mutmut's mutants/ state directory and legacy cache for the project
• show_mutant(mutation_id, venv_path=None, project_path=None) – Show the code diff and details for one named mutant
• prioritize_survivors(venv_path=None, project_path=None) – Rank survivors and uncovered mutants by likely materiality, highest score first
• mutation_score(venv_path=None, project_path=None) – Killed/total counts and the mutation score (null when there are no results or the run is incomplete) from one mutmut results --all true read

project_path

Every tool accepts an optional project_path: the directory containing the project's mutmut configuration ([tool.mutmut] in pyproject.toml), its source, its tests, and mutmut's mutants/ state directory. Mutmut runs with that directory as its working directory, and clean_mutmut_cache removes state only from inside it.

Pass it whenever the server was not launched from the project directory — which is typical for desktop MCP clients and uvx. Omitted, the tools fall back to the server process's working directory, so existing calls behave as before. A project_path that is not an existing directory returns an error without running mutmut or deleting anything.

venv_path

venv_path points at the virtual environment holding the project's mutmut (the tools use <venv>/bin/mutmut, or <venv>\Scripts\mutmut.exe on Windows); omitted, mutmut is taken from PATH. A relative venv_path is resolved against project_path when both are given, so the common .venv form works:

{ "project_path": "/home/me/src/myproject", "venv_path": ".venv" }

How this server tests itself

The repository's own [tool.mutmut] configuration points mutmut at the server module (source_paths = ["mutmut_mcp.py"]), so CI runs the mutation-testing server against itself. The campaign result is scored by scripts/mutation_budget.py, which reuses the server's own strict results parser and fails the build when the number of undetected mutants (survived or no tests) exceeds a fixed budget. The six allowed survivors are equivalent mutants, each documented in docs/mutation-waivers.md; anything new is a regression and must be killed by a named test or waived with a written reason.

Locally, the same loop is available via make mutate; make coverage enforces the measured 100% line-coverage floor, and make typecheck runs mypy.

License

This project is licensed under the MIT License. See LICENSE for details.