spec-trace
by csanborn
README.md
# 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:
```sh
npm install && npm run build
node dist/cli.js check --root examples/cart
```
## 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:
```text
$ 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:
```text
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:
```sh
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:
```json
{
"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:
```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:
```text
--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](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:
```text
$ 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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data