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> • <a href="#tools">Tools</a> • <a href="#resources">Resources</a> • <a href="#prompts">Prompts</a> • <a href="#the-sdd-workflow">Workflow</a> • <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