speckitmcp

<p align="center"> <h1 align="center">speckitmcp</h1> <p align="center"> A <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server for <a href="https://github.com/github/spec-kit">GitHub Spec-Kit</a><br/> <em>Bring Spec-Driven Development to any AI coding agent.</em> </p> </p>

<p align="center"> <a href="#quick-start">Quick Start</a> &bull; <a href="#tools">Tools</a> &bull; <a href="#resources">Resources</a> &bull; <a href="#prompts">Prompts</a> &bull; <a href="#the-sdd-workflow">Workflow</a> &bull; <a href="#development">Development</a> </p>

---

Overview

speckitmcp bridges GitHub's Spec-Kit toolkit with any MCP-compatible AI assistant — Claude Code, Cursor, VS Code Copilot, Windsurf, and more.

It exposes the full Spec-Driven Development (SDD) workflow as MCP tools, resources, and prompts, so your AI agent can:

• Initialize and manage spec-kit projects
• Author specifications, technical plans, and task breakdowns
• Track implementation progress and mark tasks complete
• Validate cross-artifact consistency with a 6-pass analysis engine
• Generate quality checklists and convert tasks to GitHub issues

All without leaving your editor.

---

Quick Start

Prerequisites

| Requirement | Install | |---|---| | Node.js 18+ | nodejs.org | | spec-kit CLI | uv tool install --from git+https://github.com/github/spec-kit.git specify-cli |

Install & Build

git clone https://github.com/jthom233/speckitmcp.git
cd speckitmcp
npm install
npm run build

Connect to Your AI Agent

<details> <summary><strong>Claude Code</strong></summary>

Add to ~/.claude/settings.json (global) or .claude/settings.json (project):

{
  "mcpServers": {
    "spec-kit": {
      "command": "node",
      "args": ["/absolute/path/to/speckitmcp/dist/index.js"]
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "spec-kit": {
      "command": "node",
      "args": ["/absolute/path/to/speckitmcp/dist/index.js"]
    }
  }
}

</details>

<details> <summary><strong>VS Code / GitHub Copilot</strong></summary>

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "spec-kit": {
      "command": "node",
      "args": ["/absolute/path/to/speckitmcp/dist/index.js"]
    }
  }
}

</details>

<details> <summary><strong>Windsurf / Other MCP Clients</strong></summary>

Point your client's MCP configuration at:

node /absolute/path/to/speckitmcp/dist/index.js

The server communicates over stdio using the standard MCP JSON-RPC protocol. </details>

---

Tools

The server exposes 13 tools that map to every phase of the SDD workflow:

| Tool | Description | |---|---| | speckit_init | Initialize spec-kit project structure | | speckit_check | Check spec-kit installation and system prerequisites | | speckit_version | Get spec-kit CLI version | | speckit_status | View project status with task completion stats | | speckit_constitution | Read, create, or update project constitution with optional version bumping | | speckit_specify | Create feature spec with template loading, script integration, and auto-generated quality checklist | | speckit_plan | Multi-phase planning (research, design, plan) with spec prerequisite and constitution gate | | speckit_tasks | Generate user-story-organized task lists (requires spec.md and plan.md) | | speckit_implement | Read tasks/docs, mark tasks complete with checklist gate, or add notes | | speckit_clarify | Scan spec.md for ambiguities (9 categories, max 5 questions) or answer them inline | | speckit_analyze | Read-only 6-pass analysis: duplication, ambiguity, underspecification, constitution alignment, coverage gaps, inconsistency | | speckit_checklist | Generate requirement quality checklists (spec quality, not implementation) in checklists/ subdirectory | | speckit_tasks_to_issues | Convert tasks.md to GitHub issues (dry-run by default) |

Key Features

• Script integration — Platform-aware bash/powershell helper scripts invoked automatically
• Template loading — Loads templates from .specify/templates/ with embedded fallbacks
• Prerequisites checking — Tools verify prior artifacts exist before proceeding
• Constitution gate — Planning phase reads the project constitution as mandatory context
• Checklist gate — Implementation checks for incomplete checklist items before marking tasks done
• 6-pass analysis engine — Catches duplication, ambiguity, underspecification, constitution violations, coverage gaps, and inconsistencies
• GitHub issue creation — Convert a tasks.md file into GitHub issues via speckit_tasks_to_issues

