spec-mcp-server

An MCP server that exposes ATDD spec files from any project so AI assistants can query them directly — no filesystem crawling needed each session.

Part of the Spec-Driven ATDD Toolkit. The toolkit installs the ATDD workflow into your project; this server makes your spec files instantly queryable by AI assistants. Install both for the full experience — see Getting Started Together below.

What it does

spec-mcp-server runs as a stdio MCP server launched by your editor (e.g. VS Code). It reads the specs/ directory of the consuming project and exposes four tools:

| Tool | Description | | ---------------- | ---------------------------------------------------------------------------- | | list-specs | List all feature names with their ATDD phase status | | get-spec | Return the full Gherkin feature file + technical spec for a named spec | | check-coverage | Diff spec scenarios against test files and report missing coverage | | create-spec | Scaffold a new .feature file and technical spec from a requirements string |

Installation

npm install -g spec-mcp-server
# or install locally in the consuming repo
npm install --save-dev spec-mcp-server

Configuration

Add .vscode/mcp.json to your consuming project:

{
  "servers": {
    "spec-mcp-server": {
      "type": "stdio",
      "command": "spec-mcp-server",
      "env": {
        "SPECS_DIR": "${workspaceFolder}/specs"
      }
    }
  }
}

SPECS_DIR must point to the root of the project's specs/ directory. All tool operations are scoped to this path.

Specs directory layout

The server expects this structure inside SPECS_DIR:

specs/
├── features/          # *.feature  — Gherkin scenarios
└── technical/         # *-spec.md  — technical specs

A spec name is the slug used in both file paths — lowercase, hyphen-separated, no extension (e.g. user-auth maps to specs/features/user-auth.feature and specs/technical/user-auth-spec.md).

Tools

list-specs

Lists every .feature file found in specs/features/ with an ATDD phase status.

Input: none

Output:

{
  "specs": [
    { "name": "user-auth", "phase": "implemented" },
    { "name": "billing", "phase": "tests-written" },
    { "name": "reporting", "phase": "spec-only" }
  ]
}

Phase detection (derived from file presence, no test execution):

| Phase | Condition | | --------------- | --------------------------------------------------------------------------------- | | spec-only | .feature file exists; no test file references the spec name | | tests-written | A *.test.ts/js or *.spec.ts/js file contains the spec name as a substring | | implemented | Same as tests-written plus a non-test source file also references the spec name |

get-spec

Returns the full content of a named spec.

Input: { "name": "user-auth" }

Output:

{
  "feature": "Feature: User Auth\n  Scenario: ...",
  "technical": "# user-auth — Technical Spec\n..."
}

technical is null when no *-spec.md file exists for that name.

Errors: SPEC_NOT_FOUND if the .feature file does not exist.

check-coverage

Parses all Scenario: and Scenario Outline: names from the feature file and checks whether any test file contains each name as a substring.

Input: { "name": "user-auth" }

Output:

{
  "specName": "user-auth",
  "totalScenarios": 4,
  "coveredCount": 3,
  "missingCount": 1,
  "covered": ["Successful login", "Login fails for unknown user", "Login fails for wrong password"],
  "missing": ["Login with expired token"]
}

Errors: SPEC_NOT_FOUND if the .feature file does not exist.

create-spec

Scaffolds a new feature file and technical spec from a plain-English requirements string.

Input: { "name": "password-reset", "requirements": "Users can reset their password via an email link" }

Output:

{
  "featurePath": "/path/to/specs/features/password-reset.feature",
  "technicalPath": "/path/to/specs/technical/password-reset-spec.md",
  "message": "Created spec files for \"password-reset\""
}

Rules:

• name and requirements must both be non-empty
• name must be lowercase alphanumeric with hyphens (user-auth, not UserAuth or ../etc)
• Never overwrites existing files — returns ALREADY_EXISTS if either file exists
• Creates specs/features/ and specs/technical/ directories if they don't exist

Errors: VALIDATION_ERROR (bad input), ALREADY_EXISTS (file conflict), MISSING_CONFIG (no SPECS_DIR).

Error codes

All errors return this structure as the tool response content:

{ "error": true, "code": "SPEC_NOT_FOUND", "message": "Spec not found: \"nonexistent\"" }

| Code | Meaning | | ------------------ | ------------------------------------------------------ | | MISSING_CONFIG | SPECS_DIR env var is not set | | SPEC_NOT_FOUND | No .feature file exists for the given name | | VALIDATION_ERROR | name is empty, malformed, or requirements is empty | | ALREADY_EXISTS | create-spec target file(s) already exist |

Development

npm install
npm run build          # compile TypeScript → dist/
npm test               # run Jest test suite
npm run lint           # ESLint
npm run typecheck      # tsc --noEmit

The test suite uses real temporary directories — no mocking of the filesystem.

Getting Started Together

The fastest way to get both tools running in a project:

Step 1 — Install the MCP server globally (once):

npm install -g spec-mcp-server

Step 2 — Install the Spec-Driven Toolkit into your project:

# Clone the toolkit (one time)
git clone https://github.com/kevinMgreer/spec-driven-development-toolkit.git

# Install into your project — this also writes .vscode/mcp.json automatically
cd spec-driven-development-toolkit
./install.sh /path/to/your-project       # macOS / Linux
.\install.ps1 -Target C:\path\to\project # Windows

That's it. The install script configures everything — ATDD workflow files, AI assistant configs, and the MCP server connection.

Step 3 — Open your project in VS Code. The MCP server starts automatically on first use.

Publishing a new version

Tag a release to trigger the npm publish pipeline:

npm version patch   # or minor / major
git push --follow-tags

The GitHub Action builds, tests, and publishes to npm automatically.