sdd-mcp

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 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"]
# }

Option 2: Install Globally

# 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

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