# quelltest MCP server and hooks for coding agents

> Run quell mcp so Claude Code, Cursor or any MCP client can call find, verify and gate, and block an agent from finishing with weakened tests via a Stop hook.

Canonical page: https://quelltest.com/docs/npm/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?

```bash
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:

```json
{
  "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?

| Tool | Arguments | What it returns |
| --- | --- | --- |
| `find` | `path` (default `.`), `diff` (git ref), `coverage` (path), `top` (default 10) | The score summary and the top candidates (`file`, `line`, `function`, `category`, `rule`, `suggestion`, `risk`), plus `more`: how many were left out. Candidates your tests already run are hidden when coverage evidence exists. |
| `verify` | `test`, `source` (both required), `functions`, `runner` (`node`, `jest`, `vitest`, `mocha`), `min_score` | A JSON summary (`verified`, `reason`, `killed`, `total`, `mutationScore`, `isolation`) followed by the Markdown [handoff](https://quelltest.com/docs/npm/verify.md): every surviving mutant with an instruction for strengthening the test. |
| `gate` | `diff` (required), `strict` | The gate result `{ issues, ok, checked }`; see [the test gate](https://quelltest.com/docs/npm/gate.md). |

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`:

```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:

```bash
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](https://quelltest.com/docs/npm/rules.md).

## Where does the same check run in CI?

In pull requests, with `gate` and `find --diff`: see [CI integration](https://quelltest.com/docs/npm/ci.md). The Python package has its own agent integration: [MCP server and Claude Code plugin](https://quelltest.com/docs/mcp.md).