spec-builder-mcp

An MCP (Model Context Protocol) server that helps AI assistants plan and document software features using a structured Software Design Document (SDD) approach.

Instead of jumping straight into code, the AI guides you through creating proper documentation — requirements and technical design — before any implementation begins.

How it works

When connected to an MCP-compatible client (e.g. Claude Desktop, Cursor, Junie), the server exposes tools and a workflow prompt that the AI uses to manage feature documentation in your project.

All documents are stored locally in your project under .docs/features/:

your-project/
└── .docs/
    └── features/
        └── user-login/
            ├── requirements.md
            └── technical_design.md

Workflow

1. You trigger the spec_wizard prompt in your MCP client.
2. The AI asks: "What do you want to build?" — or skip this step by passing a file (e.g. @ticket.json, @brief.md), which the AI uses as the basis for the spec.
3. It searches existing feature docs to check if the feature already exists.
4. If it's new, it creates the feature folder with both documents initialised from the built-in templates.
5. Both documents are filled out iteratively (requirements first, then technical design) and saved with spec_update.

Tools

Tool	Description
spec_list	Lists all documented features in .docs/features/
spec_search	Searches feature names and document contents for a query
spec_create	Creates a new feature folder (FEAT-{name}/) with both documents
spec_update	Writes content to an existing feature's requirements.md or technical_design.md
spec_delete	Permanently deletes a feature folder and all its documents

Example

An example specification generated with this tool is included in this repository:

FEAT-spec-wizard/
├── requirements.md       # functional & non-functional requirements for the Spec Wizard itself
└── technical_design.md   # architecture, components, and tool interaction flow

Setup

1. Build

npm install
npm run build

2. Configure your MCP client

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "spec-builder-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/spec-builder-mcp/build/index.js"]
    }
  }
}

3. Use

In your MCP client, select the spec_wizard prompt to begin a guided feature planning session.

Development

npm run build   # compile TypeScript + copy prompt files
npm start       # run the built server

Source structure:

src/
├── index.ts                        # entry point — registers tools and prompt
├── helpers/
│   └── directory.helper.ts         # resolves .docs/features/ path
├── prompts/
│   ├── sdd-workflow.prompt.json    # prompt metadata
│   └── sdd-workflow.prompt.md      # prompt content sent to the AI
├── templates/
│   ├── requirements.md             # template for requirements documents
│   └── technical_design.md        # template for technical design documents
└── tools/
    ├── list-features.tool.ts
    ├── search-feature.tool.ts
    ├── create-feature.tool.ts
    ├── update-feature.tool.ts
    └── delete-feature.tool.ts