speckit-mcp
v1.0.2
Published
Specification-driven development MCP server with domain analysis capabilities
Maintainers
Readme
Spec-Kit MCP
An enhanced MCP (Model Context Protocol) server implementing GitHub's spec-kit v0.0.52 methodology with constitution-driven development, structured clarification workflows, comprehensive cross-artifact analysis, and advanced domain analysis capabilities. Automate your spec-driven development workflow with powerful tools for enterprise-grade software delivery and automatic business entity extraction from data files.
Now available as an MCPB bundle for universal installation across AI applications!
What is Spec-Kit MCP (v0.0.52)?
Spec-Kit MCP brings enterprise-grade specification-driven development to any repository with enhanced constitutional governance. The latest v0.0.52 update provides:
Constitution-Driven Development
- Project governance through foundational principles
- Quality standards enforcement across all development phases
- Architectural constraints and decision-making frameworks
Enhanced 8-Phase Workflow
- Constitution - Establish governing principles and standards
- Specify - Create detailed requirements from natural language
- Domain Analysis - Extract business entities and rules from data files
- Clarify - Structured resolution of specification ambiguities
- Plan - Generate comprehensive technical implementation plans
- Tasks - Break down into actionable, dependency-aware tasks
- Analyze - Cross-artifact consistency and coverage validation
- Implement - Execute with constitutional compliance
Key Improvements
- Advanced Domain Analysis - Extract business entities and rules from JSON/CSV data files
- MCPB Bundle Distribution - Universal installation across AI applications
- Interactive Domain Configuration - Setup wizards for financial, ecommerce, CRM domains
- 11 AI agent support (Claude, Copilot, Gemini, Cursor, Qwen, opencode, Windsurf, Kilo Code, Auggie CLI, Roo Code, Codex)
- PowerShell & Shell script variants for cross-platform development
- Structured clarification workflow (replaces /quizme)
- Cross-artifact analysis for consistency and coverage
- Implementation readiness assessment before development
Enhanced Features (v0.0.52)
Domain Analysis Capabilities
- Entity Extraction - Automatically identify business entities from JSON/CSV files
- Business Rule Inference - Generate testable business rules from data patterns
- Integration Mapping - Detect external systems and data flow patterns
- Interactive Validation - User-guided analysis with domain-specific customization
- Template-Driven Analysis - Pre-built patterns for Financial, E-commerce, CRM domains
- Data-Driven Specifications - Populate templates with real extracted entities
MCPB Bundle Distribution
- Universal Installation - Single-click installation across AI applications
- Standardized Interface - MCP protocol compliance for broad compatibility
- Complete Package - Includes tools, templates, sample data, and documentation
- Cross-Platform Support - Windows, macOS, Linux via Python 3.11+
Constitutional Governance
- Project principles guide all development decisions
- Quality standards enforced automatically
- Architectural patterns maintained consistently
- Conflict resolution framework for technical choices
Structured Clarification
- Systematic Q&A workflow for specification ambiguities
- Tracking system for questions and resolutions
- Prevents planning with incomplete requirements
- Reduces implementation rework through upfront clarity
Cross-Artifact Analysis
- Consistency checking between spec, plan, and tasks
- Coverage analysis ensuring complete implementation
- Dependency validation and critical path identification
- Implementation readiness assessment and recommendations
Multi-Agent Support
- 11 AI agents with optimized configurations
- PowerShell & Shell variants for Windows/Linux/macOS
- Agent-specific templates and workflows
- Cross-platform development support
Core Capabilities
- Centralized Workflow: No per-repository installations required
- Git-Integrated: Automatic branch creation and structured file generation
- Natural Language Input: Convert ideas to specifications seamlessly
- Structured Output: Consistent formats across all development phases
- Token Efficient: Optimized for AI model performance
- Test-Driven: Constitutional TDD requirements with automated verification
- Parallel Tasks: Intelligent task dependency analysis
- MCP Prompts: Guided workflows for optimal AI collaboration
- Context-Aware: Phase-specific documentation and governance
Installation and Setup
MCPB Bundle Installation (Recommended)
The easiest way to install Spec-Kit MCP is through the MCPB bundle, which provides universal installation across AI applications:
- Download the MCPB bundle from the releases page
- Install via your MCP-compatible AI application (Claude Desktop, etc.)
- Start using immediately with pre-configured tools and templates
See MCPB_README.md for detailed MCPB installation instructions.
Manual Installation
Prerequisites
- Python 3.11 or higher installed
- Git installed and configured
- Claude Desktop application (or other MCP client)
1. Clone and Install
# Clone the repository
git clone https://github.com/DankeyDevDave/spec-kit-mcp.git
cd spec-kit-mcp
# Install with pip (recommended)
pip install -e .
# Or with development dependencies
pip install -e ".[dev]"Alternative: Using Virtual Environment (recommended for isolation)
python3 -m venv venv
source venv/bin/activate # On macOS/Linux
# or
venv\Scripts\activate # On Windows
pip install -e .2. Test the Installation
# From the project directory
python3 -m speckit_mcpYou should see the FastMCP banner indicating the server is running successfully.
3. Configure Claude Desktop
Locate Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- macOS:
Add the spec-kit server configuration:
{
"mcpServers": {
"spec-kit": {
"command": "python3",
"args": ["-m", "speckit_mcp"],
"cwd": "/path/to/your/spec-kit-mcp",
"description": "Spec-driven development workflow tools"
}
}
}Important: Replace /path/to/your/spec-kit-mcp with your actual project path.
For Virtual Environment Users
If using a virtual environment, modify the command path:
{
"mcpServers": {
"spec-kit": {
"command": "/path/to/your/project/venv/bin/python",
"args": ["-m", "speckit_mcp"],
"cwd": "/path/to/your/project",
"description": "Spec-driven development workflow tools"
}
}
}4. Restart and Verify
- Restart Claude Desktop completely (quit and reopen)
- Verify installation by asking Claude to list available tools
- Test functionality with a simple command like initializing a project
Troubleshooting
Server Not Found:
- Ensure Python 3.11+ is installed:
python3 --version - Verify the project path in the config is correct
- Check that the server runs manually:
python3 -m speckit_mcp
Permission Errors:
- Ensure read/write access to repository directories
- Check git configuration:
git config user.nameandgit config user.email
Tools Not Available:
- Restart Claude Desktop completely
- Check the server appears in Claude's MCP server list
- Review Claude Desktop logs for errors
Python Version Issues:
# Check available Python versions
which python3.11 || which python3.12 || which python3.13
# Use specific version in config
"command": "/opt/homebrew/bin/python3.12"3. Enhanced v0.0.52 Workflow
The server provides a comprehensive 7-phase workflow for spec-driven development:
- Constitution → Establish governing principles
- Specify → Create detailed requirements
- Clarify → Resolve specification ambiguities
- Plan → Generate technical implementation
- Tasks → Break down into actionable items
- Analyze → Verify consistency and coverage
- Implement → Execute with quality assurance
Enhanced Tools & Capabilities (v0.0.52)
Core Workflow Tools
Domain Analysis Tools (NEW v1.0.0)
analyze_domain - Extract Business Entities from Data
Automatically extract business entities, rules, and integration patterns from JSON/CSV data files.
Purpose: Populate specifications with real business entities discovered from your data Input:
{
"data_directory": "./data",
"interactive": false,
"domain_type": "financial", # financial, ecommerce, crm, or auto-detect
"confidence_threshold": 0.75,
"output_format": "detailed" # json, summary, detailed
}Output:
- Extracted business entities with fields and relationships
- Inferred business rules with confidence scores
- Integration points and data flow patterns
- Next steps for specification enhancement
setup_domain_config - Configure Domain Analysis
Interactive setup wizard for domain analysis preferences and templates.
Purpose: Configure domain-specific analysis patterns and preferences Input:
{
"config_directory": ".specify"
}Output:
- Domain configuration file with user preferences
- Template selections and customizations
- Analysis parameters and thresholds
list_domain_templates - Show Available Templates
List pre-built domain templates for common business domains.
Purpose: Show available analysis patterns and domain types Output:
- Financial domain template (invoices, payments, suppliers)
- E-commerce template (orders, products, customers)
- CRM template (contacts, leads, opportunities)
- Template descriptions and entity patterns
constitution_tool - Project Governance (NEW v0.0.52)
Establish foundational principles and governance framework for your project.
Purpose: Create constitutional guidelines that govern all development decisions Input:
{
"repository_path": "/path/to/your/repo",
"principles": "# Project Principles\n- Test-driven development\n- Security-first approach",
"update_mode": "append", # append, replace, merge
"governance_areas": ["security", "performance", "accessibility"]
}Output:
- Creates:
memory/constitution.mdwith governance framework - Creates:
memory/constitution_update_checklist.mdfor tracking changes - Returns: Constitutional sections, governance areas, and compliance guidelines
specify_tool - Requirements Specification
Convert natural language descriptions into structured specifications.
Purpose: Transform ideas into comprehensive, testable requirements Input:
{
"description": "Build a photo album organizer with drag-and-drop functionality",
"repository_path": "/path/to/your/repo"
}Output:
- Creates: Feature branch (e.g.,
001-photo-album-organizer) - Creates:
specs/001-photo-album-organizer/spec.mdwith structured requirements - Returns: Branch name, spec file path, and constitutional alignment status
clarify_tool - Structured Clarification (NEW v0.0.52)
Systematically resolve specification ambiguities before planning.
Purpose: Eliminate unclear requirements through structured Q&A workflow Input:
{
"repository_path": "/path/to/your/repo",
"clarification_questions": '[{"id": "Q1", "question": "Who are the primary users?", "category": "User Personas"}]',
"answers": '[{"id": "Q1", "answer": "Professional photographers and hobbyists"}]',
"complete_clarification": true
}Output:
- Creates:
clarifications.mdwith question-answer tracking - Updates: Specification with clarified information
- Returns: Resolution status and readiness for planning phase
plan_tool - Technical Implementation Planning
Generate comprehensive technical plans from clarified specifications.
Purpose: Create detailed implementation roadmap with constitutional compliance Input:
{
"feature_path": "/path/to/specs/001-photo-album-organizer"
}Output:
- Creates:
plan.mdwith technical architecture and design decisions - Creates:
data-model.mdwith entity definitions and relationships - Creates:
contracts/directory with API specifications - Returns: Plan components, constitutional compliance verification
tasks_tool - Actionable Task Breakdown
Break implementation plans into executable, dependency-aware tasks.
Purpose: Convert plans into systematic task execution with TDD methodology Input:
{
"feature_path": "/path/to/specs/001-photo-album-organizer"
}Output:
- Creates:
tasks.mdwith numbered, prioritized tasks - Includes: Dependency mapping and parallel execution opportunities
- Includes: TDD requirements and quality gates
- Returns: Task count, phases, and execution timeline
analyze_tool - Cross-Artifact Analysis (NEW v0.0.52)
Comprehensive consistency and coverage analysis before implementation.
Purpose: Verify all requirements are properly planned and tasked Input:
{
"repository_path": "/path/to/your/repo",
"analysis_type": "full", # full, consistency, coverage, dependencies
"include_recommendations": true
}Output:
- Analyzes: Consistency between spec, plan, and tasks
- Validates: Requirement coverage and dependency resolution
- Assesses: Implementation readiness with actionable recommendations
- Returns: Analysis report with consistency score and next steps
Supporting Tools
initialize_tool - Project Setup
Initialize repositories with spec-kit configuration and constitutional framework.
Input:
{
"repository_path": "/path/to/your/repo",
"project_name": "My Awesome Project",
"project_type": "web", # single, web, or mobile
"ai_agent": "claude", # claude, copilot, gemini, cursor, etc.
"script_variant": "sh", # sh (shell) or ps (PowerShell)
"create_templates": true
}Output:
- Creates: Project configuration with constitutional framework
- Creates:
specs/directory and template structure - Configures: AI agent-specific workflows and scripts
- Returns: Setup status and configuration paths
get_context_tool - Contextual Information
Provides phase-specific documentation and project state information.
Input:
{
"repository_path": "/path/to/your/repo",
"context_type": "phase", # constitution, phase, specs, feature, templates, status
"phase": "specify" # For phase context: specify, plan, tasks, implementation
}Context Types:
constitution: Get project configuration and principlesphase: Get phase-specific documentation and best practicesspecs: List all specifications in the projectfeature: Get details about a specific featuretemplates: List available templatesstatus: Get workflow status for a feature
Output:
- Context-specific information and documentation
- Current workflow phase and next steps
- Task progress tracking (for status context)
get_task_progress_tool - Progress Tracking
Analyzes task completion across all features with detailed reporting.
Input:
{
"repository_path": "/path/to/your/repo",
"feature_path": "specs/001-photo-album-organizer", # Optional: specific feature
"format_output": true
}Output:
- Overall progress statistics across all features
- Phase-by-phase breakdown (constitution, specify, clarify, plan, tasks, implement)
- Task completion analysis with parallel execution tracking
- Formatted progress report with next action recommendations
validate_compliance_tool - MCP Compliance Validation
Ensures codebase follows MCP specification standards and best practices.
Input:
{
"repository_path": "/path/to/your/repo",
"mcp_spec_version": "2025-06-18",
"include_patterns": ["*.py", "*.json"],
"validation_categories": ["protocol", "schema", "security", "tools"]
}Output:
- Comprehensive compliance report with scoring
- Detailed findings and recommendations for improvement
- MCP specification adherence analysis
- Security and best practices validation
Supported AI Agents (v0.0.52)
Spec-Kit MCP now supports 11 AI agents with optimized configurations:
| Agent | Status | Script Variants | Notes | |-------|--------|----------------|-------| | Claude Code | Full Support | Shell, PowerShell | Primary development and testing | | GitHub Copilot | Full Support | Shell, PowerShell | VS Code integration optimized | | Gemini CLI | Full Support | Shell, PowerShell | Google's AI with advanced reasoning | | Cursor | Full Support | Shell, PowerShell | Code editor with AI integration | | Qwen Code | Full Support | Shell, PowerShell | Alibaba's coding assistant | | opencode | Full Support | Shell, PowerShell | Open-source AI coding platform | | Windsurf | Full Support | Shell, PowerShell | Collaborative AI development | | Kilo Code | Full Support | Shell, PowerShell | Enterprise-focused AI assistant | | Auggie CLI | Full Support | Shell, PowerShell | Documentation and code generation | | Roo Code | Full Support | Shell, PowerShell | Rapid prototyping and development | | Codex CLI | Limited | Shell, PowerShell | Limited slash command support |
Cross-Platform Script Support
- Shell Scripts (
.sh) - Linux, macOS, WSL - PowerShell Scripts (
.ps1) - Windows, Linux, macOS (PowerShell Core) - Agent-Specific Configuration - Optimized workflows per agent
- Template Variants - Customized templates for each platform
Prompts
The server includes MCP Prompts - pre-configured conversation templates that guide AI models through complete spec-driven workflows:
start_new_feature
Guides through creating a new feature from scratch, including project initialization if needed.
Parameters:
feature_description: Natural language description of the featurerepository_path: Path to your git repository
explore_project
Explores and summarizes the current project state, including constitution, specs, and templates.
Parameters:
repository_path: Path to your git repository
⏭️ continue_feature
Continues work on an existing feature, determining the next steps based on current progress.
Parameters:
feature_path: Path to the feature directory (e.g.,specs/001-feature-name)
understand_workflow
Explains the complete spec-driven development workflow with documentation for all phases.
Parameters: None
Why Prompts Matter
MCP Prompts solve a key discoverability issue with tools that have conditional parameters. Instead of AI models struggling to understand which parameters are required for different contexts (e.g., get_context_tool needs different parameters depending on context_type), prompts provide:
- Guided workflows that combine multiple tool calls in the correct sequence
- Clear parameter requirements upfront
- Best practices embedded in the workflow
- Reduced errors from incorrect tool usage
Constitutional Governance (v0.0.52)
Spec-Kit MCP v0.0.52 introduces constitution-driven development - a governance framework that ensures consistent quality and decision-making across all development phases.
Constitutional Principles
# Project Constitution Example
## Core Development Principles
- **Test-Driven Development**: All code changes must include comprehensive tests
- **Security-First**: Security considerations integrated into all phases
- **User-Centric Design**: Features must demonstrate clear user value
- **Performance Standards**: Response times under 200ms for user interactions
- **Accessibility**: WCAG 2.1 AA compliance required
## Architectural Governance
- **Separation of Concerns**: Clear boundaries between layers
- **Dependency Management**: Minimize external dependencies
- **Scalability**: Design for horizontal scaling from start
- **Maintainability**: Code must be self-documenting
## Decision-Making Framework
1. **Consultation**: Reference constitutional principles
2. **Documentation**: Record rationale and alternatives
3. **Review**: Stakeholder validation required
4. **Compliance**: Verify adherence to standardsConstitutional Compliance
Every tool and workflow phase validates against constitutional principles:
- Specification Phase: Requirements align with user-centric design
- Clarification Phase: Ambiguities resolved per governance standards
- Planning Phase: Technical decisions follow architectural principles
- Task Phase: Implementation includes constitutional requirements
- Analysis Phase: Cross-artifact consistency with constitutional compliance
Enhanced v0.0.52 Workflow Example
Complete end-to-end example using the enhanced 7-phase methodology:
# Phase 1: Establish Constitutional Governance
constitution_result = await constitution_tool(
repository_path="/path/to/project",
principles="""
# Photo Album Project Constitution
## Core Principles
- **User Privacy**: No cloud uploads, local storage only
- **Performance**: Smooth drag-and-drop with 60fps
- **Accessibility**: Screen reader and keyboard navigation
- **Cross-Platform**: Works on Windows, macOS, Linux
## Technical Standards
- **Framework**: Vanilla JS with minimal dependencies
- **Database**: SQLite for metadata storage
- **Testing**: Jest with 90%+ coverage requirement
- **Documentation**: JSDoc for all public APIs
""",
governance_areas=["privacy", "performance", "accessibility", "cross-platform"]
)
# Phase 2: Create Requirements Specification
spec_result = await specify_tool(
description="""
Build a photo album organizer that helps users manage their local photo collection.
Users can create albums grouped by date, drag and drop photos between albums,
and view photos in a responsive tile interface. Albums are never nested.
All data stays local - no cloud uploads or external services.
""",
repository_path="/path/to/project"
)
# Phase 3: Structured Clarification (if needed)
clarify_result = await clarify_tool(
repository_path="/path/to/project",
clarification_questions="""[
{
"id": "Q1",
"category": "User Interface",
"question": "What specific photo formats should be supported?",
"context": "Technical implementation needs format specifications"
},
{
"id": "Q2",
"category": "Performance",
"question": "How many photos should be displayable in a single album?",
"context": "Impacts rendering and memory optimization"
}
]""",
answers="""[
{
"id": "Q1",
"answer": "Support JPEG, PNG, WEBP, and RAW formats (CR2, NEF). Use native browser APIs for decoding."
},
{
"id": "Q2",
"answer": "Target 1000+ photos per album with virtual scrolling for performance."
}
]""",
complete_clarification=True
)
# Phase 4: Technical Implementation Planning
plan_result = await plan_tool(
feature_path=spec_result["feature_path"]
)
# Phase 5: Task Breakdown with TDD
tasks_result = await tasks_tool(
feature_path=spec_result["feature_path"]
)
# Phase 6: Cross-Artifact Analysis
analysis_result = await analyze_tool(
repository_path="/path/to/project",
analysis_type="full",
include_recommendations=True
)
# Phase 7: Implementation Readiness Check
if analysis_result["overall_status"] == "ready":
print("Ready for implementation!")
print(f"Consistency Score: {analysis_result['consistency_analysis']['consistency_score']}%")
print(f"Coverage: {analysis_result['coverage_analysis']['coverage_percentage']}%")
else:
print("Implementation blocked:")
for issue in analysis_result["readiness_assessment"]["blocking_issues"]:
print(f" - {issue}")Testing with MCP Inspector
Test and debug the server using the MCP Inspector:
Quick Test Script
# Use the included test script (creates virtual environment and handles ports)
./test_inspector.shOr manually:
# Install the package in a virtual environment
python3 -m venv .venv_test
source .venv_test/bin/activate
pip install -e .
# Launch the Inspector
npx @modelcontextprotocol/inspector .venv_test/bin/python -m speckit_mcpIn the Inspector
- Connect to the server
- Tools tab: Test individual tools with different parameters
- Prompts tab: See and test the guided workflows
- Test scenarios:
- Try
get_context_toolwithcontext_type: "specs"(works) - Try
get_context_toolwithcontext_type: "phase"withoutphaseparameter (error) - Use prompts to see how they guide through the workflow
- Try
Complete Workflow Example
# Step 1: Initialize your project (one-time setup)
init_result = await initialize(
repository_path="/Users/me/my-project",
project_name="My API Project",
project_type="web",
create_templates=True
)
# Creates: .specify-mcp/constitution.yaml and templates
# Step 2: Create a specification
spec_result = await specify(
description="Build a REST API for user management with authentication",
repository_path="/Users/me/my-project"
)
# Creates: specs/001-rest-api-user-management/spec.md
# Step 3: Generate implementation plan
plan_result = await plan(
feature_path="specs/001-rest-api-user-management"
)
# Creates: plan.md, research.md, data-model.md, contracts/
# Step 4: Break down into tasks
tasks_result = await tasks(
feature_path="specs/001-rest-api-user-management"
)
# Creates: tasks.md with T001-T025 task breakdownGenerated File Structure
your-repo/
└── specs/
└── 001-feature-name/
├── spec.md # Feature specification
├── plan.md # Implementation plan
├── research.md # Technology research
├── data-model.md # Data models
├── tasks.md # Task breakdown
└── contracts/ # API contracts
└── mcp-tools.jsonConfiguration
Create .specify-mcp/constitution.yaml in your repository for project-specific settings:
project:
name: "My Project"
type: "web" # single, web, or mobile
workflow:
branch_prefix: "feature"
auto_commit: false
technical:
language: "Python 3.11"
framework: "FastAPI"
testing: "pytest"Development
Running Tests
# Run all tests (42 tests)
pytest tests/
# Run specific test categories
pytest tests/contract/ # Contract tests
pytest tests/integration/ # Integration tests
# Run with coverage
pytest --cov=speckit_mcp tests/Test Status
- Initialize tool: 8/8 tests passing
- Get Context tool: 9/9 tests passing
- Specify tool: 6/6 tests passing
- Plan tool: 8/8 tests passing
- Tasks tool: 9/9 tests passing
- Integration: 2/2 tests passing
Code Quality
# Format code
black src/ tests/
isort src/ tests/
# Lint
ruff src/ tests/
# Type checking
mypy src/Architecture
src/speckit_mcp/
├── server.py # FastMCP server implementation
├── prompts.py # MCP prompt definitions
├── tools/
│ ├── initialize.py # Project initialization
│ ├── context.py # Context-aware documentation
│ ├── specify.py # Specification generation
│ ├── plan.py # Plan generation
│ └── tasks.py # Task breakdown
├── git/
│ └── operations.py # Git operations (branch, commit)
├── resources/
│ └── spec_template.md # Specification template
└── models/ # Data modelsTechnology Stack
- FastMCP: MCP server framework
- Pydantic: Data validation
- PyYAML: Configuration management
- asyncio: Asynchronous operations
Roadmap
- [x] Core tools implementation (specify, plan, tasks)
- [x] Git integration
- [x] Template system
- [x] Test coverage
- [x] Initialize project tool
- [x] Context-aware documentation
- [x] MCP Prompts for guided workflows
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Write tests for your changes
- Ensure all tests pass (
pytest tests/) - Commit your changes (
git commit -m 'Add amazing feature') - Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Links
- Repository: https://github.com/DankeyDevDave/spec-kit-mcp
- Issues: https://github.com/DankeyDevDave/spec-kit-mcp/issues
- MCP Protocol: https://modelcontextprotocol.io/
- Original Spec-Kit: https://github.com/github/spec-kit
Acknowledgments
- GitHub's spec-kit team for the specification-driven methodology
- FastMCP for the excellent MCP framework
- The MCP community for protocol development
