local-dev

Local dev — mutmut-mcp

Durable record of the onboarding run (2026-09-06). Everything below was executed and verified in the sandbox; re-run it the same way.

Environment

• Python >= 3.10 required; the sandbox venv uses 3.13.14 and deps + all tests pass on it.
• uv 0.12.10 at ~/.local/bin/uv (bootstrap: curl -LsSf https://astral.sh/uv/install.sh | sh).
• No external services, no env vars, no ports — stdio MCP server.

Bring-up

export PATH="$HOME/.local/bin:$PATH"
make install   # uv venv .venv --seed && uv pip install -e ".[dev]"  — ONCE

Quirk: every make target depends on install, and uv venv errors when .venv already exists. After the first install, run the tools directly:

uv run ruff check .
uv run ruff format --check .
uv run pytest tests/ -v

or UV_VENV_CLEAR=1 make test to rebuild the venv every time.

Start the server

uv run mutmut_mcp.py   # stdio JSON-RPC; equivalent: .venv/bin/mutmut-mcp

No HTTP port — clients speak MCP over stdin/stdout. Smithery and the Dockerfile use python mutmut_mcp.py the same way.

Primary-flow verification (MCP session)

Fixture pattern (mirrors tests/test_integration.py): foo.py with 3 functions, test_foo.py testing two of them, setup.cfg containing [mutmut] + source_paths=foo.py. Then drive the spawned server with fastmcp's client:

import os
from fastmcp import Client
from fastmcp.client.transports import StdioTransport

transport = StdioTransport(command=".venv/bin/python", args=["mutmut_mcp.py"], cwd=".")
async with Client(transport) as client:
    tools = await client.list_tools()  # expect the 7 tools
    await client.call_tool(
        "run_mutmut",
        {
            "options": "--max-children 1",  # no target = full run
            "project_path": "<fixture dir>",
            "venv_path": ".venv",  # repo venv holds mutmut + pytest
        },
    )
    print(await client.call_tool("show_results", {"project_path": "<fixture dir>", "venv_path": ".venv"}))