sdd-mcp-server

v3.3.0

Published

7 days ago

MCP server for spec-driven development workflows across AI-agent CLIs and IDEs

0High
0Medium
0Low

yi-john-huang

mcp sdd spec-driven-development ai-agent cli

MCP SDD Server

A Model Context Protocol (MCP) server implementing Spec-Driven Development (SDD) workflows for AI-agent CLIs and IDEs like Claude Code, Cursor, and others.

v3.3 - Multi-tool install support: --codex (AGENTS.md for OpenAI Codex CLI), --antigravity (.agent/ symlinks for Google Antigravity), --all-tools. See CHANGELOG.md for full version history.

🚀 Quick Start

Option 1: Direct NPX Usage (Recommended)

# No installation required - use directly with npx
npx -y sdd-mcp-server@latest

# Pin exact version (optional)
npx -y [email protected]

# For Claude Code MCP integration, add to your configuration:
# "sdd-mcp-server": {
#   "command": "npx",
#   "args": ["-y", "sdd-mcp-server@latest"]
# }

Option 2: Install Globally

# Install globally for persistent usage
npm install -g sdd-mcp-server@latest

# Pin exact version (optional)
npm install -g [email protected]

# Start the server
sdd-mcp-server

Option 3: Clone and Run

# Clone the repository
git clone https://github.com/yi-john-huang/sdd-mcp.git
cd sdd-mcp

# Install and start
npm install
npm run build
npm start

Option 4: Docker (Secure Distroless Image)

# Build distroless image locally
docker build --target production -t sdd-mcp-server .

# Run with Docker (secure distroless image)
docker run -p 3000:3000 sdd-mcp-server

# Or with Docker Compose (includes security hardening)
curl -O https://raw.githubusercontent.com/yi-john-huang/sdd-mcp/develop/docker-compose.yml
docker-compose up -d

🔒 Security Features

Distroless base image: Uses gcr.io/distroless/nodejs18-debian11 for minimal attack surface
No shell access: Container contains only Node.js runtime and application code
Non-root user: Runs as user ID 1001 (no privilege escalation)
Read-only filesystem: Container filesystem is immutable at runtime
Dropped capabilities: All Linux capabilities dropped except minimal required ones
Security options: no-new-privileges prevents privilege escalation

🔧 Configuration for AI Clients

Claude Code

Add to your MCP settings using the command line:

# Option 1: Use npx (no installation required)
claude mcp add sdd -s local -- npx -y sdd-mcp-server@latest

# Option 2: Install globally first
npm install -g sdd-mcp-server@latest
claude mcp add sdd "sdd-mcp-server" -s local

# Verify connection
claude mcp list
# Should show: sdd: ✓ Connected

# For development (local repo):
git clone https://github.com/yi-john-huang/sdd-mcp.git
cd sdd-mcp
# Use the dedicated MCP entry
claude mcp add sdd "$(pwd)/mcp-server.js" -s local

Manual configuration in ~/.claude.json:

