Coverctl MCP server

coverctl

Agent-loop coverage governance for all sorts of languages — coverage your AI coding agent calls before commit, not a dashboard you read after CI.

Works with Python, TypeScript/JavaScript, Java, Rust, Go, C#, C/C++, PHP, Ruby, Swift, Dart, Scala, Elixir, and Shell — one .coverctl.yaml, one MCP surface. Not a Go cover tool.

Get started ↓ · Languages ↓ · What it looks like ↓ · MCP tools ↓ · CLI reference ↓ · Why this exists ↓ · Community ↓

"Our AI agents ship code fast, but they're blind to coverage policy while editing. We only see breakage in CI, after context is gone, and the same agent then guesses its way to a fix."

Same policy model on every language: auto-detect the runner, group paths into domains, enforce mins before commit. Mock-heavy or exotic layouts may need an explicit domains: block in .coverctl.yaml.

coverctl is not a Go cover CLI: it is policy + MCP over each language's native coverage runner (vs go test -cover / pytest --cov).

Get started

brew install klarlabs-studio/tap/coverctl

Wire into Claude Code (~/.config/claude-code/mcp.json):

{
  "mcpServers": {
    "coverctl": {
      "command": "coverctl",
      "args": ["mcp", "serve"]
    }
  }
}

Ask the agent: "Run coverctl check and tell me which domains regressed."

For Cursor / Cline / Claude Desktop / Aider / Continue / OpenCode and other MCP clients, see docs/src/content/docs/mcp.mdx. All MCP-capable clients work; coverctl mcp serve runs in agent mode by default (3 tools: check, suggest, debt). Use --mode=ci for the full nine-tool surface.

Validate the install end-to-end:

coverctl mcp doctor   # PASS/FAIL per step with remediation

What it looks like in the agent loop

Rendered for clarity — your client may format tool-calls differently.

You:    Add the email-validation feature to the api domain.

Claude: I'll add EmailValidator + tests under src/api/.

  [edits: src/api/email.ts, src/api/email.test.ts]

  Tool call → coverctl check
  Result   → passed: false; failing: api (78.2%, required 80%)
             uncovered: src/api/email.ts:42-58 (error paths)

  Tool call → coverctl suggest api
  Result   → uncovered files: email.ts (16 lines), retry.ts (4 lines)

  Two error branches in EmailValidator.validate are uncovered.
  I'll add cases for empty-input and malformed-domain so api meets
  the 80% threshold before we commit.

The regression that used to surface in CI 8 minutes later is fixed in the same agent turn.

The agent does well: reads check output verbatim, calls suggest to find uncovered files, calls debt to rank smallest fixes, re-runs check to confirm.

Watch for: agents lowering thresholds in .coverctl.yaml to "fix" a failure (it's not a fix). Agents claiming coverage rose without a new check call (hallucination). Agents ignoring rejection error_code and retrying with the same input.

coverctl returns deterministic structured signals; the agent's fix still needs a human reading. The full contract is in docs/src/content/docs/mcp.mdx.

Why this exists

AI coding agents write code blind to coverage. They edit, you commit, the regression surfaces in CI minutes or hours later — too late to course-correct in the same session. Dashboards (Codecov, Coveralls) and raw language runners (go test -cover, pytest --cov, nyc) target humans reading numbers after the fact — not agents enforcing policy mid-edit.

Shortened. The full README is on GitHub.