# Spec-Driven MCP Server

A Model Context Protocol (MCP) server that provides structured project specification management capabilities for AI editors through a specification-driven development workflow.

## Features

- **Specification-Driven Development**: [Kiro Spec-driven development](https://kiro.dev/blog/from-chat-to-specs-deep-dive/) for any AI tool that supports MCP

## Usage

Build a TODO Web app like Microsoft Todo, **using Spec-driven development mode**

Build a TODO Web app like Microsoft Todo, **using Spec-driven development mode**, just want the requirements and tasks stage, and then complete the workflow.

## Tools

### init_spec_project

Initialize the specification-driven project structure and templates.

**Purpose**: Create the foundational directory structure and template files required for specification-driven development.

**Features**:
- Creates `.spec/` and `.spec/template/` directories
- Copies default template files for requirements, design, and tasks
- Idempotent operation (can be safely run multiple times)
- Prepares workspace for subsequent specification generation

**Parameters**: No parameters required

### create_spec

Start a specification-driven development workflow.

**Parameters**:
- `requirements_prompt` (string, optional): User requirement description. Required for requirements stage. Used to convert user requirements into structured specifications.
- `stage` (enum, optional): Jump directly to specified stage ("requirements", "design", "tasks"). If not specified, automatically detects current stage.
- `next_stage` (enum, optional): Specify next stage after completion ("design", "tasks", null). Allows LLM to intelligently choose workflow path based on requirement complexity.

**Workflow Stages**:
1. **Requirements**: Analyze and document functional requirements
2. **Design**: Create technical architecture and implementation approach
3. **Tasks**: Break down implementation into actionable development tasks

**Usage Patterns**:
- Complex features: `requirements → design → tasks`
- Simple features: `requirements → tasks` (skip design)
- Documentation only: `requirements → complete`

## Responsibility Matrix

| Role | Core Position | Primary Responsibilities |
|------|---------------|-------------------------|
| **🤖 LLM** | Intelligent Analyzer & Decision Maker | • Analyze requirement complexity and infer next_stage values<br>• Generate all .spec/*.md file content<br>• Make technical routing decisions based on complexity assessment<br>• Process user requirements into structured requirements_prompt |
| **👤 User** | Requirement Owner & Quality Controller | • Clearly express desired features and functionality<br>• Review generated documentation to ensure it meets actual requirements<br>• Control workflow progress (continue/restart/modify)<br>• Provide project context that influences implementation decisions |
| **🔧 Tool** | Workflow Orchestrator | • Automatically detect current stage and manage requirements → design → tasks progression<br>• Validate workflow dependencies before stage transitions<br>• Provide structured prompts for LLM content creation<br>• Provide clear guidance when dependencies are missing or parameters are invalid |

## Installation & Setup

It is not recommended to install this as a global MCP tool. Please install it in your workspace.

### Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "spec-driven": {
      "command": "npx",
      "args": ["-y", "spec-driven-mcp"],
      "env": {
        "SPEC_ROOT_DIR": "/path/to/workspace"
      }
    }
  }
}
```

### VS Code / Cursor

Add the following to your `.cursor/mcp.json` or VS Code MCP settings:

```json
{
  "mcpServers": {
    "spec-driven": {
      "command": "npx",
      "args": ["-y", "spec-driven-mcp"],
      "env": {
        "SPEC_ROOT_DIR": "/path/to/workspace"
      }
    }
  }
}
```

## Template Customization

Edit template files in the `.spec/template/` directory to customize the generated specification format. Each call to `create_spec` uses the latest template version to generate specification prompts.

**Template Files**:
- `requirements.md`: User story format with acceptance criteria
- `design.md`: Architecture design including component relationships
- `tasks.md`: Implementation checklist with specific actionable tasks

## Development

```bash
pnpm watch    # Development mode with auto-reload

pnpm build    # Production build
```

## License

MIT License