Spec MCP Server
A Model Context Protocol server designed to streamline development workflows through AI-assisted analysis, planning, and verification.
Features
- Tech Steering: Automated codebase analysis and documentation
- Plan Generation: Comprehensive requirement and design documentation
- Task Breakdown: Detailed task generation with dependencies
- Implementation Verification: Automated code review and compliance checking
Installation
- Configure your AI client (Claude Desktop, Cursor, etc.)
- Add the server to your MCP configuration
- Start using the tools through your AI interface
Configuration Examples
Visual Studio Code
Add to your VS Code MCP configuration file:
- Regular VS Code:
~/Library/Application Support/Code/User/mcp.json - VS Code Insiders:
~/Library/Application Support/Code - Insiders/User/mcp.json
{
"servers": {
"spec": {
"command": "npx",
"args": [
"-y",
"spec-mcp@latest"
]
}
}
}
Zed
- Open Zed > Settings > Open Settings (it will open
~/. config/zed/settings.json) - Add a context_servers section to your configuration:
{
"context_servers": {
"spec": {
"source": "custom",
"command": "npx",
"args": ["-y", "spec-mcp@latest"],
"env": {}
}
}
}
Claude Code (CLI)
For Claude Code CLI, use the following command:
claude mcp add spec-mcp --scope user -- npx -y spec-mcp@latest
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"spec": {
"command": "npx",
"args": [
"-y",
"spec-mcp@latest"
]
}
}
}
Workflow
The Spec MCP workflow guides you through complex development tasks like framework migrations, feature implementation, or refactoring. Follow these steps:
1. Analyze Codebase (One-time Setup)
Analyze the existing codebase to create steering documents that guide all future operations.
Prompt: Use Spec MCP to analyze the codebase
This creates three steering documents in .spec/steering/:
product.md- Product overview and business contexttech.md- Technology stack and development guidelinesstructure.md- Project organization and patterns
Note: You can recreate these documents anytime with force_regenerate=true
2. Search Documentation
Search documentation for relevant information about frameworks, APIs, or migration guides using e.g. Context7 MCP.
Prompt: Search docs with Context7 MCP for [topic/framework/library]
3. Generate Tasks
Ask the Spec MCP server to generate a clear, evidence‑driven task list from your goal.
Having your previous analysis in context window you can create tasks from it.
Example prompt:
Generate tasks from the analysis using Spec MCP
Output:
.spec/specs/tasks.md(includes overview, requirements with EARS, implementable tasks, dependencies, and tests)
4. Implement Tasks
Execute tasks systematically using the task orchestrator, which handles dependencies and parallelization.
Prompt: Implement tasks from tasks.md using Spec MCP task orchestrator
The orchestrator will:
- Identify ready tasks based on dependencies
- Execute tasks through task-executor
- Verify completion with task-checker
- Report progress and next available tasks
Available Tools
generate-codebase-analysis
Analyzes codebase and generates three foundational analysis documents: product.md, tech.md, and structure.md in .spec/steering/ directory. These documents provide comprehensive analysis of the product features, technology stack, and project structure.
generate-tasks
Spec MCP: Generate tasks.md (Plan & Task Breakdown)
Generate tasks.md (implementation plan & task breakdown) from your request and codebase. Writes .spec/specs/tasks.md with overview, numbered requirements using EARS, implementable tasks (T‑1…), dependencies/phases, and testing guidance. Use for “task breakdown”, “create tasks.md”, “implementation plan”, or “roadmap”. Inputs:
user_request(required)project_path(optional, defaults to.)
task-orchestrator
Analyzes tasks.md to identify dependencies, parallelization opportunities, and coordinate task execution. Returns a structured execution plan for deploying task executors efficiently.
task-executor
Executes a specific task from tasks.md by providing detailed implementation guidance, requirements, acceptance criteria, and code patterns. This tool focuses on implementing one task thoroughly.
task-checker
Checks if a task can be marked as done by verifying all acceptance criteria checkboxes are checked and optionally running build/tests. Returns PASS or FAIL with clear reasons.
License
MIT