MCP Server

The reqstool MCP server exposes requirements, SVCs, MVRs, and traceability status as Model Context Protocol tools. AI agents such as Claude or GitHub Copilot can call these tools directly to query and reason over a requirements dataset.

See also: reqstool-ai — a marketplace of AI agents, prompts, and plugins built on reqstool and reqstool+OpenSpec integrations.

Starting the Server

Installation

The MCP server is included in the reqstool package:

pip install reqstool

Local project

reqstool mcp local -p /path/to/reqstool

The server starts and blocks, serving MCP requests over stdio. The project at the given path is loaded at startup and reloaded whenever its files change — see Snapshot Freshness.

Other sources

All location types supported by the CLI are accepted:

reqstool mcp git --url https://github.com/example/repo --path docs/reqstool
reqstool mcp pypi --package my-lib --version 1.2.3
reqstool mcp maven --group com.example --artifact my-lib --version 1.2.3

Auto-detect (no source)

When called with no source argument, the server searches for a .reqstool-ai.yaml config file in the current working directory or any parent:

reqstool mcp

Tools

Listing Tools

`list_requirements`

Returns a lightweight list of all requirements.

Parameters:

urn (string, optional) — scope to a single project node
lifecycle_state (string, optional) — filter by state: draft, effective, deprecated, obsolete

Returns: array of { id, title, lifecycle_state }

`list_svcs`

Returns a lightweight list of all software verification cases.

Parameters:

urn (string, optional)
lifecycle_state (string, optional) — draft, effective, deprecated, obsolete

Returns: array of { id, title, lifecycle_state, verification }

where verification is one of automated-test, manual-test, review.

`list_mvrs`

Returns a lightweight list of all manual verification results.

Parameters:

urn (string, optional)
passed (boolean, optional) — true for passing, false for failing

Returns: array of { id, passed }

`list_annotations`

Returns all @Requirements implementation annotations found in source code.

Parameters:

urn (string, optional)

Returns: array of { req_id, req_urn, element_kind, fqn }

`list_urns`

Returns all URNs in the project graph with metadata and file paths.

Parameters: none

Returns: array of { urn, variant, title, url, location: {type, uri}, file_paths }

Detail Tools

`get_requirement`

Full details for a single requirement.

Parameters:

id (string, required) — bare requirement ID, e.g. REQ_010

Returns: { type, id, urn, title, significance, description, rationale, revision, lifecycle, categories, implementation, references, implementations, svcs, location, source_paths }

`get_svc`

Full details for a single SVC.

Parameters:

id (string, required)

Returns: { type, id, urn, title, description, verification, instructions, revision, lifecycle, requirement_ids, test_annotations, test_results, test_summary, mvrs, location, source_paths }

Each entry in mvrs is { id, urn, passed, date, comment, superseded }. date is an RFC 3339 date-time string or empty string; superseded: true means an older entry that was superseded by a later one.

`get_mvr`

Full details for a single MVR.

Parameters:

id (string, required)

Returns: { type, id, urn, passed, date, comment, svc_ids, location, source_paths }

date is an RFC 3339 date-time string, or an empty string if the MVR has no date.

`get_urn_details`

Full details for a URN: metadata, file paths, and entity counts.

Parameters:

urn (string, required)

Returns: { urn, variant, title, url, location, file_paths, counts: { requirements, svcs, mvrs, impl_annotations, test_annotations } }

Status Tools

`get_status`

Overall traceability status across all requirements — completion counts, test totals.

Parameters: none

Returns: status summary dict, plus a snapshot field describing the data it was computed from: { built_at, reload, tracked_files, warnings }. See Snapshot Freshness.

`refresh`

Forces an immediate reload of the project from disk. Reloading is automatic when input files change, so this is only needed to reload unconditionally or to confirm what is being served.

Parameters: none

Returns: { built_at, reload, tracked_files, warnings }

`get_requirement_status`

Status for a single requirement, derived from the same verdict computation as the status CLI command — get_status, get_requirement_status, and get_requirements_status always agree.

Parameters:

id (string, required)
include_post_build (boolean, optional, default false) — also scope to post-build-phase SVCs, for parity with status --with-post-tests

Returns: { id, lifecycle_state, completed, implementations, implementation_type, automated_tests: {total, passed, failed, skipped, missing, not_applicable}, manual_tests: {total, passed, failed, skipped, missing, not_applicable} }

`get_requirements_status`

Batch status for all requirements. Returns the same fields as get_requirement_status for every requirement in the dataset. Use this to find incomplete, partially tested, or unimplemented requirements without N+1 individual calls.

Parameters:

urn (string, optional) — scope to a single project node
include_post_build (boolean, optional, default false) — same as get_requirement_status

Returns: array of { id, urn, lifecycle_state, completed, implementations, implementation_type, automated_tests, manual_tests }

Example: Finding Incomplete Requirements

The following client-side filter finds requirements that have started but are not yet done — they have an implementation and at least one passing automated test, but are still not completed (e.g. due to missing or failing tests for other SVCs):

statuses = get_requirements_status()

in_progress = [
    r for r in statuses
    if not r["completed"]
    and r["implementation_type"] != "N/A"
    and r["automated_tests"]["passed"] > 0
]

Snapshot Freshness

An MCP server is typically spawned by an AI harness and left running for days, while builds regenerate annotations.yml and JUnit XML underneath it. The server therefore records which local files it parsed — including files it looked for and did not find, and the concrete files each test_results pattern matched — and re-checks them before answering each request. If anything changed, the project is reloaded first.

Consequences worth knowing:

Files that appear later count as changes. A server started before the first build picks up the annotations.yml that build produces; it does not keep reporting zero implementations.
A project that no longer parses is an error, not a stale answer. If the sources changed but the new state cannot be loaded — a half-written YAML file, say — tools fail with the parse error rather than answering from the superseded snapshot. Fixing the file restores service on the next call.
Absent build artifacts are reported, not counted as zero. When a configured test_results pattern matches no files, get_status says so under snapshot.warnings instead of silently reporting a project with no tests.
Only local sources are watched. Remote sources (git, maven, npm, pypi) are version-pinned downloads, so they are never treated as stale. Use refresh to reload those.

reqstool-ai

reqstool-ai provides a marketplace of AI agents, prompts, and plugins built on the reqstool MCP server. This includes integrations with OpenSpec for requirement-driven API design and code generation workflows.