contract-driven-delivery 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [2.1.1] - 2026-05-29
+
+MCP tool access for graph/code-map exploration.
+
+### Added
+
+- **`cdd-kit mcp`**: runs a stdio MCP server exposing graph and code-map tools
+  (`cdd_graph_status`, `cdd_graph_context`, `cdd_graph_query`,
+  `cdd_graph_impact`, `cdd_index_query`, `cdd_index_impact`) so AI agents can
+  use project exploration as native tools instead of shell-only commands.
+
 ## [2.1.0] - 2026-05-27
 
 Native code graph and symptom-driven bug-fix workflow.

package/README.md

@@ -713,6 +713,31 @@ Use `--engine native` for the built-in graph, `--engine codemap` for the older
 code-map-only fallback, `--engine codegraph` to require external CodeGraph, or
 `CDD_CODEGRAPH_BIN=/path/to/codegraph` to point at a custom binary.
 
+### `cdd-kit mcp`
+
+`cdd-kit mcp` runs a stdio MCP server so agents can call the graph/index layer
+as tools instead of shelling out manually.
+
+```json
+{
+  "mcpServers": {
+    "cdd-kit": {
+      "command": "cdd-kit",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Exposed tools:
+
+- `cdd_graph_status`
+- `cdd_graph_context`
+- `cdd_graph_query`
+- `cdd_graph_impact`
+- `cdd_index_query`
+- `cdd_index_impact`
+
 Large Python repos are scanned in chunks (`CDD_CODE_MAP_BATCH_SIZE`, default 400)
 so one slow batch cannot drop the whole language. Raise
 `CDD_CODE_MAP_TIMEOUT_MS` (default 30000) if a single batch still times out.

package/assets/skills/contract-driven-delivery/references/code-map-protocol.md

@@ -9,7 +9,16 @@ auto-refreshing `cdd-kit index ...` commands for that job.
 
 ## Preferred workflow: graph/query before reading
 
-Before reading source, use the graph layer when available:
+Before reading source, use the graph layer when available. If the `cdd-kit`
+MCP server is configured, prefer these tools:
+
+- `cdd_graph_context`
+- `cdd_graph_query`
+- `cdd_graph_impact`
+- `cdd_index_query`
+- `cdd_index_impact`
+
+If MCP tools are not available, use the equivalent CLI commands:
 
 ```bash
 cdd-kit graph context "fix login redirect bug"

package/dist/cli/index.js

@@ -11816,6 +11816,315 @@ var init_graph = __esm({
   }
 });
 