{
  "mcpServers": {
    "sdd": {
      "command": "sdd-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Cursor IDE

Add to your MCP configuration:

{
  "sdd-server": {
    "command": "npx",
    "args": ["-y", "sdd-mcp-server@latest"],
    "env": {}
  }
}

Or with global installation:

{
  "sdd-server": {
    "command": "sdd-mcp-server",
    "args": [],
    "env": {}
  }
}

Other MCP Clients

Any MCP-compatible client can connect using stdio transport:

# Use npx (no installation required)
npx -y sdd-mcp-server@latest

# Or install globally first
npm install -g sdd-mcp-server@latest
sdd-mcp-server

🎯 Agent Skills (NEW in v1.9.0)

SDD now uses a hybrid architecture for better token efficiency:

MCP Tools: Action-oriented operations (init, status, approve, quality-check, validate, spec-impl)
Agent Skills: Template/guidance-heavy operations (requirements, design, tasks, steering, implement, commit)

Installing Components (v3.0+)

# Recommended: Install ALL components (skills, steering, rules, contexts, agents, hooks)
npx sdd-mcp-server install --all

# Install specific component types
npx sdd-mcp-server install --skills      # Skills to .claude/skills/
npx sdd-mcp-server install --steering    # Steering to .spec/steering/
npx sdd-mcp-server install --rules       # Rules to .claude/rules/
npx sdd-mcp-server install --contexts    # Contexts to .claude/contexts/
npx sdd-mcp-server install --agents      # Agents to .claude/agents/
npx sdd-mcp-server install --hooks       # Hooks to .claude/hooks/

# Install multiple component types
npx sdd-mcp-server install --skills --rules --agents

# Default: Install skills + steering (backward compatible)
npx sdd-mcp-server install

# List all available components
npx sdd-mcp-server install --list

# Legacy: Install skills only
npx sdd-mcp-server install-skills

# Multi-tool support (v3.3+)
npx sdd-mcp-server install --codex             # + AGENTS.md for OpenAI Codex CLI
npx sdd-mcp-server install --antigravity       # + .agent/ symlinks for Google Antigravity
npx sdd-mcp-server install --all-tools         # + all tool integrations

Component Types (v3.0): | Component | Install Path | Purpose | |-----------|--------------|---------| | Skills | .claude/skills/ | Workflow guidance (requirements, design, tasks, implement, etc.) | | Steering | .spec/steering/ | Project-specific templates (product, tech, structure) | | Rules | .claude/rules/ | Always-active guidelines (coding-style, testing, security, git-workflow) | | Contexts | .claude/contexts/ | Mode-specific prompts (dev, review, planning, security-audit, research) | | Agents | .claude/agents/ | Specialized AI personas (planner, architect, reviewer, implementer) | | Hooks | .claude/hooks/ | Event-driven automation (pre-tool-use, post-tool-use, session events) |

Component Architecture & Relationships

The 6 component types work together in a layered guidance model:

┌──────────────────────────────────────────────────────────────┐
│                     User Request                             │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  HOOKS (pre-tool-use)                                        │
│  • Validate workflow order (e.g., requirements before design)│
│  • Check test coverage before implementation                 │
│  • Triggered automatically on events                         │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  RULES (always active)                                       │
│  • coding-style.md → TypeScript/JS conventions               │
│  • testing.md → TDD requirements                             │
│  • security.md → OWASP guidelines                            │
│  • Loaded at session start, apply to ALL operations          │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  CONTEXTS (mode-specific)                                    │
│  • dev.md → Implementation focus                             │
│  • review.md → Quality focus                                 │
│  • planning.md → Architecture focus                          │
│  • Activated based on current task type                      │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  AGENTS (specialized personas)                               │
│  • reviewer.md → Linus-style code review                     │
│  • architect.md → System design expertise                    │
│  • implementer.md → TDD implementation                       │
│  • Invoked for specific expertise needs                      │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  SKILLS (on-demand workflows)                                │
│  • /sdd-requirements → EARS requirements template            │
│  • /sdd-design → Architecture design template                │
│  • /sdd-implement → Implementation checklist                 │
│  • User-invoked via slash commands                           │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  STEERING (project-specific templates - v3.1+)               │
│  • product.md → Product description                          │
│  • tech.md → Technology stack                                │
│  • structure.md → Project structure                          │
│  • (Static guidance now in agents/rules/skills)              │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  MCP TOOLS (actions)                                         │
│  • sdd-init, sdd-approve, sdd-status, sdd-spec-impl          │
│  • Execute actual operations                                 │
└──────────────────────────────────────────────────────────────┘

When Each Component Activates: | Component | Activation | Example | |-----------|------------|---------| | Rules | Session start (always) | coding-style.md enforces conventions on every response | | Contexts | Task type detection | review.md activates when reviewing code | | Agents | Explicit invocation | reviewer.md invoked by /sdd-review skill | | Skills | User command (/skill-name) | /sdd-requirements loads requirements template | | Steering | Project customization | /sdd-steering generates product.md, tech.md | | Hooks | Events (pre/post tool, session) | validate-sdd-workflow runs before sdd-design |

Migrating from .kiro to .spec (v2.1.0+)

If you have existing projects using the legacy .kiro directory, migrate to the new .spec standard:

# Preview migration (dry run)
npx sdd-mcp-server migrate-kiro --dry-run

# Perform migration
npx sdd-mcp-server migrate-kiro

# Migrate a specific project
npx sdd-mcp-server migrate-kiro --path ./my-project

Note: Legacy .kiro directories are still supported for backwards compatibility, but new projects will use .spec.

Migrating Steering Documents (v3.1.0+)

If you have existing projects with static steering documents, migrate to the new consolidated architecture:

# Preview migration (dry run)
npx sdd-mcp-server migrate-steering --dry-run

# Perform migration (backs up existing steering first)
npx sdd-mcp-server migrate-steering

# Migrate a specific project
npx sdd-mcp-server migrate-steering --path ./my-project

What this does:

Backs up existing .spec/steering/ to .spec/steering.backup/
Removes static steering docs (principles.md, tdd-guideline.md, linus-review.md, etc.)
Preserves project-specific templates (product.md, tech.md, structure.md)
The static content now lives in enhanced .claude/ components

Available Skills

After installation, use these skills in Claude Code:

| Skill | Description | |-------|-------------| | /simple-task <description> | Quick implementation for small features, bug fixes, enhancements | | /sdd-requirements <feature> | Generate EARS-formatted requirements with embedded quality checklist | | /sdd-design <feature> | Create architecture design with Linus-style principles | | /sdd-tasks <feature> | Generate TDD task breakdown with test pyramid guidance | | /sdd-implement <feature> | Implementation guidelines with SOLID, security, TDD | | /sdd-steering | Create/update project-specific steering documents | | /sdd-steering-custom | Create custom steering with inclusion modes | | /sdd-commit | Commit/PR guidelines with conventional commits | | /sdd-review | NEW in v3.0 - Linus-style direct code review with severity levels | | /sdd-security-check | NEW in v3.0 - OWASP Top 10 security audit checklist | | /sdd-test-gen | NEW in v3.0 - TDD test generation with Red-Green-Refactor workflow |

Token Efficiency

Old Design (static steering): ~3,800 tokens loaded for every operation New Design (skills): ~1,700 tokens loaded only when skill invoked

Savings: ~55% fewer tokens in typical operations!

📋 Available MCP Tools

Once connected to your AI client, you can use these MCP tools:

| Tool | Description | Usage | |------|-------------|--------| | sdd-init | Initialize new SDD project with interactive clarification | Analyzes description quality (0-100 score), blocks if < 70%, asks targeted WHY/WHO/WHAT questions | | sdd-status | Check workflow progress | Shows current phase and approvals for features | | sdd-approve | Approve workflow phases | Mark phases (requirements, design, tasks) as approved | | sdd-quality-check | Code quality analysis | Linus-style 5-layer code review | | sdd-context-load | Load project context | Restore project memory and state | | sdd-validate-design | Design quality validation | Interactive GO/NO-GO design review | | sdd-validate-gap | Implementation gap analysis | Analyze requirements vs codebase | | sdd-spec-impl | Execute tasks with TDD | Kent Beck's Red-Green-Refactor methodology | | sdd-list-skills | List available Agent Skills | Shows skills that can be installed for Claude Code |

Note: Template/guidance tools (sdd-requirements, sdd-design, sdd-tasks, sdd-steering, sdd-implement) are now Agent Skills. Install them with npx sdd-mcp-server install-skills and use as /sdd-requirements, /sdd-design, etc.

💡 Basic Workflow

Setup: Install Skills & Steering, Initialize Project

# Install skills and steering documents (recommended)
npx sdd-mcp-server install

# Initialize project with MCP tool
Use sdd-init to create a new SDD project

# Generate project-specific steering documents with Agent Skill
Use /sdd-steering to generate product.md, tech.md, structure.md

Generate Requirements (Agent Skill)

Use /sdd-requirements <feature-name> to analyze your project
Automatically detects: language, framework, build tools, test frameworks
Creates EARS-formatted requirements with embedded quality checklist
Use sdd-validate-gap (MCP tool) to analyze implementation feasibility

Create Design (Agent Skill)

Use /sdd-design <feature-name> to generate architecture
Includes: component structure, data models, API design, Linus principles
Use sdd-validate-design (MCP tool) for GO/NO-GO design review
Use sdd-approve (MCP tool) to approve the design phase

Plan Tasks with TDD (Agent Skill)

Use /sdd-tasks <feature-name> to create TDD-focused task breakdown
Includes test pyramid guidance (70/20/10 ratio)
Tasks follow RED-GREEN-REFACTOR workflow automatically
Use sdd-approve (MCP tool) to approve the tasks phase

Implement with TDD (Agent Skill + MCP Tool)

Use /sdd-implement <feature-name> for implementation guidelines
Use sdd-spec-impl (MCP tool) to execute tasks with TDD methodology
Use sdd-quality-check (MCP tool) for Linus-style code review

Commit Changes (Agent Skill)

Use /sdd-commit for commit message and PR guidelines
Follow conventional commits format

Monitor & Manage (MCP Tools)

Use sdd-status to check workflow progress and phase approvals
Use sdd-context-load to restore project memory

⚙️ Configuration

Environment Variables

# Basic configuration
export LOG_LEVEL=info          # debug, info, warn, error
export DEFAULT_LANG=en         # en, es, fr, de, it, pt, ru, ja, zh, ko

# Document generation behavior
export SDD_ALLOW_TEMPLATE_FALLBACK=false  # true to allow fallback templates when module loading fails
                                          # false (default) to fail fast with actionable errors

# Advanced configuration (optional)
export PLUGIN_DIR=/path/to/plugins
export TEMPLATE_DIR=/path/to/templates
export MAX_PLUGINS=50
export HOOK_TIMEOUT=10000

Module Loading and Fallback Behavior

By default, the SDD server requires actual codebase analysis to generate steering documents and specifications. If module loading fails (e.g., running from source without building), commands will error with helpful messages:

# Default behavior - fail fast with clear error
sdd-steering
# Error: Failed to load documentGenerator: ...
# To use template fallbacks, set SDD_ALLOW_TEMPLATE_FALLBACK=true or run 'npm run build'

To allow fallback templates when modules cannot be loaded:

# Allow fallback templates (useful for development/debugging)
export SDD_ALLOW_TEMPLATE_FALLBACK=true
sdd-steering
# ⚠️ Warning: Using fallback templates - documents will contain generic content

Recommendation: Keep fallback disabled in production to ensure all generated documents reflect your actual codebase.

Claude Code Integration Example

# Install globally first
npm install -g sdd-mcp-server@latest

# Add to Claude Code with environment variables
claude mcp add sdd "sdd-mcp-server"

# Manual configuration in ~/.mcp.json:
{
  "servers": {
    "sdd": {
      "type": "stdio", 
      "command": "sdd-mcp-server",
      "args": [],
      "env": {
        "LOG_LEVEL": "info",
        "DEFAULT_LANG": "en"
      }
    }
  }
}

🏗️ Key Features

Core SDD Workflow

5-Phase SDD Workflow: INIT → REQUIREMENTS → DESIGN → TASKS → IMPLEMENTATION
TDD-First Task Generation: All implementation tasks follow Test-Driven Development (RED-GREEN-REFACTOR) methodology
EARS-Formatted Requirements: Generate acceptance criteria based on actual npm scripts and dependencies
Quality Enforcement: Linus-style 5-layer code review system with security (OWASP Top 10) checks

Plugin Architecture (v3.0)

6 Component Types: Skills, Steering, Rules, Contexts, Agents, Hooks for comprehensive AI guidance
Specialized Agents: Planner, Architect, Reviewer, Implementer, Security-Auditor, TDD-Guide personas
Always-Active Rules: Coding-style, Testing, Security, Git-workflow, Error-handling enforcement
Mode-Specific Contexts: Development, Review, Planning, Security-audit, Research modes
Event-Driven Hooks: Pre/post tool-use and session lifecycle automation
Plugin Manifest: .claude-plugin/plugin.json for Claude Code integration

Codebase Analysis

Comprehensive Multi-Language Analysis: Automatic detection of TypeScript, JavaScript, Java, Python, Go, Ruby, PHP, Rust, C#, Scala projects with framework-specific insights
Framework Detection: Recognizes Spring Boot, Django, FastAPI, Flask, Rails, Laravel, Express, React, Vue, Angular, Next.js, and 20+ other frameworks
Architecture Pattern Recognition: Detects DDD, MVC, Microservices, Clean Architecture patterns in your codebase
Context-Aware Generation: Analyzes package.json, dependencies, build tools, test frameworks, and project structure for real content

Guidelines & Standards

Coding Principles Enforcement: Built-in SOLID, DRY, KISS, YAGNI, Separation of Concerns, and Modularity guidance
Comprehensive Steering Documents: 8 auto-generated guidance docs (product, tech, structure, linus-review, commit, tdd-guideline, security-check, principles)
Multi-Language Support: 10 languages with cultural adaptation (en, es, fr, de, it, pt, ru, ja, zh, ko)
Template Engine: Handlebars-based file generation with project-specific data
Plugin System: Extensible architecture for custom workflows
MCP Protocol: Full compatibility with AI-agent CLIs and IDEs

🔍 Example: Complete SDD Workflow

Here's how to use the MCP SDD Server in your AI client:

# 1. Initialize a new project
"Use the sdd-init tool to create a project called 'my-web-app'
 for a React/TypeScript application with user authentication"

# 2. Generate steering documents
"Use sdd-steering to analyze my codebase and generate all steering documents"
# Result: 8 steering documents created including principles.md and tdd-guideline.md

# 3. Generate requirements with comprehensive analysis
"Use sdd-requirements to analyze the project and create requirements.md"
# Result: Detects TypeScript, React, npm, Jest, and generates EARS-formatted requirements

# 4. Create technical design
"Use sdd-design to generate architecture based on my React/TypeScript stack"
# Result: Component structure, state management design, API integration patterns

# 5. Validate design quality
"Use sdd-validate-design to review the architecture for potential issues"
# Result: GO/NO-GO assessment with improvement recommendations

# 6. Plan TDD-focused implementation tasks
"Use sdd-tasks to break down the work into TDD implementation phases"
# Result: Tasks organized as RED (tests) → GREEN (implementation) → REFACTOR (quality)

# 7. Implement with TDD
"Use sdd-spec-impl to execute the authentication tasks with TDD methodology"
# Result: Test-first development following principles.md and tdd-guideline.md

# 8. Review code quality
"Use sdd-quality-check to perform Linus-style code review with SOLID principles check"
# Result: 5-layer analysis + SOLID/DRY/KISS validation + security checks

# 9. Check workflow status
"Use sdd-status to check workflow progress and phase approvals"
# Result: Phase completion status and approval tracking

🛠️ Development & Troubleshooting

Local Development

git clone https://github.com/yi-john-huang/sdd-mcp.git
cd sdd-mcp
npm install
npm run dev  # Development mode with hot reload

Testing

npm test                # Run all tests
npm run test:coverage   # Run with coverage report

Common Issues

Issue: "Cannot find module sdd-mcp-server"

# Clear npm cache and reinstall
npm cache clean --force
npm install -g sdd-mcp-server

Issue: "Connection fails with npx"

⚠️ Known Issue: npx execution may have timing issues with Claude Code health checks.

Solution: Use global installation instead:

# Don't use: npx -y sdd-mcp-server@latest
# Instead, install globally:
npm install -g sdd-mcp-server@latest
claude mcp add sdd "sdd-mcp-server" -s local

Issue: "MCP server not responding or Failed to connect"

Fixed in v1.1.21: Use global installation instead of npx for reliable connections.

# Install globally first
npm install -g sdd-mcp-server@latest

# Test server directly
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' | sdd-mcp-server

# Check Claude MCP status
claude mcp list

# Re-add server to Claude MCP (forces refresh)
claude mcp remove sdd -s local
claude mcp add sdd "sdd-mcp-server" -s local

# Alternative: Use local development version for faster startup
git clone https://github.com/yi-john-huang/sdd-mcp.git
cd sdd-mcp
claude mcp add sdd "$(pwd)/mcp-server.js" -s local

Issue: "Permission denied"

# Fix permissions for global install
sudo npm install -g sdd-mcp-server

Issue: "Only template content generated" (Improved in v1.4.3)

As of v1.4.3, comprehensive codebase analysis is automatic with multi-language detection. Documents include real framework, build tool, and architecture information. If you still see a basic template:

Check the tool response message — it shows "✅ Comprehensive codebase analysis" or "⚠️ Basic template (analysis failed)"
Check the top of the generated file for warning headers with error details
Common causes: missing package.json, permissions issues, or unsupported project structure
Fix the issue and rerun the tool to get comprehensive analysis

📖 Advanced Documentation

For detailed documentation on:

📥 Installation Guide: See docs/INSTALL-GUIDE.md for complete CLI usage examples with real output
🔄 Workflow Diagrams: See docs/WORKFLOW.md for sequence diagrams showing component interactions
🤖 AI Agent Guide: See AGENTS.md for detailed instructions on using this server with AI agents
🏗️ Architecture Overview: See ARCHITECTURE.md for complete system design, layered architecture, module loading, and Mermaid diagrams
📦 Plugin Manifest: See .claude-plugin/plugin.json for Claude Code plugin configuration
Plugin Development: See DEPLOYMENT.md
Docker Deployment: See Dockerfile and docker-compose.yml

Component Documentation (v3.0):

Rules: See rules/*.md for always-active coding guidelines
Contexts: See contexts/*.md for mode-specific system prompts
Agents: See agents/*.md for specialized AI personas
Hooks: See hooks/**/*.md for event-driven automation

Steering Documents (v3.1+):

As of v3.1, static steering content has been consolidated into enhanced components:

Design Principles: .claude/rules/coding-style.md (includes SOLID, DRY, KISS, YAGNI, SoC)
TDD Methodology: .claude/agents/tdd-guide.md (Red-Green-Refactor workflow)
Code Review: .claude/agents/reviewer.md (Linus-style 5-layer thinking)
Security Checklist: .claude/agents/security-auditor.md (OWASP Top 10)

The .spec/steering/ directory now contains only project-specific templates:

product.md - Product description template
tech.md - Technology stack template
structure.md - Project structure template

Migration from v3.0: Run npx sdd-mcp-server migrate-steering to update existing projects.

🐛 Support & Issues

GitHub Issues: Report bugs or request features
Repository: yi-john-huang/sdd-mcp
License: MIT

🚀 Quick Links

Ready to get started?

# Install globally first
npm install -g sdd-mcp-server@latest

# For Claude Code users:
claude mcp add sdd "sdd-mcp-server"

# For direct usage:
sdd-mcp-server

Built for the AI development community 🤖✨