quelltest MCP server and hooks for coding agents

quell mcp starts a Model Context Protocol server on stdio that gives a coding agent three tools: find, verify and gate. Use it when an agent writes the code and the tests, so that the check on those tests is something the agent cannot talk its way around. Everything runs locally; the server makes no network calls.

How do I add it to Claude Code?

claude mcp add quelltest -- npx -y quelltest mcp

Any MCP client that can launch a stdio server can run npx -y quelltest mcp. A typical JSON configuration (for example Cursor's .cursor/mcp.json, or a project .mcp.json) looks like this:

{
  "mcpServers": {
    "quelltest": { "command": "npx", "args": ["-y", "quelltest", "mcp"] }
  }
}

Tested how: the server was exercised here over stdio with a scripted client (initialize, tools/list, tools/call for find and gate) and by the package's own tests. The Claude Code and Cursor recipes follow those tools' documented conventions but were not run inside live Claude Code or Cursor sessions. Treat them as a starting point.

The server speaks newline-delimited JSON-RPC. tools/list returns the schemas below; paths are resolved against the working directory the client starts the server in, so launch it from the project root.

What tools does it expose?

A failing call (for example a bad git ref) comes back as a tool result with isError: true and the message quell: .... Malformed JSON, batches and stray responses are answered or ignored without stopping the server.

Typical agent loop:

1. After writing a test, call verify with test, source and the right runner.
2. If verified is false or survivors are listed, strengthen the test using the handoff and call verify again.
3. Before declaring the task done, call gate with diff: "origin/main".

verify runs your tests (once per mutant, in a temporary copy of the project) and can take a while; set the client's tool timeout accordingly. The MCP tool does not expose --command, --timeout or --handoff; use the CLI for those.

How do I block an agent from finishing with weakened tests?

Claude Code runs a Stop hook before the agent finishes; exit code 2 blocks the stop and feeds standard error back to the agent. quell gate prints its findings on standard output, so redirect them to standard error. Add this to .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "npx quell gate --diff origin/main >&2 || exit 2" }
        ]
      }
    ]
  }
}

quell gate exits 5 when it finds weakened tests; || exit 2 turns that into a blocking result. The same line works in Windows cmd. The ref must exist locally (git fetch origin main first in a fresh clone).

To also require that the tests the agent touched really catch faults:

npx quell verify tests/pay.test.js --source src/pay.js --runner jest --min-score 60 --handoff quell-handoff.md >&2 || exit 2

Exit code 4 means not verified. Because the redirect sends the result to the agent, it sees which mutants survived and where quell-handoff.md is.

How do I give agents an escape hatch that stays reviewable?

• // quell-allow-weaken <reason> inside a test exempts it from gate.
• // quell-ignore-mutant <reason> on a source line stops it being mutated by verify.
• // quell-ignore [rule] suppresses a finding from find.

All three leave a comment in the diff that a reviewer can see; see the rule pack.

Where does the same check run in CI?

In pull requests, with gate and find --diff: see CI integration. The Python package has its own agent integration: MCP server and Claude Code plugin.