contract-driven-delivery 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [2.1.2] - 2026-05-29
+
+Recommended MCP setup during install and upgrade.
+
+### Changed
+
+- `cdd-kit init` and `cdd-kit refresh` now explicitly recommend enabling the
+  `cdd-kit mcp` server so AI agents use graph/code-map tools directly.
+- `CLAUDE.md`, `CODEX.md`, README, and install guide now present MCP graph tools
+  as the recommended project exploration path, with `cdd-kit graph/index` as
+  fallback.
+
+## [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

@@ -275,6 +275,12 @@ Creates: `contracts/`, `specs/templates/`, provider guidance files (`CLAUDE.md`,
 
 `.cdd/model-policy.json` stores role-to-model **classes** (`opus`, `sonnet`, `haiku`) instead of provider release IDs such as `claude-opus-4-7`. This keeps the policy stable across Claude and Codex adapters; provider-specific tooling can map the class to the concrete model available in that environment.
 
+Recommended: configure MCP-capable AI agents with `command: "cdd-kit"` and
+`args: ["mcp"]` after init. This exposes graph/code-map tools directly to the
+agent (`cdd_graph_context`, `cdd_graph_query`, `cdd_graph_impact`,
+`cdd_index_query`, `cdd_index_impact`) so project exploration does not depend on
+the agent remembering shell commands.
+
 ---
 
 ### `cdd-kit update`
@@ -307,6 +313,10 @@ cdd-kit migrate --all    # add new per-change scaffolds such as implementation-p
 cdd-kit doctor --strict
 ```
 
+After syncing, configure MCP-capable agents with `command: "cdd-kit"` and
+`args: ["mcp"]`. This is the recommended way for agents to use the regenerated
+code graph and code-map; shell commands remain the fallback.
+
 What gets updated:
 
 | command | updates | preserves |
@@ -389,6 +399,11 @@ cdd-kit refresh --yes --no-templates
 5. Resyncs `.cdd/model-policy.json` roles from installed agent frontmatter.
 6. Regenerates `.cdd/code-map.yml`.
 
+After `refresh --yes`, configure MCP-capable agents to run `cdd-kit mcp`.
+The MCP tools are the recommended graph/code-map exploration interface for AI
+agents; `cdd-kit graph ...` and `cdd-kit index ...` remain the fallback when MCP
+is not available.
+
 Run `cdd-kit migrate --all` separately when you need existing
 `specs/changes/*` directories to gain new required artifacts.
 
@@ -713,6 +728,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.
@@ -744,6 +784,9 @@ cdd-kit migrate --all
 cdd-kit doctor --strict
 ```
 
+Recommended agent setup after the refresh: enable the `cdd-kit` MCP server with
+args `["mcp"]` so agents use graph/code-map tools before opening source files.
+
 ### Old completed specs
 
 If a change is already finished, merged, or only kept for audit/history:
@@ -776,11 +819,12 @@ Then choose one path per active change:
 ### Recommended rollout for production repos already burned by token overuse
 
 1. Run `cdd-kit refresh --yes` once per repo after updating the npm package.
-2. Run `cdd-kit migrate --all` so existing active changes receive the current required artifact set.
-3. Review and fill `implementation-plan.md` before resuming implementation agents on active changes.
-4. Run `cdd-kit doctor --strict` in CI.
-5. Migrate active specs with `cdd-kit migrate --enable-context-governance` only after reviewing the generated manifest.
-6. Teach agents to use `cdd-kit context request/approve/reject/list` instead of silently widening context.
+2. Configure MCP-capable agents with `command: "cdd-kit"` and `args: ["mcp"]`.
+3. Run `cdd-kit migrate --all` so existing active changes receive the current required artifact set.
+4. Review and fill `implementation-plan.md` before resuming implementation agents on active changes.
+5. Run `cdd-kit doctor --strict` in CI.
+6. Migrate active specs with `cdd-kit migrate --enable-context-governance` only after reviewing the generated manifest.
+7. Teach agents to use `cdd-kit context request/approve/reject/list` instead of silently widening context.
 
 ---
 

package/assets/CLAUDE.template.md

@@ -42,6 +42,28 @@ This repository follows the Contract-Driven Delivery workflow.
 
 Run `cdd-kit detect-stack` to verify the detected tech stack.
 
+## Recommended MCP Tools
+
+Configure MCP-capable agents to use the cdd-kit server:
+
+```json
+{
+  "mcpServers": {
+    "cdd-kit": {
+      "command": "cdd-kit",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Prefer these MCP tools before reading source files: `cdd_graph_context`,
+`cdd_graph_query`, `cdd_graph_impact`, `cdd_index_query`, and
+`cdd_index_impact`. They use `.cdd/code-map.yml` and
+`.cdd/code-graph.index.json` as the project exploration layer. If MCP is not
+available, use the equivalent CLI commands: `cdd-kit graph ...` and
+`cdd-kit index ...`.
+
 ## Context Governance
 
 For context-governed changes, read `specs/changes/<change-id>/context-manifest.md` before using file-reading or broad search tools.

package/assets/CODEX.template.md

@@ -11,6 +11,28 @@ This project uses Contract-Driven Delivery (CDD).
 - Run `cdd-kit context-scan` before classification when project context may be stale.
 - Run `cdd-kit gate <change-id>` before proposing a commit or PR.
 
+## Recommended MCP Tools
+
+Configure MCP-capable agents to use the cdd-kit server:
+
+```json
+{
+  "mcpServers": {
+    "cdd-kit": {
+      "command": "cdd-kit",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Prefer these MCP tools before reading source files: `cdd_graph_context`,
+`cdd_graph_query`, `cdd_graph_impact`, `cdd_index_query`, and
+`cdd_index_impact`. They use `.cdd/code-map.yml` and
+`.cdd/code-graph.index.json` as the project exploration layer. If MCP is not
+available, use the equivalent CLI commands: `cdd-kit graph ...` and
+`cdd-kit index ...`.
+
 ## Context Governance
 
 Read `specs/changes/<change-id>/context-manifest.md` before using file-reading or search tools.

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

@@ -98,6 +98,21 @@ var init_logger = __esm({
   }
 });
 
+// src/utils/mcp-hint.ts
+function logRecommendedMcpSetup() {
+  log.info("Recommended for AI agents: enable the cdd-kit MCP server.");
+  log.dim("  MCP server command: cdd-kit");
+  log.dim('  MCP server args: ["mcp"]');
+  log.dim("  Tools exposed: cdd_graph_context, cdd_graph_query, cdd_graph_impact, cdd_index_query, cdd_index_impact");
+  log.dim("  Use MCP graph tools before source reads; CLI fallback: cdd-kit graph/index.");
+}
+var init_mcp_hint = __esm({
+  "src/utils/mcp-hint.ts"() {
+    "use strict";
+    init_logger();
+  }
+});
+
 // src/commands/code-map-hook.ts
 var code_map_hook_exports = {};
 __export(code_map_hook_exports, {
@@ -10283,8 +10298,10 @@ async function refresh(opts) {
     log.info("Next: review changes with `git diff`, then commit:");
     log.dim("  git add .cdd/code-map.yml .cdd/model-policy.json specs/templates tests/templates ci-templates .github/workflows");
     log.dim('  git commit -m "chore: cdd-kit refresh"');
+    logRecommendedMcpSetup();
   } else {
     log.info("Dry-run finished. Re-run with `--yes` to apply.");
+    log.info('After applying, configure MCP with command `cdd-kit` and args ["mcp"] so agents use graph/code-map tools directly.');
   }
   log.blank();
 }
@@ -10299,6 +10316,7 @@ var init_refresh = __esm({
     init_upgrade();
     init_code_map();
     init_code_map_hook();
+    init_mcp_hint();
     HOOKS_MARKER_PATH = ".cdd/.hooks-installed";
   }
 });
@@ -11816,6 +11834,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 +12685,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";
 
@@ -12534,6 +12861,7 @@ function detectStack(repoRoot) {
 }
 
 // src/commands/init.ts
+init_mcp_hint();
 function readCondaEnvName(cwd) {
   const envYml = join5(cwd, "environment.yml");
   if (!existsSync4(envYml))
@@ -12771,6 +13099,7 @@ async function init(opts) {
   } else {
     log.info("Use the contract-driven-delivery skill in Claude Code to scan this repo.");
   }
+  logRecommendedMcpSetup();
   log.blank();
 }
 
@@ -13464,7 +13793,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 +13951,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.2",
   "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",