contract-driven-delivery 2.1.1 → 2.1.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [2.1.3] - 2026-05-29
+
+Correct Claude Code MCP registration guidance.
+
+### Changed
+
+- Install and upgrade guidance now recommends
+  `claude mcp add --scope user cdd-kit -- cdd-kit mcp`, which writes the server
+  to `~/.claude.json`.
+- Documentation now warns that adding `mcpServers` to
+  `~/.claude/settings.json` alone is not sufficient for Claude Code CLI MCP
+  discovery.
+
+## [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,19 @@ 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: register the cdd-kit MCP server with Claude Code after init:
+
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
+```
+
+This writes the server to `~/.claude.json` and exposes graph/code-map tools
+directly to the agent (`cdd_graph_context`, `cdd_graph_query`,
+`cdd_graph_impact`, `cdd_index_query`, `cdd_index_impact`). Do not rely on
+manually adding `mcpServers` to `~/.claude/settings.json`; that file is a Claude
+Code UI settings format and is not the MCP registry read by the CLI.
+
 ---
 
 ### `cdd-kit update`
@@ -307,6 +320,11 @@ cdd-kit migrate --all    # add new per-change scaffolds such as implementation-p
 cdd-kit doctor --strict
 ```
 
+After syncing, register MCP-capable agents with
+`claude mcp add --scope user cdd-kit -- cdd-kit 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 +407,18 @@ 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`, register the MCP server:
+
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+```
+
+The MCP tools are the recommended graph/code-map exploration interface for AI
+agents. Claude Code CLI stores user-scope MCP servers in `~/.claude.json`; a
+manual `mcpServers` entry in `~/.claude/settings.json` is not sufficient.
+`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.
 
@@ -716,19 +746,17 @@ code-map-only fallback, `--engine codegraph` to require external CodeGraph, or
 ### `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.
+as tools instead of shelling out manually. Register it with Claude Code:
 
-```json
-{
-  "mcpServers": {
-    "cdd-kit": {
-      "command": "cdd-kit",
-      "args": ["mcp"]
-    }
-  }
-}
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
 ```
 
+Use the CLI command above so Claude Code writes the server to `~/.claude.json`.
+Do not rely on manually editing `~/.claude/settings.json`; that file is not the
+MCP registry read by the CLI.
+
 Exposed tools:
 
 - `cdd_graph_status`
@@ -769,6 +797,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 +832,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. Register MCP-capable agents with `claude mcp add --scope user cdd-kit -- cdd-kit 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,27 @@ 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:
+
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
+```
+
+For Claude Code, use `claude mcp add` so the server is written to
+`~/.claude.json`. Do not rely on manually adding `mcpServers` to
+`~/.claude/settings.json`; that is a Claude Code UI settings format and is not
+the MCP registry read by the CLI.
+
+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,27 @@ 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:
+
+```bash
+claude mcp add --scope user cdd-kit -- cdd-kit mcp
+claude mcp list
+```
+
+For Claude Code, use `claude mcp add` so the server is written to
+`~/.claude.json`. Do not rely on manually adding `mcpServers` to
+`~/.claude/settings.json`; that is a Claude Code UI settings format and is not
+the MCP registry read by the CLI.
+
+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,22 @@ 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("  Claude Code user-scope setup: claude mcp add --scope user cdd-kit -- cdd-kit mcp");
+  log.dim("  Verify in Claude Code: /mcp or `claude mcp list`");
+  log.dim("  Note: Claude Code CLI reads MCP servers from ~/.claude.json; ~/.claude/settings.json is not enough.");
+  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 +10299,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, register MCP with `claude mcp add --scope user cdd-kit -- cdd-kit mcp` so agents use graph/code-map tools directly.");
   }
   log.blank();
 }
@@ -10299,6 +10317,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 +12862,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 +13100,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.3",
   "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",