Specification-driven development MCP server with domain analysis capabilities
npm install speckit-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!
Spec-Kit MCP brings enterprise-grade specification-driven development to any repository with enhanced constitutional governance. The latest v0.0.52 update provides:
The easiest way to install Spec-Kit MCP is through the MCPB bundle, which provides universal installation across AI applications:
1. Download the MCPB bundle from the releases page
2. Install via your MCP-compatible AI application (Claude Desktop, etc.)
3. Start using immediately with pre-configured tools and templates
See MCPB_README.md for detailed MCPB installation instructions.
#### Prerequisites
- Python 3.11 or higher installed
- Git installed and configured
- Claude Desktop application (or other MCP client)
``bashClone the repository
git clone https://github.com/DankeyDevDave/spec-kit-mcp.git
cd spec-kit-mcp
#### Alternative: Using Virtual Environment (recommended for isolation)
bash
python3 -m venv venv
source venv/bin/activate # On macOS/Linux
or
venv\Scripts\activate # On Windowspip install -e .
`$3
bash
From the project directory
python3 -m speckit_mcp
`You should see the FastMCP banner indicating the server is running successfully.
$3
1. Locate Claude Desktop configuration file:
- macOS:
- Windows:
- Linux: 2. Add the spec-kit server configuration:
json
{
"mcpServers": {
"spec-kit": {
"command": "python3",
"args": ["-m", "speckit_mcp"],
"cwd": "/path/to/your/spec-kit-mcp",
"description": "Spec-driven development workflow tools"
}
}
}
`Important: Replace
with your actual project path.#### For Virtual Environment Users
If using a virtual environment, modify the command path:
`json
{
"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"
}
}
}
`$3
1. Restart Claude Desktop completely (quit and reopen)
2. Verify installation by asking Claude to list available tools
3. Test functionality with a simple command like initializing a project
$3
Server Not Found:
- Ensure Python 3.11+ is installed:
- Verify the project path in the config is correct
- Check that the server runs manually: Permission Errors:
- Ensure read/write access to repository directories
- Check git configuration:
and git config user.emailTools 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:
bash
Check available Python versions
which python3.11 || which python3.12 || which python3.13Use specific version in config
"command": "/opt/homebrew/bin/python3.12"
`$3
The server provides a comprehensive 7-phase workflow for spec-driven development:
1. Constitution → Establish governing principles
2. Specify → Create detailed requirements
3. Clarify → Resolve specification ambiguities
4. Plan → Generate technical implementation
5. Tasks → Break down into actionable items
6. Analyze → Verify consistency and coverage
7. Implement → Execute with quality assurance
Enhanced Tools & Capabilities (v0.0.52)
$3
$3
####
- Extract Business Entities from DataAutomatically extract business entities, rules, and integration patterns from JSON/CSV data files.
Purpose: Populate specifications with real business entities discovered from your data
Input:
`python
{
"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
####
- Configure Domain AnalysisInteractive setup wizard for domain analysis preferences and templates.
Purpose: Configure domain-specific analysis patterns and preferences
Input:
`python
{
"config_directory": ".specify"
}
`Output:
- Domain configuration file with user preferences
- Template selections and customizations
- Analysis parameters and thresholds
####
- Show Available TemplatesList 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:
`python
{
"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:
with governance framework
- Creates: memory/constitution_update_checklist.md for tracking changes
- Returns: Constitutional sections, governance areas, and compliance guidelines####
specify_tool - Requirements SpecificationConvert natural language descriptions into structured specifications.
Purpose: Transform ideas into comprehensive, testable requirements
Input:
`python
{
"description": "Build a photo album organizer with drag-and-drop functionality",
"repository_path": "/path/to/your/repo"
}
`Output:
- Creates: Feature branch (e.g.,
)
- Creates: specs/001-photo-album-organizer/spec.md with 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:
`python
{
"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:
with question-answer tracking
- Updates: Specification with clarified information
- Returns: Resolution status and readiness for planning phase####
plan_tool - Technical Implementation PlanningGenerate comprehensive technical plans from clarified specifications.
Purpose: Create detailed implementation roadmap with constitutional compliance
Input:
`python
{
"feature_path": "/path/to/specs/001-photo-album-organizer"
}
`Output:
- Creates:
with technical architecture and design decisions
- Creates: data-model.md with entity definitions and relationships
- Creates: contracts/ directory with API specifications
- Returns: Plan components, constitutional compliance verification####
tasks_tool - Actionable Task BreakdownBreak implementation plans into executable, dependency-aware tasks.
Purpose: Convert plans into systematic task execution with TDD methodology
Input:
`python
{
"feature_path": "/path/to/specs/001-photo-album-organizer"
}
`Output:
- Creates:
with 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:
`python
{
"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
$3
####
- Project SetupInitialize repositories with spec-kit configuration and constitutional framework.
Input:
`python
{
"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:
directory and template structure
- Configures: AI agent-specific workflows and scripts
- Returns: Setup status and configuration paths####
get_context_tool - Contextual InformationProvides phase-specific documentation and project state information.
Input:
`python
{
"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:
-
: Get project configuration and principles
- phase: Get phase-specific documentation and best practices
- specs: List all specifications in the project
- feature: Get details about a specific feature
- templates: List available templates
- status: Get workflow status for a featureOutput:
- Context-specific information and documentation
- Current workflow phase and next steps
- Task progress tracking (for status context)
####
get_task_progress_tool - Progress TrackingAnalyzes task completion across all features with detailed reporting.
Input:
`python
{
"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
####
- MCP Compliance ValidationEnsures codebase follows MCP specification standards and best practices.
Input:
`python
{
"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 |
$3
- Shell Scripts (
) - 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$3
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 feature
- repository_path: Path to your git repository####
explore_project
Explores and summarizes the current project state, including constitution, specs, and templates.Parameters:
-
: Path to your git repository#### ⏭️
continue_feature
Continues work on an existing feature, determining the next steps based on current progress.Parameters:
-
: 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
$3
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.,
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.
$3
`markdown
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 requiredArchitectural 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-documentingDecision-Making Framework
1. Consultation: Reference constitutional principles
2. Documentation: Record rationale and alternatives
3. Review: Stakeholder validation required
4. Compliance: Verify adherence to standards
`$3
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:
python
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:
$3
bash
Use the included test script (creates virtual environment and handles ports)
./test_inspector.sh
`Or manually:
bash
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_mcp
`$3
1. Connect to the server
2. Tools tab: Test individual tools with different parameters
3. Prompts tab: See and test the guided workflows
4. Test scenarios:
- Try
with context_type: "specs" (works)
- Try get_context_tool with context_type: "phase" without phase parameter (error)
- Use prompts to see how they guide through the workflowComplete Workflow Example
`python
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 breakdown
` Generated 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.json
Configuration
Create
in your repository for project-specific settings:`yaml
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
$3
bash
Run all tests (42 tests)
pytest tests/Run specific test categories
pytest tests/contract/ # Contract tests
pytest tests/integration/ # Integration testsRun with coverage
pytest --cov=speckit_mcp tests/
`$3
- 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$3
bash
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 models
$3
- FastMCP: MCP server framework
- Pydantic: Data validation
- PyYAML: Configuration management
- asyncio: Asynchronous operationsRoadmap
- [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.
1. Fork the repository
2. Create your feature branch (
)
3. Write tests for your changes
4. Ensure all tests pass (pytest tests/)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature`)This project is licensed under the MIT License - see the LICENSE file for details.
- 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
- GitHub's spec-kit team for the specification-driven methodology
- FastMCP for the excellent MCP framework
- The MCP community for protocol development
---