AI Agents (MCP)

Quell ships an MCP (Model Context Protocol) server that exposes its tools to AI coding agents. This lets Claude Code, Cursor, Devin, and similar agents check requirement coverage, reproduce bugs, and generate verified tests — all without leaving their workflow.

Install

pip install "quelltest[mcp]"

Start the MCP server

quell-mcp

The server starts on http://localhost:8765 by default.

Configure your agent

Claude Code

Add to your .claude/settings.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "quell": {
      "command": "quell-mcp"
    }
  }
}

Cursor

Add to Cursor MCP settings:

{
  "servers": {
    "quell": {
      "command": "quell-mcp",
      "cwd": "/path/to/your/project"
    }
  }
}

Available tools

check_requirements

Scan a file or directory for uncovered requirements.

Input:
  target: str       — file or directory path
  fix: bool         — generate verified tests for gaps (default: false)

Output:
  requirements: list
  score: float
  uncovered_count: int

reproduce_bug

Convert a plain-English bug description into a verified failing test.

Input:
  description: str  — bug description in plain English
  file: str | None  — optional target source file

Output:
  written: bool
  test_function_name: str
  explanation: str

prove_coverage

Get requirement coverage score for a file or function.

Input:
  file: str         — source file path
  function: str | None — optional function name

Output:
  score: float      — 0.0–1.0
  percentage: int
  grade: str

get_project_score

Get the requirement coverage score for the whole project.

Input:
  (none)

Output:
  percentage: int
  grade: str
  files: list[{file, score, grade}]

Example AI agent session

User: "Our payments.py has poor requirement coverage. Fix it."

Agent (Claude Code with Quell MCP):
  1. Calls check_requirements(target="payments.py")
     → score: 40%, 3 gaps found

  2. Calls check_requirements(target="payments.py", fix=true)
     → 3 verified tests written

  3. Calls prove_coverage(file="payments.py")
     → score: 100%

Agent: "I've generated verified tests for all 3 uncovered requirements
        in payments.py. Coverage improved from 40% to 100%."

SDK for custom agents

If you're building your own agent, use the Python SDK directly instead of the MCP server:

from quell import Quell

q = Quell(llm="anthropic")
result = q.check("src/payments.py", fix=True)
print(f"Score: {result.score:.0%} ({len(result.uncovered)} gaps remaining)")