Spec Driver MCP

English | 中文 | Русский

A Model Context Protocol server that brings Kiro-style spec-driven development to any AI coding tool (Claude Code, Cursor, opencode, Codex CLI, Reasonix, Gemini CLI, and more).

What it does

Replaces unstructured chat with a 3-phase workflow when you ask AI to build, plan, or refactor a project:

Phase 1: Requirements  →  requirements.md (EARS format: WHEN...THE SYSTEM SHALL...)
Phase 2: Design         →  design.md (architecture, components, data flow)
Phase 3: Tasks          →  tasks.md (trackable [x] checkboxes)

Each phase requires your approval before advancing. Hooks auto-maintain consistency.

Quick Start

1. Install

npx github:linanwanttodo/spec-driver-mcp

Or install globally:

npm install -g github:linanwanttodo/spec-driver-mcp

2. Add to your AI tool

opencode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "spec-driver": {
      "type": "local",
      "command": ["npx", "github:linanwanttodo/spec-driver-mcp"]
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "spec-driver": {
      "command": "npx",
      "args": ["github:linanwanttodo/spec-driver-mcp"]
    }
  }
}

Then copy instructions/CLAUDE.md to your project root as CLAUDE.md.

Cursor

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "spec-driver": {
      "command": "npx",
      "args": ["github:linanwanttodo/spec-driver-mcp"]
    }
  }
}

Then copy instructions/cursor-rules.md to your project root as .cursorrules.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.spec-driver]
command = "npx"
args = ["github:linanwanttodo/spec-driver-mcp"]

Reasonix

Add to ~/.reasonix/config.json mcp array:

"spec-driver=npx github:linanwanttodo/spec-driver-mcp"

Gemini CLI

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "spec-driver": {
      "command": "npx",
      "args": ["github:linanwanttodo/spec-driver-mcp"]
    }
  }
}

Usage

Once configured, just tell your AI:

"帮我开发一个博客系统" or "帮我分析这个项目" or "我们来重构这个"

The AI will automatically:

1. Read your codebase to understand context
2. Ask you clarifying questions (requirements-first or design-first? specific details?)
3. Write requirements.md using EARS notation
4. Wait for your approval before proceeding
5. Write design.md with architecture and component design
6. Wait for your approval
7. Write tasks.md with - [ ] checkboxes
8. Wait for your approval, then implement

Marking tasks done

During implementation:

- [x] Task completed via update-task
- [ ] Still pending

The AI auto-runs hooks at each event:

• on-task-completed → auto-mark task [x], check acceptance criteria
• on-spec-phase-change → validate document completeness
• on-user-request-change → sync all documents

Tools

Tool	Description
init-spec	Initialize .spec/ with config + 3 default hooks
write-spec-file	Write requirements.md / design.md / tasks.md
read-spec-file	Read any spec file
list-spec-files	Show file status + hooks
update-task	Toggle task [x] or [ ]
get-task-summary	Task completion stats
create-hook	Create automation rules
list-hooks	List all hooks
delete-hook	Remove a hook
run-hooks	Execute hooks for an event

Spec File Location

All files are created in .spec/ at your project root:

your-project/
├── .spec/
│   ├── .config              # Project metadata
│   ├── requirements.md       # Phase 1: Requirements
│   ├── design.md             # Phase 2: Design
│   ├── tasks.md              # Phase 3: Tasks
│   └── hooks/                # Automation rules
│       ├── auto-mark-completed.md
│       ├── validate-before-phase.md
│       └── notify-on-change.md
├── ...your code...

Default Hooks

Hook	Event	What it does
auto-mark-completed	on-task-completed	Auto update-task after implementation
validate-before-phase	on-spec-phase-change	Validate doc completeness before advancing
notify-on-change	on-user-request-change	Sync all docs when requirements change

One-Click AI Install Prompt

If you're asking an AI to set this up for you, copy this:

Install spec-driver-mcp from GitHub and configure it:
1. Run: npm install -g github:linanwanttodo/spec-driver-mcp
2. Add "spec-driver" to the MCP servers config of my AI tool
   (the config format depends on which tool I use)
3. Done - no server needed, no API keys, no registration

License

MIT