@juanklagos/sdd-mcp

sdd-mcp

MCP server for the Spec-Driven Development framework.

Purpose:

• expose SDD operations as MCP tools
• expose framework and project context as MCP resources
• expose beginner-friendly SDD flows as MCP prompts

Design goals:

• prefer ./www/<project-name>/ as the recommended default workspace inside this template
• support external target project paths on project-root-based tools
• block implementation without approved spec and consistent plan
• require user consent only before implementation starts

Target MCP surface:

• Tools: create workspace, create spec, validate, check gate, record consent, generate status
• Resources: policy, templates, quickstart, active project context
• Prompts: new project, adapt existing project, first spec, session close

Run it (installed from npm)

The package ships two executables. Both read stdin/stdout or listen locally; no build step is required.

# 1. stdio transport - what MCP clients (Claude, Cursor, Codex...) launch
npx -y @juanklagos/sdd-mcp

# 2. Streamable HTTP transport - the visual board, the dashboard, and MCP at /mcp
npx -y @juanklagos/sdd-mcp --http
# -> http://127.0.0.1:3334/builder    the SDD Builder canvas
#    http://127.0.0.1:3334/dashboard  read-only status
#    http://127.0.0.1:3334/mcp        the MCP endpoint itself

The sdd-mcp-http bin still exists and does the same thing — --http on the main bin is there so reaching the board never depends on npx resolving a second executable.

Environment variables:

Variable	Default	Meaning
SDD_MCP_HTTP_PORT	3334	Port for sdd-mcp-http.
SDD_MCP_HTTP_HOST	127.0.0.1	Bind address. Loopback by default; see the security notes below.
SDD_MCP_HTTP_ALLOWED_ORIGINS	(empty)	Extra Origin values allowed on mutating requests, comma-separated. * disables the check.
SDD_MCP_MAX_BODY_BYTES	2097152	Maximum request body the transport will buffer.
SDD_MCP_SESSION_TTL_MS	600000	Idle time after which an MCP Streamable HTTP session is reclaimed.
SDD_MCP_MAX_SESSIONS	64	Concurrent MCP session cap; the least-recently-used session is evicted.
SDD_PROJECT_ROOT	autodetected from the cwd	Project the HTTP dashboard, REST API and live events operate on.
SDD_WORKSPACES_ROOT	repo root in a checkout, cwd when installed from npm	Where sdd_create_workspace creates ./www/<project-name>.

Security model of sdd-mcp-http / Modelo de seguridad

The HTTP server is local-first and unauthenticated on purpose: it reads, creates and approves specs in your working copy, and /api/spec/:id/issues runs your authenticated gh. It is therefore locked down as follows.

• Loopback only. It binds 127.0.0.1. SDD_MCP_HTTP_HOST can widen that (0.0.0.0, ::), and doing so prints a warning at startup, because anyone who can reach the port gets full control. The startup banner always shows the address actually bound.
• Origin allowlist. Mutating requests (POST/PUT/PATCH/DELETE) from a non-loopback Origin get 403 before any route runs, so a page you merely visit cannot drive the server. Requests with no Origin (CLI, MCP clients) are allowed; loopback origins on any port are allowed, so the builder's Vite dev server keeps working.
• JSON only. A mutating request that declares a non-JSON content type gets 415, which forces browsers into a preflight that never succeeds.
• Bounded bodies. Request bodies over SDD_MCP_MAX_BODY_BYTES get 413 (or the socket is dropped for chunked uploads that never declare a length).
• Bounded sessions. MCP Streamable HTTP sessions are reclaimed on DELETE, on transport close, after an idle TTL, and by a concurrent-session cap.

ES: el servidor HTTP es local-first y sin autenticación a propósito. Escucha solo en loopback, bloquea peticiones cross-origin que modifican estado, exige content-type: application/json, limita el tamaño del cuerpo y recicla las sesiones MCP. Exponerlo fuera de loopback con SDD_MCP_HTTP_HOST da control total a cualquiera que alcance el puerto.

Note: binding 127.0.0.1 means the IPv6 loopback [::1] is not served. Browsers and curl fall back to IPv4 for localhost; set SDD_MCP_HTTP_HOST=:: if you need dual-stack.

Framework assets (policy, quickstart, guides, spec template, scaffolding scripts) are bundled inside @juanklagos/sdd-core under framework/, so the tools and sdd:// resources work from a plain npm install. Running from a checkout of the template repository always uses the live files instead.

The SDD Builder UI (/builder) is checkout-only by design: builder/dist is not bundled in the tarball. An npm-installed server answers /builder with a 503 explaining how to get it. Everything else - tools, resources, prompts and /dashboard - works from npm.

Local development (inside the template repository):

npm install
npm run typecheck
npm run build
npm run mcp:smoke        # stdio, from the checkout
npm run mcp:http:smoke   # streamable HTTP, from the checkout
npm run mcp:pack:smoke   # npm pack + install + run the bins as a user would
npm run mcp:start
npm run mcp:http:start

Current MVP 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

Current resources:

• sdd-policy
• sdd-ai-start
• sdd-easy-mcp-guide
• sdd-quickstart
• sdd-spec-template
• sdd-project-index
• sdd-project-log
• sdd-project-latest-handoff
• sdd-project-idea
• sdd-spec-document

Current 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

Implementation notes:

• tools expose outputSchema
• handlers return structuredContent
• stdio and Streamable HTTP are both supported

Config examples:

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

Reference docs:

• docs/en/43-easy-mcp-guide.md
• docs/es/43-guia-mcp-facil.md
• docs/en/44-hosted-mcp-onboarding-model.md
• docs/es/44-modelo-onboarding-mcp-alojado.md
• docs/en/45-client-visual-examples-for-easy-mcp.md
• docs/es/45-ejemplos-visuales-clientes-mcp-facil.md
• docs/en/33-mcp-server-guide.md
• docs/es/33-guia-servidor-mcp.md