contract-driven-delivery 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.

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.
 
@@ -769,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:
@@ -801,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/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";
   }
 });
@@ -12843,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))
@@ -13080,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();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contract-driven-delivery",
-  "version": "2.1.1",
+  "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",