Easy SDD MCP

Easy SDD MCP is a Model Context Protocol server that bootstraps and manages .easy-sdd workspaces, provides AI-facing tools for spec-driven development, and serves a real-time web dashboard (multi-project ready).

What You Get

• Structured workflow: requirements → design → tasks with approval gates and status tracking
• Unified multi-project dashboard: one process watches every project registered in ~/.easy-sdd-mcp/activeProjects.json
• Live spec/task/approval updates over WebSocket with copyable task prompts
• Automatic workspace bootstrap: .easy-sdd/ folders, templates, config.example.toml, and user-templates README
• Language support: English and 日本語 (set via config or CLI)

Quick Start

1. Start the unified dashboard (once per machine)

npx -y @nogataka/easy-sdd-mcp@latest --dashboard --port 5000

• Runs dashboard only (no MCP server) and picks an ephemeral port if omitted
• Watches ~/.easy-sdd-mcp/activeProjects.json for active servers

2. Start an MCP server per project

cd /path/to/project && npx -y @nogataka/easy-sdd-mcp@latest
# or provide an explicit path
npx -y @nogataka/easy-sdd-mcp@latest /path/to/project

• Registers/unregisters itself with the dashboard registry on start/stop
• Initializes .easy-sdd/ (specs, templates, steering docs, approvals, archive) if missing

3. Add to your MCP client

{
  "mcpServers": {
    "easy-sdd": {
      "command": "npx",
      "args": ["-y", "@nogataka/easy-sdd-mcp@latest", "/path/to/your/project"]
    }
  }
}

• Claude CLI: claude mcp add easy-sdd npx @nogataka/easy-sdd-mcp@latest -- /path/to/project
• Windows fallback: claude mcp add easy-sdd cmd.exe /c "npx @nogataka/easy-sdd-mcp@latest /path/to/project"
• Works with Augment, Claude Desktop, Cursor, Continue, OpenCode, and other MCP clients that accept the same command/args pattern.

--AutoStartDashboard is deprecated; it only logs a warning. Always run the dashboard explicitly with --dashboard.

CLI Options and Modes

• easy-sdd-mcp [path] [options] – path defaults to the current directory
• --dashboard – run dashboard-only multi-project mode (no MCP server)
• --port <1024-65535> – dashboard port (ephemeral when omitted)
• --config <path> – load a TOML config (defaults to .easy-sdd/config.toml when present)
• --help – print detailed usage
• --AutoStartDashboard – deprecated flag; dashboard is not auto-started

CLI arguments override config values. Dashboard-only mode ignores the project path except for loading config.

Configuration

Default location: .easy-sdd/config.toml (created as config.example.toml on first run).

projectDir = "/absolute/or/relative/path"
port = 5000            # dashboard port (1024-65535)
dashboardOnly = false  # run only the dashboard when true
autoStartDashboard = false  # deprecated; prints warning
lang = "en"            # en or ja

Precedence: CLI args > --config target > .easy-sdd/config.toml > built-in defaults.

Workspace Layout

.easy-sdd/
  approvals/
  archive/specs/
  specs/
  steering/
  templates/
  user-templates/
  config.example.toml

• Default templates: requirements, design, tasks, and steering docs are copied on startup.
• user-templates/ overrides matching filenames in templates/.
• Approvals live under .easy-sdd/approvals/; archived specs live under .easy-sdd/archive/specs/.

Dashboard Highlights

• Browser UI for specs, requirements, design, tasks, approvals, and progress bars
• Switch projects from the sidebar; each tab remembers its own selection
• Live updates via WebSocket; task prompts are copyable for AI execution
• Registry file: ~/.easy-sdd-mcp/activeProjects.json (auto-cleaned when servers stop; delete it manually if you ever need to clear stale entries)

Talking to Easy SDD

• “Create a spec for user authentication”
• “List my specs”
• “Execute task 1.2 in spec user-auth”
• “Show the status of spec payment-gateway”
• “Open the steering guide” / “Open the easy-sdd guide”

More prompting examples →

Documentation

• User Guide – end-to-end usage
• Configuration – CLI, config files, precedence
• Workflow – spec-driven process
• Interfaces – dashboard details
• Prompting – ready-made prompts
• Tools Reference – MCP tools and prompts
• Development – building and contributing
• Troubleshooting – common fixes

Migrating from Per-Project Dashboards

1. Stop any running easy-sdd-mcp processes.
2. (Optional) Clear stale registry data: rm ~/.easy-sdd-mcp/activeProjects.json.
3. Start the unified dashboard: npx -y @nogataka/easy-sdd-mcp@latest --dashboard --port 5000.
4. Restart each project’s MCP server without --AutoStartDashboard.
5. Open the dashboard and pick projects from the sidebar.

Development

npm install
npm run dev          # start MCP server in dev mode
npm run build        # typecheck + build dashboard + copy static assets
npm test             # vitest

GPL-3.0