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

$3

``bash

No installation required - use directly with npx

npx -y sdd-mcp-server@latest

Pin exact version (optional)

npx -y sdd-mcp-server@1.6.0

For Claude Code MCP integration, add to your configuration:

"sdd-mcp-server": {

"command": "npx",

"args": ["-y", "sdd-mcp-server@latest"]

}

`

$3

`bash

Install globally for persistent usage

npm install -g sdd-mcp-server@latest

Pin exact version (optional)

npm install -g sdd-mcp-server@1.6.0

Start the server

sdd-mcp-server
`

$3

`bash

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
`

$3

`bash

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

$3


Add to your MCP settings using the command line:
`bash

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:
`json
{
"mcpServers": {
"sdd": {
"command": "sdd-mcp-server",
"args": [],
"env": {}
}
}
}
`

$3


Add to your MCP configuration:
`json
{
"sdd-server": {
"command": "npx",
"args": ["-y", "sdd-mcp-server@latest"],
"env": {}
}
}
`

Or with global installation:
`json
{
"sdd-server": {
"command": "sdd-mcp-server",
"args": [],
"env": {}
}
}
`

$3


Any MCP-compatible client can connect using stdio transport:
`bash

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)

$3

`bash


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) |

$3

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 |

$3

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

`bash


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.

$3

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

`bash


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

$3

After installation, use these skills in Claude Code:

| Skill | Description |
|-------|-------------|
| /simple-task | Quick implementation for small features, bug fixes, enhancements |
| /sdd-requirements | Generate EARS-formatted requirements with embedded quality checklist |
| /sdd-design | Create architecture design with Linus-style principles |
| /sdd-tasks | Generate TDD task breakdown with test pyramid guidance |
| /sdd-implement | 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 |

$3

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

1. Setup: Install Skills & Steering, Initialize Project
`bash
# 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
`

2. Generate Requirements (Agent Skill)
`
Use /sdd-requirements 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
`

3. Create Design (Agent Skill)
`
Use /sdd-design 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
`

4. Plan Tasks with TDD (Agent Skill)
`
Use /sdd-tasks 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
`

5. Implement with TDD (Agent Skill + MCP Tool)
`
Use /sdd-implement 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
`

6. Commit Changes (Agent Skill)
`
Use /sdd-commit for commit message and PR guidelines
Follow conventional commits format
`

7. Monitor & Manage (MCP Tools)
`
Use sdd-status to check workflow progress and phase approvals
Use sdd-context-load to restore project memory
`

⚙️ Configuration

$3


`bash

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:

`bash


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:

`bash


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.

$3

`bash

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

$3

- 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

$3

- 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

$3

- 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

$3

- 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:

`bash


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

$3

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

$3

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

$3

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


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:
`bash


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.

`bash


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"
`bash


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

- npm package
- Docker image
- Source code
- Issues

---

Ready to get started?
`bash


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 🤖✨