mcp-speckit

AI Agent lifecycle management toolkit for MCP Server Lifecycle Specification

mcp-speckit is a specification-driven toolkit that guides AI agents through the complete lifecycle of MCP (Model Context Protocol) server development, from requirements gathering to deployment and operations.

🎯 Purpose

• Spec-Driven: Enforces compliance with MCP Server Lifecycle Specification v1.0.0
• AI-First: Designed for AI agent workflows with Slash Commands
• Complete Lifecycle: Covers UNDERSTAND → DESIGN → BUILD → TEST → DEPLOY → OPERATE phases
• Validation Engine: Two-stage validation (JSON Schema + specification rules)

🚀 Quick Start

Installation

pip install mcp-speckit

Initialize a New Project

mcp-speckit init my-mcp-server
cd my-mcp-server

This creates:

my-mcp-server/
├── artifacts/              # Specification artifacts
│   └── requirements_document.json
├── tools/                  # Tool implementations
├── resources/              # Resource implementations
├── prompts/                # Prompt implementations
└── README.md

Validate Artifacts

# Check entire project
mcp-speckit check

# Check specific file
mcp-speckit check artifacts/requirements_document.json

# Strict mode (warnings as errors)
mcp-speckit check --strict

# JSON output
mcp-speckit check --json > results.json

📚 CLI Commands

init - Initialize Project

Create a new MCP server project with templates.

mcp-speckit init <path> [OPTIONS]

Options:

• --template, -t: Server type (stdio or sse, default: stdio)
• --force, -f: Overwrite existing directory

Examples:

mcp-speckit init my-server
mcp-speckit init my-server --template sse
mcp-speckit init my-server --force

check - Validate Artifacts

Validate artifacts against MCP Server Lifecycle Specification.

mcp-speckit check [PATH] [OPTIONS]

Options:

• --type, -t: Explicit artifact type (requirements_document, technical_design_specification)
• --strict, -s: Treat warnings as errors
• --json: Output results as JSON

Examples:

mcp-speckit check                                    # Current directory
mcp-speckit check artifacts/requirements.json        # Single file
mcp-speckit check --type requirements_document req.json
mcp-speckit check --strict                           # Strict validation

Exit Codes:

• 0: All artifacts valid
• 1: Validation errors found
• 2: File/directory not found or other error

🤖 AI Agent Interface (Slash Commands)

mcp-speckit provides Slash Commands for AI-guided development:

Lifecycle Phase Commands

• /mcpspeckit.understand - Requirements gathering and analysis
• /mcpspeckit.design - Technical design specification
• /mcpspeckit.build - Implementation guidance
• /mcpspeckit.test - Testing and validation
• /mcpspeckit.deploy - Deployment orchestration
• /mcpspeckit.operate - Runtime management

Support Commands

• /mcpspeckit.get-spec - Specification specification reference
• /mcpspeckit.validate-requirements - Validate requirements document
• /mcpspeckit.validate-design - Validate design specification

Location: templates/mcp-spec/commands/

📋 Specification Compliance

Supported Artifacts

1. Requirements Document

{
  "mcp_spec_version": "1.0.0",
  "spec_version": "1.0.0",
  "project_name": "my-server",
  "description": "Server description",
  "server_type": "stdio",
  "functional_requirements": [
    {
      "id": "FR-001",
      "description": "Requirement description",
      "priority": "high",
      "acceptance_criteria": ["Criterion 1"]
    }
  ],
  "non_functional_requirements": []
}

2. Technical Design Specification

{
  "mcp_spec_version": "1.0.0",
  "spec_version": "1.0.0",
  "project_name": "my-server",
  "description": "Design description",
  "server_type": "stdio",
  "architecture": {
    "overview": "Architecture overview",
    "components": []
  },
  "tools": [],
  "prompts": [],
  "resources": []
}

Validation Rules

Schema Validation:

• Required fields presence
• Field types and formats
• Enum values (priority, server_type)
• String length constraints
• Array length constraints

Specification Rules:

• MCP version format (1.x.x)
• At least one high-priority requirement (warning)
• Tool/prompt/resource naming conventions

🏗️ Architecture

┌─────────────────────────────────────────┐
│  CLI Layer (init + check)               │
│  • User interaction                     │
│  • Rich formatted output                │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│  Validator Core                          │
│  • JSON Schema validation               │
│  • Specification rules checking              │
│  • Error message generation             │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│  Utils Layer                             │
│  • File loading (JSON/YAML)             │
│  • Artifact type detection              │
│  • Project structure creation           │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│  Models + Schemas                        │
│  • Pydantic models                      │
│  • JSON Schema definitions              │
└─────────────────────────────────────────┘

🧪 Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src/mcp_speckit --cov-report=html

# Run specific test suite
pytest tests/unit/test_validator.py -v
pytest tests/integration/test_cli.py -v

Test Coverage: 95%

• models.py: 97%
• schemas/: 100%
• validator.py: 94%
• utils.py: 100%
• cli.py: 88%

🌐 MCP Factory Ecosystem

mcp-speckit is part of the MCP Factory ecosystem:

• mcp-factory-server - Development and runtime management (UNDERSTAND/DESIGN/BUILD/OPERATE)
• mcp-inspector-server - Testing and validation (TEST)
• devops-mcp-server - Infrastructure deployment (DEPLOY)

📖 Documentation

• Specification - Toolkit specification
• Implementation Plan - Architecture and design
• Tasks - Implementation breakdown
• Specification Spec - MCP Server Lifecycle Specification

🤝 Contributing

This project follows the MetaSpec specification-driven development methodology:

1. Specifications First: All changes start with specification updates
2. AI-Assisted: Use Slash Commands for guided development
3. Quality Standards: Defined in memory/constitution.md

📄 License

MIT License - see LICENSE for details

🔗 Links

• MCP Protocol
• MetaSpec Framework
• MCP Factory

---

Generated with: MetaSpec 0.2.0
Specification Version: MCP Server Lifecycle Specification v1.0.0