@protonspy/csdd-mcp

An MCP server that exposes the csdd CLI as tools — one tool per subcommand.

csdd governs the Claude Code Spec-Driven Development workflow (steering, specs, skills, sub-agents, MCP servers) and validates the contract mechanically. This server lets an MCP-capable agent drive csdd directly as tools, instead of shelling out to a terminal — same operations, same phase gates, same exit codes.

agent ──(MCP/stdio)──▶ csdd-mcp ──(execFile)──▶ csdd binary ──▶ .claude/ · specs/

Each tool builds a csdd argv, runs the binary headlessly (NO_COLOR=1, no TTY so confirmations auto-decline), and returns its stdout/stderr. A non-zero exit becomes an MCP error result; exit 2 (validation failure) is surfaced distinctly so the agent can tell "your spec is invalid" from "the command broke".

Requirements

• Node.js ≥ 18 (the published package ships compiled JS).
• The csdd binary, reachable by the server — see Locating the csdd binary.

Install & configure

The server runs over stdio; point your MCP client at it.

Claude Code

# project scope (writes .mcp.json) — or use --scope user for all projects
claude mcp add csdd -- npx -y @protonspy/csdd-mcp

Or add it to .mcp.json by hand:

{
  "mcpServers": {
    "csdd": {
      "command": "npx",
      "args": ["-y", "@protonspy/csdd-mcp"],
      "env": { "CSDD_BIN": "/usr/local/bin/csdd" }
    }
  }
}

env.CSDD_BIN is optional — drop it if csdd is on your PATH. See below.

Any MCP client

Launch npx -y @protonspy/csdd-mcp (or csdd-mcp if installed globally) as a stdio server. The process stays alive serving stdio until the client closes the pipe.

Locating the csdd binary

The server resolves csdd once, on first use, in this order (first hit wins):

| # | Source | When it applies | |---|--------|-----------------| | 1 | $CSDD_BIN | Explicit absolute path. Always wins — use this if in doubt. | | 2 | Platform package @protonspy/csdd-<os>-<arch> | Declared as an optionalDependency of this package, so npx/npm i fetches the prebuilt binary for your OS/arch automatically — the zero-config path. | | 3 | Sibling repo binary (../csdd, ../../csdd) | When running from a checkout of the csdd repo. | | 4 | csdd on $PATH | Last resort, resolved by the OS at spawn time. |

If none resolve, calls fail with exit 127 and a message telling you to set CSDD_BIN, install @protonspy/csdd, or put csdd on your PATH.

Zero-config: running via npx -y @protonspy/csdd-mcp pulls the matching binary through #2 automatically — nothing to install. Set CSDD_BIN only to pin a specific build (e.g. a local dev binary).

Environment