---

Resources

The server exposes spec-kit project files as read-only MCP resources:

| URI | Content | |---|---| | speckit://constitution | Project constitution | | speckit://templates/{name} | Spec-kit templates | | speckit://specs/{feature}/spec | Feature specification | | speckit://specs/{feature}/plan | Implementation plan | | speckit://specs/{feature}/tasks | Task list | | speckit://specs/{feature}/research | Research notes | | speckit://specs/{feature}/data-model | Data model | | speckit://specs/{feature}/quickstart | Quickstart guide | | speckit://specs/{feature}/checklists/{name} | Quality checklists | | speckit://specs/{feature}/contracts/{name} | API contracts |

---

Prompts

Ten built-in prompts guide your AI agent through each SDD phase:

| Prompt | Purpose | |---|---| | sdd_workflow | End-to-end walkthrough of the full SDD lifecycle | | sdd_specify | Structured feature specification authoring | | sdd_clarify | Guided ambiguity resolution | | sdd_plan | Technical planning with architecture and stack decisions | | sdd_tasks | Task breakdown with phasing, dependencies, and parallelism | | sdd_implement | Task execution and progress tracking | | sdd_checklist | Requirement quality checklist generation | | sdd_analyze | Cross-artifact consistency validation | | sdd_constitution | Guided creation of project principles and governance | | sdd_taskstoissues | Convert tasks to GitHub issues |

---

The SDD Workflow

  init → constitution → specify → clarify → plan → tasks → checklist → analyze → implement → tasks_to_issues

1. Init — speckit_init — Scaffold the project with .specify/ templates
2. Constitution — speckit_constitution — Define project principles and governance before specifying
3. Specify — speckit_specify — Define requirements as prioritized user stories with template loading
4. Clarify — speckit_clarify — Scan for and resolve ambiguities before committing to a plan
5. Plan — speckit_plan — Multi-phase planning gated on project constitution
6. Tasks — speckit_tasks — Generate user-story-organized task lists with prerequisites check
7. Checklist — speckit_checklist — Generate requirement quality checklists
8. Analyze — speckit_analyze — 6-pass validation of spec / plan / tasks alignment
9. Implement — speckit_implement — Track completion with checklist gate and regex-safe marking
10. Tasks to Issues — speckit_tasks_to_issues — Push tasks to GitHub as issues

---

Project Structure

src/
├── index.ts                   # Entry point — stdio transport
├── server.ts                  # MCP server — handler registration
├── cli.ts                     # spec-kit CLI wrapper (child_process)
├── tools/
│   ├── index.ts               # Tool registry
│   ├── init.ts                # speckit_init
│   ├── check.ts               # speckit_check
│   ├── version.ts             # speckit_version
│   ├── status.ts              # speckit_status
│   ├── constitution.ts        # speckit_constitution
│   ├── specify.ts             # speckit_specify
│   ├── plan.ts                # speckit_plan
│   ├── tasks.ts               # speckit_tasks
│   ├── implement.ts           # speckit_implement
│   ├── clarify.ts             # speckit_clarify
│   ├── analyze.ts             # speckit_analyze
│   ├── checklist.ts           # speckit_checklist
│   └── tasks-to-issues.ts     # speckit_tasks_to_issues
├── resources/
│   └── index.ts               # MCP resource handlers
└── prompts/
    └── index.ts               # SDD workflow prompts

---

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript → dist/
npm run dev          # Watch mode (rebuild on change)

Manual Smoke Test

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js

You should see a JSON-RPC response with serverInfo.name: "spec-kit-mcp".

---

Tech Stack

| Layer | Choice | |---|---| | Language | TypeScript 5 (strict mode, ESM) | | Runtime | Node.js 18+ | | Protocol | @modelcontextprotocol/sdk v1.x | | Validation | Zod | | Transport | stdio (JSON-RPC 2.0) | | CLI Integration | Node.js child_process wrapping specify |

---

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes
4. Push to your fork and open a Pull Request

---

License

MIT