Skip to main content
Glama

spec-trace-mcp

An MCP server and CLI that link the acceptance criteria in your spec to the tests that cover them.

Coding agents are quick to say "done". When the work started from a written spec, the useful question is whether every requirement in it has a test. spec-trace answers that with stable IDs: a requirement is a Markdown list item such as - [AC-3] Rows remember their last focused column., and a test covers it by naming the ID, as in it('AC-3 restores the column', ...) or // covers AC-3. The agent can then check its own claim before reporting back, and CI can check it again.

Quickstart

Requires Node 22 or later. Clone the repository, then:

npm install && npm run build
node dist/cli.js check --root examples/cart

Related MCP server: Spec Kit Acceptance Gate MCP

Example output

The examples/cart project has four requirements. CART-4 has no test on purpose, and one test still mentions CART-5, a requirement that was cut from the spec:

$ node dist/cli.js check --root examples/cart
4 requirements in 1 spec file: 3 covered, 1 uncovered (2 test files scanned)

Uncovered requirements:
  CART-4  SPEC.md:18  Removing the last unit of an item removes its line from the cart.

References to IDs the spec does not declare:
  CART-5  tests/discount.test.ts:9 (in "CART-5 gives free shipping over $50")

FAIL: 1 uncovered, 1 warning.

The exit code is 1, so the same command fails a CI job. Through MCP, an agent asking about a single requirement gets:

trace_requirement { "id": "CART-2" }
CART-2  SPEC.md:10  The subtotal is the sum of each line's unit price times its quantity, in cents.
Referenced by 1:
  tests/cart.test.ts:10 (in "adds up price times quantity")

Tools

Tool

What it returns

list_requirements

Every requirement with ID, text, spec file and line. Optional file filter.

trace_requirement

The tests that reference one ID (file, line, enclosing test name). Unknown IDs get close matches.

coverage_gaps

Uncovered requirements, test references to undeclared IDs (typos, stale tests) and duplicate IDs.

suggest_test_stub

A failing Vitest or Jest skeleton that names the ID, plus the test file that covers the nearest requirement. Text only.

Every tool is read only, validates its input with zod, and returns a text summary plus structured JSON. Lists are capped at 200 items by default (limit raises it) and say how many were left out.

Client setup

Build first, then point your client at dist/index.js. The server reads only inside --root (default: the directory it starts in) and rejects paths that escape it, symbolic links included.

Claude Code:

claude mcp add spec-trace -- node /absolute/path/to/spec-trace-mcp/dist/index.js --root .

--root . resolves against the directory Claude Code starts the server from, which is your project. Add --scope project to write it to the project's .mcp.json for your team.

Cursor (.cursor/mcp.json) and other clients that use the mcpServers JSON format:

{
  "mcpServers": {
    "spec-trace": {
      "command": "node",
      "args": ["/absolute/path/to/spec-trace-mcp/dist/index.js", "--root", "/absolute/path/to/your/repo"]
    }
  }
}

Codex (~/.codex/config.toml) uses the same command and arguments in TOML:

[mcp_servers.spec-trace]
command = "node"
args = ["/absolute/path/to/spec-trace-mcp/dist/index.js", "--root", "/absolute/path/to/your/repo"]

Server and CLI options:

--root <dir>            Project root (default: current directory)
--spec <glob>           Spec files, repeatable (default: SPEC.md)
--tests <glob>          Test files, repeatable (default: *.test.* and *.spec.* for JS and TS, test_*.py, *_test.py)
--max-file-size <bytes> Skip larger files (default: 1048576)

The CLI also takes --json (machine readable report) and --strict (fail on undeclared references and duplicate IDs too). node_modules, dist, build, coverage and .git are never scanned.

Spec format

  • A requirement is a list item (bulleted, numbered or a task box) that starts with a bracketed ID: an uppercase prefix, a dash and a number, such as [AC-3] or [REQ-12].

  • Indented lines that follow belong to the same requirement.

  • IDs in fenced code blocks and inline code are ignored, so docs can show examples.

  • Only prefixes your spec declares count as references, so ISO-8601 in a test is not a typo warning.

How this was built

I built this by directing AI coding agents (Claude Code) from the project's own SPEC.md, written first with 22 acceptance criteria. Every test names the criterion it covers, and CI runs spec-trace check on this repository after the build, so a new requirement without a test fails the pipeline:

$ node dist/cli.js check --root .
22 requirements in 1 spec file: 22 covered, 0 uncovered (8 test files scanned)

OK: every requirement has a test.

Development scripts: npm run lint, npm run typecheck, npm test, npm run build.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Implements GitHub's Spec-Driven Development methodology, transforming natural language requirements into executable specifications, technical plans, and ordered task lists with contract-based validation and progress tracking.
      26 npm
      2
      MIT