@protonspy/csdd-mcp 0.1.1

package/README.md

@@ -0,0 +1,232 @@
+# @protonspy/csdd-mcp
+
+**An [MCP](https://modelcontextprotocol.io) server that exposes the [`csdd`](https://github.com/protonspy/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](#locating-the-csdd-binary).
+
+---
+
+## Install & configure
+
+The server runs over **stdio**; point your MCP client at it.
+
+### Claude Code
+
+```bash
+# 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:
+
+```json
+{
+  "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
+
+**27 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 only the iterative development-flow resources
+> (steering · spec · skill · agent). **Workspace setup and config management are
+> deliberately not tools** — `csdd init`, `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). |
+
+> **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. |
+| `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. `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). |
+
+> **Not here:** managing the `.mcp.json` servers themselves (`csdd mcp add/list/
+> remove/enable/disable/validate`) stays on the CLI — same for `csdd init` 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:
+
+```jsonc
+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
+
+```bash
+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

package/dist/csdd.js

@@ -0,0 +1,98 @@
+// Resolve the csdd binary and run it headlessly, capturing structured output.
+//
+// Resolution order (first hit wins):
+//   1. $CSDD_BIN                          — explicit override
+//   2. platform optionalDependency        — @protonspy/csdd-<platform>-<arch>
+//      (the same packages the npm launcher uses)
+//   3. sibling repo binary                — ../csdd (when running from the repo)
+//   4. "csdd" on $PATH                     — last-resort lookup at spawn time
+import { execFile } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+// platform/arch -> npm package name (must match the npm launcher's TARGETS).
+const PKG = {
+    "linux-x64": "@protonspy/csdd-linux-x64",
+    "linux-arm64": "@protonspy/csdd-linux-arm64",
+    "darwin-x64": "@protonspy/csdd-darwin-x64",
+    "darwin-arm64": "@protonspy/csdd-darwin-arm64",
+    "win32-x64": "@protonspy/csdd-win32-x64",
+};
+const binName = process.platform === "win32" ? "csdd.exe" : "csdd";
+function fromPlatformPackage() {
+    const pkgName = PKG[`${process.platform}-${process.arch}`];
+    if (!pkgName)
+        return null;
+    try {
+        const pkgJson = require.resolve(`${pkgName}/package.json`);
+        const candidate = join(pkgJson, "..", "bin", binName);
+        return existsSync(candidate) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+function fromSiblingRepo() {
+    // dist/csdd.js -> packageRoot = mcp-server -> repo root holds ./csdd
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const up of ["..", "../.."]) {
+        const candidate = join(here, up, binName);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+let cached = null;
+/** Locate the csdd binary, caching the result. Falls back to a bare "csdd". */
+export function resolveCsddBin() {
+    if (cached)
+        return cached;
+    cached =
+        process.env.CSDD_BIN ||
+            fromPlatformPackage() ||
+            fromSiblingRepo() ||
+            binName; // let the OS resolve it on $PATH at spawn time
+    return cached;
+}
+/**
+ * Run `csdd` with the given argv. Never rejects on a non-zero exit — the exit
+ * code is returned so each tool can map it to an MCP error result.
+ * `cwd` controls workspace discovery when no --root flag is passed.
+ */
+export function runCsdd(argv, cwd) {
+    const bin = resolveCsddBin();
+    return new Promise((resolve) => {
+        execFile(bin, argv, {
+            cwd: cwd || process.cwd(),
+            // NO_COLOR keeps output free of ANSI escapes; csdd is non-interactive
+            // (confirm() returns false) when stdin is not a TTY, which it isn't here.
+            env: { ...process.env, NO_COLOR: "1" },
+            maxBuffer: 16 * 1024 * 1024,
+            windowsHide: true,
+        }, (err, stdout, stderr) => {
+            const code = err && typeof err.code === "string"
+                ? // spawn failure (ENOENT etc.) — surface as exit 127
+                    127
+                : (err?.code ?? 0);
+            if (err && code === 127) {
+                resolve({
+                    ok: false,
+                    exitCode: 127,
+                    stdout: stdout?.toString() ?? "",
+                    stderr: (stderr?.toString() ?? "") +
+                        `\ncsdd binary not found or not executable: ${bin}\n` +
+                        `Set CSDD_BIN, install @protonspy/csdd, or put csdd on PATH.`,
+                });
+                return;
+            }
+            resolve({
+                ok: code === 0,
+                exitCode: typeof code === "number" ? code : 1,
+                stdout: stdout?.toString() ?? "",
+                stderr: stderr?.toString() ?? "",
+            });
+        });
+    });
+}

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// csdd-mcp — an MCP server (stdio) that exposes the csdd CLI as one tool per
+// subcommand. Each tool shells out to the csdd binary headlessly and returns
+// its stdout/stderr; non-zero exits are surfaced as MCP errors (exit 2 =
+// validation failure).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { makeHandler } from "./tooldef.js";
+import { allTools } from "./registry.js";
+const version = "0.1.0";
+async function main() {
+    const server = new McpServer({ name: "csdd-mcp", version });
+    for (const def of allTools) {
+        server.registerTool(def.name, {
+            title: def.title,
+            description: def.description,
+            inputSchema: def.inputSchema,
+        }, makeHandler(def));
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Never resolves; the process stays alive serving stdio until the client
+    // closes the pipe.
+}
+main().catch((err) => {
+    process.stderr.write(`csdd-mcp fatal: ${err?.stack || err}\n`);
+    process.exit(1);
+});

package/dist/registry.js

@@ -0,0 +1,20 @@
+import { steeringTools } from "./tools/steering.js";
+import { specTools } from "./tools/spec.js";
+import { skillTools } from "./tools/skill.js";
+import { agentTools } from "./tools/agent.js";
+export const miscTools = [
+    {
+        name: "csdd_version",
+        title: "csdd version",
+        description: "Print the version of the underlying csdd binary (diagnostic).",
+        inputSchema: {},
+        toArgs: () => ["version"],
+    },
+];
+export const allTools = [
+    ...miscTools,
+    ...steeringTools,
+    ...specTools,
+    ...skillTools,
+    ...agentTools,
+];

package/dist/tooldef.js

@@ -0,0 +1,63 @@
+// Shared types + helpers for declaring csdd-backed MCP tools.
+import { z } from "zod";
+import { runCsdd } from "./csdd.js";
+// --- argv builders ---------------------------------------------------------
+/** `--flag value` when value is a non-empty string/number, else nothing. */
+export function flag(name, value) {
+    if (value === undefined || value === null || value === "")
+        return [];
+    return [name, String(value)];
+}
+/** `--flag` when truthy, else nothing. */
+export function bool(name, value) {
+    return value ? [name] : [];
+}
+/** Repeat `--flag value` for each item. */
+export function multi(name, values) {
+    if (!Array.isArray(values))
+        return [];
+    return values.flatMap((v) => [name, String(v)]);
+}
+/** Standard `--root` passthrough (most commands accept it). */
+export function rootArg(params) {
+    return flag("--root", params.root);
+}
+// Reusable field schemas -----------------------------------------------------
+export const rootField = z
+    .string()
+    .optional()
+    .describe("Workspace root (the directory containing .claude/). Defaults to walking up from the current directory.");
+export const forceField = z
+    .boolean()
+    .optional()
+    .describe("Bypass safety checks / overwrite or delete without confirmation.");
+// --- result formatting -----------------------------------------------------
+/** Turn a csdd run into an MCP tool result, flagging non-zero exits. */
+export function toMcpResult(r) {
+    const parts = [];
+    if (r.stdout.trim())
+        parts.push(r.stdout.trimEnd());
+    if (r.stderr.trim())
+        parts.push((r.ok ? "" : "[stderr] ") + r.stderr.trimEnd());
+    if (parts.length === 0) {
+        parts.push(r.ok ? "(ok, no output)" : `csdd exited with code ${r.exitCode}`);
+    }
+    // Exit 2 = validation failure; surface it distinctly in the text.
+    const header = r.exitCode === 2
+        ? "csdd validation failed (exit 2):\n"
+        : r.ok
+            ? ""
+            : `csdd failed (exit ${r.exitCode}):\n`;
+    return {
+        content: [{ type: "text", text: header + parts.join("\n\n") }],
+        isError: !r.ok,
+    };
+}
+/** Build the handler that runs a ToolDef's argv and formats the result. */
+export function makeHandler(def) {
+    return async (params) => {
+        const argv = def.toArgs(params ?? {});
+        const result = await runCsdd(argv, params?.root);
+        return toMcpResult(result);
+    };
+}

package/dist/tools/agent.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { bool, flag, forceField, multi, rootArg, rootField, } from "../tooldef.js";
+const agentName = z.string().describe("Agent name (.claude/agents/<name>.md).");
+export const agentTools = [
+    {
+        name: "csdd_agent_create",
+        title: "Agent create",
+        description: "Create a custom sub-agent with least-privilege tools (default: Read, Grep). Description tells the orchestrator when to pick it.",
+        inputSchema: {
+            name: agentName,
+            description: z.string().describe("When the orchestrator should select this agent."),
+            tools: z
+                .array(z.string())
+                .optional()
+                .describe("Tool names to grant (e.g. Read, Grep, Bash, Edit). Repeatable."),
+            model: z.string().optional().describe("Model override (e.g. sonnet, opus, haiku)."),
+            title: z.string().optional().describe("Document title (defaults to Title Case of name)."),
+            force: forceField,
+            root: rootField,
+        },
+        toArgs: (p) => [
+            "agent",
+            "create",
+            p.name,
+            ...flag("--description", p.description),
+            ...multi("--tools", p.tools),
+            ...flag("--model", p.model),
+            ...flag("--title", p.title),
+            ...bool("--force", p.force),
+            ...rootArg(p),
+        ],
+    },
+    {
+        name: "csdd_agent_list",
+        title: "Agent list",
+        description: "List agents with their tools and descriptions.",
+        inputSchema: { root: rootField },
+        toArgs: (p) => ["agent", "list", ...rootArg(p)],
+    },
+    {
+        name: "csdd_agent_show",
+        title: "Agent show",
+        description: "Print an agent file.",
+        inputSchema: { name: agentName, root: rootField },
+        toArgs: (p) => ["agent", "show", p.name, ...rootArg(p)],
+    },
+    {
+        name: "csdd_agent_delete",
+        title: "Agent delete",
+        description: "Delete .claude/agents/<name>.md. Requires force.",
+        inputSchema: { name: agentName, force: forceField, root: rootField },
+        toArgs: (p) => ["agent", "delete", p.name, ...bool("--force", p.force), ...rootArg(p)],
+    },
+];

package/dist/tools/skill.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { bool, flag, forceField, rootArg, rootField } from "../tooldef.js";
+const skillName = z.string().describe("Skill name (.claude/skills/<name>/).");
+function addArtifact(action, kind) {
+    return {
+        name: `csdd_skill_add_${action.replace("add-", "")}`,
+        title: `Skill add ${kind}`,
+        description: `Add a ${kind} file under .claude/skills/<skill>/${kind}s/ with a placeholder. Path traversal is rejected.`,
+        inputSchema: {
+            skill: skillName,
+            file: z.string().describe(`File path relative to the ${kind}s/ subdir.`),
+            root: rootField,
+        },
+        toArgs: (p) => ["skill", action, p.skill, p.file, ...rootArg(p)],
+    };
+}
+export const skillTools = [
+    {
+        name: "csdd_skill_create",
+        title: "Skill create",
+        description: "Create .claude/skills/<name>/ with SKILL.md (+ references/, assets/, scripts/). Description is the one-line activation trigger.",
+        inputSchema: {
+            name: skillName,
+            description: z.string().describe("One-sentence activation trigger for the skill."),
+            title: z.string().optional().describe("Document title (defaults to Title Case of name)."),
+            root: rootField,
+        },
+        toArgs: (p) => [
+            "skill",
+            "create",
+            p.name,
+            ...flag("--description", p.description),
+            ...flag("--title", p.title),
+            ...rootArg(p),
+        ],
+    },
+    {
+        name: "csdd_skill_list",
+        title: "Skill list",
+        description: "List skills with their descriptions.",
+        inputSchema: { root: rootField },
+        toArgs: (p) => ["skill", "list", ...rootArg(p)],
+    },
+    {
+        name: "csdd_skill_show",
+        title: "Skill show",
+        description: "List a skill's files and print SKILL.md.",
+        inputSchema: { name: skillName, root: rootField },
+        toArgs: (p) => ["skill", "show", p.name, ...rootArg(p)],
+    },
+    addArtifact("add-reference", "reference"),
+    addArtifact("add-script", "script"),
+    addArtifact("add-asset", "asset"),
+    {
+        name: "csdd_skill_validate",
+        title: "Skill validate",
+        description: "Validate skill structure + frontmatter; report line/token counts. Exit 2 on issues.",
+        inputSchema: { name: skillName, root: rootField },
+        toArgs: (p) => ["skill", "validate", p.name, ...rootArg(p)],
+    },
+    {
+        name: "csdd_skill_delete",
+        title: "Skill delete",
+        description: "Delete .claude/skills/<name>/ recursively. Requires force.",
+        inputSchema: { name: skillName, force: forceField, root: rootField },
+        toArgs: (p) => ["skill", "delete", p.name, ...bool("--force", p.force), ...rootArg(p)],
+    },
+];

package/dist/tools/spec.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { bool, flag, forceField, rootArg, rootField } from "../tooldef.js";
+const feature = z.string().describe("Feature name (specs/<feature>/).");
+export const specTools = [
+    {
+        name: "csdd_spec_init",
+        title: "Spec init",
+        description: "Create specs/<feature>/spec.json (phase=initial, no approvals, not ready for implementation).",
+        inputSchema: {
+            feature,
+            language: z.string().optional().describe("Spec language (default: en)."),
+            root: rootField,
+        },
+        toArgs: (p) => ["spec", "init", p.feature, ...flag("--language", p.language), ...rootArg(p)],
+    },
+    {
+        name: "csdd_spec_list",
+        title: "Spec list",
+        description: "List specs with current phase, approved phases, and readiness.",
+        inputSchema: { root: rootField },
+        toArgs: (p) => ["spec", "list", ...rootArg(p)],
+    },
+    {
+        name: "csdd_spec_show",
+        title: "Spec show",
+        description: "Show a spec's metadata (spec.json) and its artifacts.",
+        inputSchema: { feature, root: rootField },
+        toArgs: (p) => ["spec", "show", p.feature, ...rootArg(p)],
+    },
+    {
+        name: "csdd_spec_status",
+        title: "Spec status",
+        description: "Combined show + validate for a spec.",
+        inputSchema: { feature, root: rootField },
+        toArgs: (p) => ["spec", "status", p.feature, ...rootArg(p)],
+    },
+    {
+        name: "csdd_spec_generate",
+        title: "Spec generate artifact",
+        description: "Generate a spec artifact. Phase gates apply: design needs requirements approved, tasks needs design approved (use force to bypass). research/bugfix are ungated.",
+        inputSchema: {
+            feature,
+            artifact: z
+                .enum(["requirements", "design", "tasks", "research", "bugfix"])
+                .describe("Which artifact to generate."),
+            force: forceField,
+            root: rootField,
+        },
+        toArgs: (p) => [
+            "spec",
+            "generate",
+            p.feature,
+            ...flag("--artifact", p.artifact),
+            ...bool("--force", p.force),
+            ...rootArg(p),
+        ],
+    },
+    {
+        name: "csdd_spec_approve",
+        title: "Spec approve phase",
+        description: "Approve a spec phase (requirements|design|tasks). Validates first; force approves despite issues/missing prior approvals. Sets ready_for_implementation only when all three are approved.",
+        inputSchema: {
+            feature,
+            phase: z.enum(["requirements", "design", "tasks"]).describe("Phase to approve."),
+            force: forceField,
+            root: rootField,
+        },
+        toArgs: (p) => [
+            "spec",
+            "approve",
+            p.feature,
+            ...flag("--phase", p.phase),
+            ...bool("--force", p.force),
+            ...rootArg(p),
+        ],
+    },
+    {
+        name: "csdd_spec_validate",
+        title: "Spec validate",
+        description: "Validate a spec: EARS phrasing, traceability, task annotations, parallel safety. Exit 2 on issues.",
+        inputSchema: { feature, root: rootField },
+        toArgs: (p) => ["spec", "validate", p.feature, ...rootArg(p)],
+    },
+    {
+        name: "csdd_spec_delete",
+        title: "Spec delete",
+        description: "Delete specs/<feature>/ recursively. Requires force.",
+        inputSchema: { feature, force: forceField, root: rootField },
+        toArgs: (p) => ["spec", "delete", p.feature, ...bool("--force", p.force), ...rootArg(p)],
+    },
+];

package/dist/tools/steering.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { bool, flag, forceField, multi, rootArg, rootField, } from "../tooldef.js";
+const inclusion = z
+    .enum(["always", "fileMatch", "manual", "auto"])
+    .describe("When the steering loads: always (always-on), fileMatch (when files match --pattern), manual (#name), auto (when description matches context).");
+export const steeringTools = [
+    {
+        name: "csdd_steering_init",
+        title: "Steering init",
+        description: "Create .claude/steering/ and populate the 6 standard files (product, tech, structure, security, testing, api-conventions).",
+        inputSchema: { root: rootField },
+        toArgs: (p) => ["steering", "init", ...rootArg(p)],
+    },
+    {
+        name: "csdd_steering_create",
+        title: "Steering create",
+        description: "Create a custom steering file with inclusion metadata. fileMatch requires at least one pattern; auto requires a description.",
+        inputSchema: {
+            name: z.string().describe("Steering file name (no extension)."),
+            inclusion,
+            pattern: z
+                .array(z.string())
+                .optional()
+                .describe("Glob pattern(s) for fileMatch inclusion. Repeatable."),
+            description: z
+                .string()
+                .optional()
+                .describe("One-line description; required for auto inclusion."),
+            title: z.string().optional().describe("Document title (defaults to Title Case of name)."),
+            force: forceField,
+            root: rootField,
+        },
+        toArgs: (p) => [
+            "steering",
+            "create",
+            p.name,
+            ...flag("--inclusion", p.inclusion),
+            ...multi("--pattern", p.pattern),
+            ...flag("--description", p.description),
+            ...flag("--title", p.title),
+            ...bool("--force", p.force),
+            ...rootArg(p),
+        ],
+    },
+    {
+        name: "csdd_steering_list",
+        title: "Steering list",
+        description: "List steering files with inclusion mode and inclusion-specific extras.",
+        inputSchema: {
+            root: rootField,
+            inclusion: inclusion.optional().describe("Filter by inclusion mode."),
+        },
+        toArgs: (p) => ["steering", "list", ...rootArg(p), ...flag("--inclusion", p.inclusion)],
+    },
+    {
+        name: "csdd_steering_show",
+        title: "Steering show",
+        description: "Print a steering file (frontmatter + body).",
+        inputSchema: { name: z.string().describe("Steering file name."), root: rootField },
+        toArgs: (p) => ["steering", "show", p.name, ...rootArg(p)],
+    },
+    {
+        name: "csdd_steering_delete",
+        title: "Steering delete",
+        description: "Delete a steering file. Requires force. Foundational files (product, tech, structure) are protected.",
+        inputSchema: {
+            name: z.string().describe("Steering file name."),
+            force: forceField,
+            root: rootField,
+        },
+        toArgs: (p) => ["steering", "delete", p.name, ...bool("--force", p.force), ...rootArg(p)],
+    },
+    {
+        name: "csdd_steering_validate",
+        title: "Steering validate",
+        description: "Validate steering frontmatter and structure. Omit name to validate all. Exit 2 on issues.",
+        inputSchema: {
+            name: z.string().optional().describe("Validate only this file; omit for all."),
+            root: rootField,
+        },
+        toArgs: (p) => ["steering", "validate", ...(p.name ? [p.name] : []), ...rootArg(p)],
+    },
+];

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@protonspy/csdd-mcp",
+  "version": "0.1.1",
+  "description": "MCP server exposing the csdd CLI over stdio (one tool per subcommand).",
+  "homepage": "https://github.com/protonspy/csdd/tree/main/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/protonspy/csdd/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/protonspy/csdd.git",
+    "directory": "mcp-server"
+  },
+  "type": "module",
+  "bin": {
+    "csdd-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "csdd",
+    "claude-code",
+    "sdd"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "optionalDependencies": {
+    "@protonspy/csdd-linux-x64": "0.1.1",
+    "@protonspy/csdd-linux-arm64": "0.1.1",
+    "@protonspy/csdd-darwin-x64": "0.1.1",
+    "@protonspy/csdd-darwin-arm64": "0.1.1",
+    "@protonspy/csdd-win32-x64": "0.1.1"
+  }
+}