+// src/mcp/server.ts
+var server_exports = {};
+__export(server_exports, {
+  runMcpServer: () => runMcpServer
+});
+import { spawnSync as spawnSync4 } from "child_process";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { createInterface } from "readline";
+async function runMcpServer(opts) {
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line.trim())
+      continue;
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch (err) {
+      writeError(null, -32700, `Parse error: ${err.message}`);
+      continue;
+    }
+    if (!request.method) {
+      if ("id" in request)
+        writeError(request.id ?? null, -32600, "Invalid Request: missing method");
+      continue;
+    }
+    try {
+      const result = await handleRequest(request, opts);
+      if ("id" in request)
+        writeResult(request.id ?? null, result);
+    } catch (err) {
+      if ("id" in request)
+        writeError(request.id ?? null, -32e3, err.message);
+    }
+  }
+}
+async function handleRequest(request, opts) {
+  switch (request.method) {
+    case "initialize": {
+      const params = asObject(request.params);
+      return {
+        protocolVersion: typeof params.protocolVersion === "string" ? params.protocolVersion : "2024-11-05",
+        capabilities: {
+          tools: { listChanged: false },
+          resources: {},
+          prompts: {}
+        },
+        serverInfo: {
+          name: "cdd-kit",
+          version: opts.version
+        }
+      };
+    }
+    case "ping":
+      return {};
+    case "tools/list":
+      return { tools };
+    case "tools/call": {
+      const params = asObject(request.params);
+      const name = requireString(params, "name");
+      const args = asObject(params.arguments);
+      return callTool(name, args);
+    }
+    case "resources/list":
+      return { resources: [] };
+    case "prompts/list":
+      return { prompts: [] };
+    case "notifications/initialized":
+      return {};
+    default:
+      throw new Error(`Method not found: ${request.method}`);
+  }
+}
+function callTool(name, args) {
+  switch (name) {
+    case "cdd_graph_status":
+      return runCddJson([
+        "graph",
+        "status",
+        "--engine",
+        optionalString(args.engine, "auto"),
+        "--map",
+        optionalString(args.map, DEFAULT_MAP),
+        "--json"
+      ]);
+    case "cdd_graph_query":
+      return runCddJson([
+        "graph",
+        "query",
+        requireString(args, "query"),
+        "--engine",
+        optionalString(args.engine, "auto"),
+        "--map",
+        optionalString(args.map, DEFAULT_MAP),
+        "--limit",
+        String(optionalInt(args.limit, 10)),
+        "--json",
+        ...refreshArgs(args)
+      ]);
+    case "cdd_graph_context":
+      return runCddJson([
+        "graph",
+        "context",
+        requireString(args, "task"),
+        "--engine",
+        optionalString(args.engine, "auto"),
+        "--map",
+        optionalString(args.map, DEFAULT_MAP),
+        "--max-nodes",
+        String(optionalInt(args.maxNodes, 20)),
+        "--json",
+        ...refreshArgs(args)
+      ]);
+    case "cdd_graph_impact":
+      return runCddJson([
+        "graph",
+        "impact",
+        requireString(args, "target"),
+        "--engine",
+        optionalString(args.engine, "auto"),
+        "--map",
+        optionalString(args.map, DEFAULT_MAP),
+        "--limit",
+        String(optionalInt(args.limit, 20)),
+        "--depth",
+        String(optionalInt(args.depth, 2)),
+        "--json",
+        ...refreshArgs(args)
+      ]);
+    case "cdd_index_query":
+      return runCddJson([
+        "index",
+        "query",
+        requireString(args, "query"),
+        "--map",
+        optionalString(args.map, DEFAULT_MAP),
+        "--limit",
+        String(optionalInt(args.limit, 10)),
+        "--json",
+        ...refreshArgs(args)
+      ]);
+    case "cdd_index_impact":
+      return runCddJson([
+        "index",
+        "impact",
+        requireString(args, "target"),
+        "--map",
+        optionalString(args.map, DEFAULT_MAP),
+        "--limit",
+        String(optionalInt(args.limit, 20)),
+        "--json",
+        ...refreshArgs(args)
+      ]);
+    default:
+      return {
+        isError: true,
+        content: [{ type: "text", text: `Unknown tool: ${name}` }]
+      };
+  }
+}
+function runCddJson(args) {
+  const cliPath = process.argv[1] || fileURLToPath3(import.meta.url);
+  const result = spawnSync4(process.execPath, [cliPath, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    encoding: "utf8"
+  });
+  const stdout = result.stdout?.trim() ?? "";
+  const stderr = result.stderr?.trim() ?? "";
+  const isError = !!result.error || (result.status ?? 1) !== 0;
+  if (stdout) {
+    return {
+      isError: isError || void 0,
+      content: [{ type: "text", text: stdout }]
+    };
+  }
+  return {
+    isError: true,
+    content: [{ type: "text", text: result.error?.message || stderr || `cdd-kit exited with status ${result.status}` }]
+  };
+}
+function refreshArgs(args) {
+  return args.refresh === false ? ["--no-refresh"] : [];
+}
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function requireString(args, key) {
+  const value = args[key];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`Missing required string argument: ${key}`);
+  }
+  return value;
+}
+function optionalString(value, fallback) {
+  return typeof value === "string" && value.trim() ? value : fallback;
+}
+function optionalInt(value, fallback) {
+  const parsed = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : fallback;
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function writeResult(id, result) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}
+`);
+}
+function writeError(id, code, message) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })}
+`);
+}
+var DEFAULT_MAP, tools;
+var init_server = __esm({
+  "src/mcp/server.ts"() {
+    "use strict";
+    DEFAULT_MAP = ".cdd/code-map.yml";
+    tools = [
+      {
+        name: "cdd_graph_status",
+        description: "Show the active cdd-kit graph engine and code-map/code-graph freshness for the current workspace.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
+            engine: { type: "string", enum: ["auto", "native", "codegraph", "codemap"], default: "auto" }
+          },
+          additionalProperties: false
+        }
+      },
+      {
+        name: "cdd_graph_query",
+        description: "Search native graph symbols/files and return candidate nodes with line ranges.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Symbol, file path, file stem, class, function, component, or route term." },
+            limit: { type: "integer", minimum: 1, maximum: 100, default: 10 },
+            map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
+            engine: { type: "string", enum: ["auto", "native", "codegraph", "codemap"], default: "auto" },
+            refresh: { type: "boolean", default: true }
+          },
+          required: ["query"],
+          additionalProperties: false
+        }
+      },
+      {
+        name: "cdd_graph_context",
+        description: "Build graph-first task context from a task, symptom, or known feature term.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            task: { type: "string", description: "Task, bug symptom, feature name, screen name, or domain term." },
+            maxNodes: { type: "integer", minimum: 1, maximum: 100, default: 20 },
+            map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
+            engine: { type: "string", enum: ["auto", "native", "codegraph", "codemap"], default: "auto" },
+            refresh: { type: "boolean", default: true }
+          },
+          required: ["task"],
+          additionalProperties: false
+        }
+      },
+      {
+        name: "cdd_graph_impact",
+        description: "Analyze callers, callees, imports, references, and dependents for a file or symbol before editing.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: { type: "string", description: "Candidate file path, symbol, graph node id, or qualified name." },
+            depth: { type: "integer", minimum: 1, maximum: 10, default: 2 },
+            limit: { type: "integer", minimum: 1, maximum: 200, default: 20 },
+            map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
+            engine: { type: "string", enum: ["auto", "native", "codegraph", "codemap"], default: "auto" },
+            refresh: { type: "boolean", default: true }
+          },
+          required: ["target"],
+          additionalProperties: false
+        }
+      },
+      {
+        name: "cdd_index_query",
+        description: "Fallback code-map query for files, symbols, imports, and line ranges.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string", description: "Symbol, file path, import module, enum member, or substring." },
+            limit: { type: "integer", minimum: 1, maximum: 100, default: 10 },
+            map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
+            refresh: { type: "boolean", default: true }
+          },
+          required: ["query"],
+          additionalProperties: false
+        }
+      },
+      {
+        name: "cdd_index_impact",
+        description: "Fallback code-map impact query for local imports and direct dependents.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            target: { type: "string", description: "File path or unique symbol." },
+            limit: { type: "integer", minimum: 1, maximum: 200, default: 20 },
+            map: { type: "string", description: "Code-map YAML path.", default: DEFAULT_MAP },
+            refresh: { type: "boolean", default: true }
+          },
+          required: ["target"],
+          additionalProperties: false
+        }
+      }
+    ];
+  }
+});
+
 // src/commands/archive.ts
 var archive_exports = {};
 __export(archive_exports, {
@@ -12358,7 +12667,7 @@ var init_context = __esm({
 // src/cli/index.ts
 import { readFileSync as readFileSync31 } from "fs";
 import os from "os";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { fileURLToPath as fileURLToPath4 } from "url";
 import { dirname as dirname7, join as join30 } from "path";
 import { Command } from "commander";
 
@@ -13464,7 +13773,7 @@ async function installHooks() {
 }
 
 // src/cli/index.ts
-var __dirname2 = dirname7(fileURLToPath3(import.meta.url));
+var __dirname2 = dirname7(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(readFileSync31(join30(__dirname2, "..", "..", "package.json"), "utf8"));
 var program = new Command();
 program.name("cdd-kit").description("Contract-Driven Delivery Kit CLI").version(pkg.version);
@@ -13622,6 +13931,10 @@ graph.command("context <task>").description("Build task context with native grap
   });
   process.exit(exit);
 });
+program.command("mcp").description("Run the cdd-kit MCP stdio server exposing graph and code-map tools").action(async () => {
+  const { runMcpServer: runMcpServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
+  await runMcpServer2({ version: pkg.version });
+});
 program.command("gate <change-id>").description("Run delivery-quality gate for a change (required artifacts, tasks, tier, contracts)").option("--strict", "Treat pending tasks (except section 7) as errors", false).action(async (id, opts) => {
   await gate(id, { strict: opts.strict });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Contract-driven delivery kit for AI coding agents with deterministic context indexes, manifest-backed read-scope governance, and orchestrated contracts-first delivery.",
   "keywords": [
     "contract-driven",