Local MCP

The MCP (Model Context Protocol) server enables AI coding assistants to work with your requirements—searching, validating, composing, and tracking coverage without leaving your development environment.

Setup

Run the interactive setup:


dotreq mcp-setup

This will:

Prompt you to select your AI assistant
Configure the MCP server for that assistant
Optionally install workflow skills

After setup, restart your AI assistant to load the new configuration.

Supported Assistants

Assistant	Configuration
Claude Code	Auto-configured via `claude mcp add-json`
Claude Desktop	Edits config at `~/Library/Application Support/Claude/`
Cursor	Edits `.cursor/mcp.json` in project
Google Antigravity	Edits `~/.gemini/antigravity/mcp_config.json`
OpenAI Codex	Auto-configured via `codex mcp add`
GitHub Copilot	Manual config needed; skills installed

Workflow Skills

During setup, you can install three workflow skills that guide your AI assistant through common tasks:

Skill	Trigger	Purpose
`dotreq-overview`	Understanding system behavior	Explore what requirements exist and what’s tested
`dotreq-requirements`	Adding new functionality	Compose requirements before implementation
`dotreq-tests`	Validating behavior	Write tests that reference requirements

Skills are installed to platform-specific directories (.claude/skills/, .cursor/skills/, etc.) and are strongly recommended for getting the most out of the MCP integration.

Available Tools

Exploration

Tool	Description
`list_all_requirements`	Get summary of all requirements in the project
`get_requirement`	Get a requirement tree with test coverage info
`search_requirements`	Search by text or regex across IDs, content, and labels
`get_requirements_by_test`	See which requirements a test file references
`get_tests_by_requirement`	Find tests that reference a specific requirement
`list_untested_requirements`	Find requirements without test coverage

Authoring

Tool	Description
`create_requirement_document`	Get a Markdown template with format examples
`validate_requirements`	Check file syntax offline (no network required)
`style_check`	AI-powered style feedback on requirements or tests
`push_requirements`	Push local changes to cloud (shows diff preview first)

Coverage

Tool	Description
`get_requirement_coverage`	Get coverage data for a specific requirement
`get_project_coverage_summary`	Project-wide coverage stats with branch filtering

Test Review

Tool	Description
`review_test`	Semantic validation that tests actually check what requirements specify

Test review validates that:

Setup matches GIVEN conditions
Actions match WHEN triggers
Assertions match THEN outcomes

This catches tests that reference requirements but don’t actually validate them—especially valuable when AI assistants write tests.

Diagnostic

Tool	Description
`debug_mcp_environment`	Debug MCP server configuration

Tool Details

`search_requirements`

Search by text or regex pattern:


search_requirements({ query: "login" })
search_requirements({ query: "AUTH-.*", useRegex: true })

Searches requirement IDs, content, and labels.

`get_requirement`

Get a requirement and all its children with coverage info:


get_requirement({ id: "AUTH-LOGIN-1" })
get_requirement({ id: "AUTH-LOGIN-1.0" })

Returns the full tree from the specified node, plus which tests reference each requirement.

`validate_requirements`

Check file syntax without network access:


validate_requirements({ filePath: ".requirements/auth.requirements.md" })

Returns detailed error messages if validation fails. Use this before pushing to catch format issues early.

`style_check`

AI-powered feedback on writing style and clarity:


style_check({ filePath: ".requirements/auth.requirements.md" })
style_check({ filePath: "src/auth.test.ts" })

Works on both requirements files (*.requirements.md) and test files (*.test.*, *.spec.*).

`push_requirements`

Two-step push with diff preview:


// First call: see what will change
push_requirements({})

// Second call: execute the push
push_requirements({ confirmed: true })

Can push all files or a specific file:


push_requirements({ filePath: ".requirements/auth.requirements.md", confirmed: true })

`review_test`

Comprehensive test review checking both style and semantic correctness:


review_test({ testFilePath: "src/auth.test.ts" })

Loads referenced requirements and validates that test implementation actually checks what the requirement specifies—not just that it references the requirement.

Manual Configuration

If your AI assistant isn’t supported by mcp-setup, configure it manually:

MCP Server Command


npx -y @popoverai/dotrequirements mcp

Or if globally installed:


dotreq mcp

Example Configuration

Most assistants use a JSON configuration like:


{
  "mcpServers": {
    "dotrequirements": {
      "command": "npx",
      "args": ["-y", "@popoverai/dotrequirements", "mcp"]
    }
  }
}

The exact location and format varies by assistant—consult your assistant’s MCP documentation.

What Works Offline

These MCP tools work without cloud authentication:

list_all_requirements
get_requirement
search_requirements
get_requirements_by_test
get_tests_by_requirement
list_untested_requirements
create_requirement_document
validate_requirements

These tools require cloud authentication:

push_requirements
style_check
review_test
get_requirement_coverage
get_project_coverage_summary