spec-trace
Generates failing Jest test stubs that name a requirement ID, and scans Jest test files for references to requirements.
Parses Markdown spec files (default SPEC.md) to extract acceptance criteria IDs from list items and link them to covering tests.
Generates failing Vitest test stubs that name a requirement ID, and scans Vitest test files for references to requirements.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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/cartRelated 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 |
| Every requirement with ID, text, spec file and line. Optional |
| The tests that reference one ID (file, line, enclosing test name). Unknown IDs get close matches. |
| Uncovered requirements, test references to undeclared IDs (typos, stale tests) and duplicate IDs. |
| 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-8601in 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Requirements authority for AI coding agents: binding requirements and acceptance criteria.
Spec-driven development for AI coding agents: live requirements, stories and traceability over MCP
Write product documentation to share with your whole team, including testable specifications.
Generate architecture docs, implementation plans, and dev tickets from your project requirements.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceImplements 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 npm2MIT
- FlicenseNot gradedqualityDmaintenanceEnables spec-driven development acceptance gate with structured receipts, audit logs, and reviewer-ready evidence.-
- AlicenseAqualityCmaintenanceEnables turning requirements documents into RFCs, functional test scenarios, and a traceability matrix, with tools to parse, diff, and verify coverage.41MIT
- AlicenseNot gradedqualityDmaintenanceEnables agents to read and create feature specs, track coverage and status, and generate pytest test skeletons from specs without leaving the conversation.3Apache 2.0