MCP Server Guide

Purpose

This guide is only for MCP setup and connectivity.

If you want the non-technical route first, start here:

• Easy MCP Guide

If you want the full functional reference, start here:

• Complete MCP Reference

Setup flow

flowchart LR
  A["Install dependencies"] --> B["Build MCP"]
  B --> C["Register client config"]
  C --> D["Start transport"]
  D --> E["Validate connection"]

Product split:

• repository root: canonical SDD framework
• packages/sdd-core: reusable SDD logic
• packages/sdd-mcp: MCP tools, resources, prompts, and transports

What is already implemented

High-level summary only:

Transports:

• stdio
• Streamable HTTP

Tools:

• sdd_create_workspace
• sdd_create_spec
• sdd_validate
• sdd_check_gate
• sdd_record_user_consent
• sdd_list_specs
• sdd_generate_status
• sdd_generate_roadmap
• sdd_append_project_log
• sdd_write_daily_log
• sdd_write_handoff
• sdd_write_decision

Structured tool output:

• each tool exposes outputSchema
• handlers return structuredContent plus text output

Static resources:

• sdd-policy
• sdd-ai-start
• sdd-easy-mcp-guide
• sdd-quickstart
• sdd-spec-template

Project resource templates:

• sdd-project-index
• sdd-project-log
• sdd-project-latest-handoff
• sdd-project-idea
• sdd-spec-document

Prompts:

• start_new_sdd_project
• adapt_existing_project_to_sdd
• close_sdd_session
• easy_start_project
• easy_create_spec
• easy_show_structure
• easy_validate_project
• easy_show_next_step
• easy_close_session

Local setup

npm install
npm run typecheck
npm run build
npm run mcp:smoke
npm run mcp:http:smoke

Run the servers:

npm run mcp:start
npm run mcp:http:start

Entrypoints:

• stdio: packages/sdd-mcp/dist/index.js
• HTTP: http://127.0.0.1:3334/mcp

Operational contract

• open this repository as the workspace root
• prefer ./www/<project-name>/ as the recommended default workspace
• external target paths are also supported for project-root-based tools
• create the SDD base first
• do not implement code before approved spec and consistent plan
• request explicit user consent only when implementation is about to start

Related references:

• Complete MCP Reference
• Command Results Reference

Copy-paste config examples

Reference examples:

• packages/sdd-mcp/examples/.cursor/mcp.json
• packages/sdd-mcp/examples/.mcp.json
• packages/sdd-mcp/examples/codex.config.toml

Cursor

Official config path on macOS/Linux:

• ~/.cursor/mcp.json

Project-scoped alternative:

• mcp.json in the workspace, if you prefer project-local registration

Example:

{
  "mcpServers": {
    "sdd": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/spec-driven-development-template/packages/sdd-mcp/dist/index.js"
      ]
    }
  }
}

Codex

Official shared config path:

• ~/.codex/config.toml

Example:

[mcp_servers.sdd]
command = "node"
args = ["/ABSOLUTE/PATH/TO/spec-driven-development-template/packages/sdd-mcp/dist/index.js"]

Claude Code

Official project-scoped config:

• .mcp.json at the repository root

Official user-scoped config:

• ~/.claude.json

Project-scoped example:

{
  "mcpServers": {
    "sdd": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/spec-driven-development-template/packages/sdd-mcp/dist/index.js"
      ],
      "env": {}
    }
  }
}

HTTP-capable clients

If the client supports remote MCP over Streamable HTTP:

http://127.0.0.1:3334/mcp

Use:

npm run mcp:http:start

Recommended first message to the agent

Use the connected sdd MCP server for this repository.
Create the SDD base first.
If the project is runnable inside this template, keep it inside ./www/<project-name>; external target paths are also supported.
Read the policy and quickstart resources first.
Do not implement code before approved spec and consistent plan.
Ask for explicit user consent only when implementation is about to start.

Verification checklist

• npm run typecheck
• npm run build
• npm run mcp:smoke
• npm run mcp:http:smoke
• ./scripts/validate-sdd.sh . --strict
• ./scripts/check-sdd-policy.sh .
• ./scripts/check-sdd-gate.sh .