| Variable | Effect | |----------|--------| | CSDD_BIN | Absolute path to the csdd binary. Highest-priority resolution. | | NO_COLOR | Forced to 1 for every call so output is ANSI-free (you don't set this). |

Result & error semantics

Every tool returns a text result. The mapping from the csdd exit code is:

| Exit | isError | Result text | |------|-----------|-------------| | 0 | false | stdout (and any stderr as an unlabelled warning); (ok, no output) if silent. | | 2 | true | Prefixed csdd validation failed (exit 2): — a contract/validation problem. | | other | true | Prefixed csdd failed (exit <n>):; stderr is labelled [stderr]. | | 127 | true | Binary not found — includes guidance to set CSDD_BIN / install / fix PATH. |

Tool reference

35 tools covering the csdd development flow, grouped by resource. Conventions:

• Every tool accepts an optional root — the workspace root (the directory containing .claude/). Omit it to walk up from the server's working directory.
• Destructive / gate-breaking tools take force (boolean). Without it, deletes are refused and phase gates hold.
• ? marks an optional parameter; everything else is required.

Scope: this server exposes the iterative development-flow resources (steering · spec · skill · agent) and the knowledge-graph brain (graph). Workspace setup and config management are deliberately not tools — csdd init, csdd update, csdd mcp …, and csdd export … are one-time operations a human runs from the CLI, not part of the loop an agent drives. (In fact, csdd init is what registers this server.)

Diagnostic

| Tool | Parameters | What it does | |------|------------|--------------| | csdd_version | — | Print the underlying csdd binary version (diagnostic / connectivity check). |

🧭 steering — project memory (.claude/steering/*.md)

| Tool | Parameters | What it does | |------|------------|--------------| | csdd_steering_init | root? | Create .claude/steering/ and the 6 standard files (product, tech, structure, security, testing, api-conventions). | | csdd_steering_create | name, inclusion, pattern?[], description?, title?, force?, root? | Create a custom steering file. inclusion ∈ always · fileMatch · manual · auto. fileMatch requires ≥1 pattern; auto requires a description. | | csdd_steering_list | root?, inclusion? | List steering files with inclusion mode; optionally filter by inclusion. | | csdd_steering_show | name, root? | Print a steering file (frontmatter + body). | | csdd_steering_delete | name, force?, root? | Delete a steering file (force required). Foundational files (product, tech, structure) are protected. | | csdd_steering_validate | name?, root? | Validate frontmatter/structure. Omit name to validate all. Exit 2 on issues. |

inclusion controls when the steering loads: always (always-on), fileMatch (when files match a pattern), manual (#name), auto (when its description matches the context).

📐 spec — per-feature contract (specs/<feature>/)

| Tool | Parameters | What it does | |------|------------|--------------| | csdd_spec_init | feature, language?, root? | Create specs/<feature>/spec.json (phase = initial, no approvals). language defaults to en. | | csdd_spec_list | root? | List specs with current phase, approved phases, and readiness. | | csdd_spec_show | feature, root? | Show a spec's spec.json metadata and its artifacts. | | csdd_spec_status | feature, root? | Combined show + validate for a spec. | | csdd_spec_generate | feature, artifact, force?, root? | Generate an artifact. artifact ∈ requirements · design · tasks · research · bugfix. Phase gates apply (see below); force bypasses them. | | csdd_spec_approve | feature, phase, force?, root? | Approve a phase. phase ∈ requirements · design · tasks. Validates first; force approves despite issues/missing prior approvals. | | csdd_spec_validate | feature, root? | Validate EARS phrasing, traceability, task annotations, parallel safety. Exit 2 on issues. | | csdd_spec_delete | feature, force?, root? | Delete specs/<feature>/ recursively (force required). | | csdd_spec_test_report | feature, run?, cmd?, lang?, path?, junit?, coverage?, root? | Record per-spec unit-test evidence into test-report.json. With run it executes the tests (per-language default or cmd) and parses JUnit + coverage; lang/path auto-discover reports; a failing run exits non-zero and gates the task. | | csdd_spec_diff_report | feature, base?, maxLines?, root? | Record an auditable file diff (merge-base of the base ref → working tree) into diff-report.json for the dashboard's Changes view. base overrides auto-detection; maxLines caps recorded lines/file. Read-only; requires git. |

Phase gates (enforced, not advisory): design needs requirements approved; tasks needs design approved. Generating out of order fails with exit 2 unless force is passed. ready_for_implementation flips to true only when all three phases are approved. research and bugfix are ungated.

🛠️ skill — workflow bundles (.claude/skills/<name>/)

| Tool | Parameters | What it does | |------|------------|--------------| | csdd_skill_create | name, description, title?, root? | Create .claude/skills/<name>/ with SKILL.md (+ references/, assets/, scripts/). description is the one-line activation trigger. The tool scaffolds the file — author the body by editing SKILL.md directly. | | csdd_skill_list | root? | List skills with their descriptions. | | csdd_skill_show | name, root? | List a skill's files and print SKILL.md. | | csdd_skill_add_reference | skill, file, root? | Add a reference file under references/. Path traversal is rejected. | | csdd_skill_add_script | skill, file, root? | Add a script file under scripts/. Path traversal is rejected. | | csdd_skill_add_asset | skill, file, root? | Add an asset file under assets/. Path traversal is rejected. | | csdd_skill_validate | name, root? | Validate structure + frontmatter; report line/token counts. Exit 2 on issues. | | csdd_skill_delete | name, force?, root? | Delete .claude/skills/<name>/ recursively (force required). |

🤖 agent — custom sub-agents (.claude/agents/<name>.md)

| Tool | Parameters | What it does | |------|------------|--------------| | csdd_agent_create | name, description, tools?[], model?, title?, force?, root? | Create a least-privilege sub-agent (default tools: Read, Grep). description tells the orchestrator when to pick it. Scaffolds the file; fill in the body by editing the generated .md. model ∈ sonnet · opus · haiku. | | csdd_agent_list | root? | List agents with their tools and descriptions. | | csdd_agent_show | name, root? | Print an agent file. | | csdd_agent_delete | name, force?, root? | Delete .claude/agents/<name>.md (force required). |

🧠 graph — the knowledge-base brain (docs/graph/)

Consult it before you grep. query/path/explain/analyze rebuild the graph in memory from the corpus, so their answers are always current even if the committed graph.json.gz is stale.

| Tool | Parameters | What it does | |------|------------|--------------| | csdd_graph_build | full?, json?, root? | Rebuild docs/graph/graph.json.gz from the corpus (specs, plans, ADRs, wiki, glossary, stack, CLAUDE.md, Go source). Incremental by default; full forces a complete rebuild. | | csdd_graph_query | terms, hops?, budget?, json?, root? | Find nodes matching terms and show their neighborhood — the fast way to locate an artifact and what connects to it. Quote multi-word queries. | | csdd_graph_path | from, to, maxHops?, json?, root? | Shortest path between two nodes. Reports each endpoint's match tier (exact / prefix / substring), so a fuzzy resolution is never mistaken for an exact one. | | csdd_graph_explain | label, json?, root? | A node and all its connections, ordered by neighbor degree. | | csdd_graph_analyze | strict?, json?, root? | Traceability gaps + wiki/tech/plan/glossary/collision lints. strict exits non-zero (2) on any finding — the CI gate. | | csdd_graph_export | out?, json?, root? | Write docs/graph/graph.html — a self-contained interactive visualization. |

Not here: managing the .mcp.json servers themselves (csdd mcp add/list/ remove/enable/disable/validate) stays on the CLI — same for csdd init, csdd update, and csdd export. Keeping setup off the tool surface is intentional (see Scope).

A typical agent flow

Setup is a one-time CLI step (npx @protonspy/csdd init --with-baseline, which also registers this server). From there the agent drives the feature with tools:

csdd_spec_init      { "feature": "photo-albums" }

csdd_spec_generate  { "feature": "photo-albums", "artifact": "requirements" }
csdd_spec_validate  { "feature": "photo-albums" }            // exit 2 → fix what it flags
csdd_spec_approve   { "feature": "photo-albums", "phase": "requirements" }

csdd_spec_generate  { "feature": "photo-albums", "artifact": "design" }   // gated on the approval above
csdd_spec_approve   { "feature": "photo-albums", "phase": "design" }

csdd_spec_generate  { "feature": "photo-albums", "artifact": "tasks" }
csdd_spec_approve   { "feature": "photo-albums", "phase": "tasks" }
// → spec.json: ready_for_implementation = true

csdd_spec_status { "feature": "photo-albums" } between steps shows phase, approvals, and validation issues in one call.

Development

npm install
npm run build      # tsc → dist/
npm test           # build + Node's built-in test runner (node:test)
npm run test:run   # tests only, against the current dist/ (no rebuild)
npm run dev        # tsc --watch

Tests are TypeScript run through node:test with native type stripping, so they need Node ≥ 22.18 (dev-only — the published package still targets Node ≥ 18). They exercise the argv builders, result formatting, binary resolution, runCsdd against a stub binary, and every tool's argv mapping. See test/.

License

MIT