speckitmcp

A Model Context Protocol server for GitHub Spec-Kit
Bring Spec-Driven Development to any AI coding agent.

Quick Start • Tools • Resources • Prompts • Workflow • Development

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

Install & Build

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

Connect to Your AI Agent

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

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

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

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

Tools

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

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:

Prompts

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

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

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