# 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

```bash
npm install
npm run build
```

### 2. Configure your MCP client

Add the server to your MCP client configuration:

```json
{
  "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

```bash
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
```