@hegemonart/get-design-done 1.58.0 → 1.59.1

package/reference/schemas/generated.d.ts

@@ -160,6 +160,108 @@ export interface DesignConfigJson {
 
 export type ConfigSchema = DesignConfigJson;
 
+// ---- design-context.schema.json ----
+/**
+ * The canonical typed knowledge graph of a design system, persisted at .design/context-graph.json. Nodes are design entities (tokens, components, screens, patterns); edges are typed relationships between them (uses-token, composes, transitions-to). Built by a two-phase mapper: a deterministic extract pass emits node/edge skeletons, then an LLM summary pass fills each node summary. Validated structurally by scripts/validate-design-context.cjs and queried by scripts/lib/design-context-query.cjs.
+ */
+export interface DesignContextGraph {
+  /**
+   * Schema version of this graph document (e.g. "52.0").
+   */
+  schema_version: string;
+  /**
+   * ISO-8601 timestamp the graph was last assembled (optional).
+   */
+  generated_at?: string;
+  /**
+   * All design entities in the graph. Node ids must be unique.
+   */
+  nodes: Node[];
+  /**
+   * All typed relationships. Every source/target must resolve to a node id.
+   */
+  edges: Edge[];
+  [k: string]: unknown;
+}
+export interface Node {
+  /**
+   * Stable unique identifier for the node (referenced by edge source/target).
+   */
+  id: string;
+  /**
+   * The kind of design entity this node represents.
+   */
+  type:
+    | 'token'
+    | 'component'
+    | 'variant'
+    | 'state'
+    | 'motion-fragment'
+    | 'a11y-pattern'
+    | 'screen'
+    | 'layer'
+    | 'pattern'
+    | 'anti-pattern';
+  /**
+   * Human-readable name of the entity.
+   */
+  name: string;
+  /**
+   * One-line LLM-authored description of what the entity is and does. A stub summary (empty or identical to name) is flagged by the validator as a soft warning.
+   */
+  summary: string;
+  /**
+   * Controlled-vocabulary tags grouping the node by concern (see reference/design-context-tag-vocab.md). Unknown tags are a soft warning, not a hard error.
+   */
+  tags?: string[];
+  /**
+   * Coarse complexity bucket for the entity.
+   */
+  complexity: 'simple' | 'moderate' | 'complex';
+  /**
+   * Optional finer classification. For token nodes one of color/spacing/typography/radius/shadow; for layer nodes one of Atomic/Molecular/Organism/Template. Free-form for other node types.
+   */
+  subtype?: string;
+  [k: string]: unknown;
+}
+export interface Edge {
+  /**
+   * Node id the edge originates from.
+   */
+  source: string;
+  /**
+   * Node id the edge points to.
+   */
+  target: string;
+  /**
+   * The kind of relationship between source and target.
+   */
+  type:
+    | 'uses-token'
+    | 'composes'
+    | 'extends'
+    | 'transitions-to'
+    | 'depends-on'
+    | 'mirrors'
+    | 'conflicts-with'
+    | 'referenced-by'
+    | 'tested-by'
+    | 'documented-by'
+    | 'consumes-context'
+    | 'provides-context';
+  /**
+   * Whether the relationship reads source-to-target (forward), target-to-source (backward), or both ways (bidirectional).
+   */
+  direction: 'forward' | 'backward' | 'bidirectional';
+  /**
+   * Relationship strength in the inclusive range 0..1.
+   */
+  weight: number;
+  [k: string]: unknown;
+}
+
+export type DesignContextSchema = DesignContextGraph;
+
 // ---- events.schema.json ----
 /**
  * One line of .design/telemetry/events.jsonl — the append-only telemetry stream produced by Plan 20-06. Each event is a single JSON object followed by a newline. See .planning/phases/20-gdd-sdk-foundation/20-06-PLAN.md.
@@ -168,7 +270,7 @@ export type Event = {
   [k: string]: unknown;
 } & {
   /**
-   * Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt.
+   * Free-form event type identifier. Pre-registered seeds: state.mutation, state.transition, stage.entered, stage.exited, hook.fired, error, capability_gap, kfm-candidate, router_pick, verify_outcome, rollout_started, rollout_advanced, rollout_stuck, budget_forecast, project_cap_warning, project_cap_halt, live_session_start, live_pick, live_generate, live_accept, live_discard, live_session_end, instinct_emitted, instinct_promoted, instinct_decayed, risk_assessment.
    */
   type: string;
   /**
@@ -266,6 +368,73 @@ export interface AgentInsightLine {
 
 export type InsightLineSchema = AgentInsightLine;
 
+// ---- instinct.schema.json ----
+/**
+ * An atomic, confidence-weighted design instinct learned across cycles. Validates the YAML frontmatter object of an instinct unit (see reference/instinct-format.md). Project-scoped units live at <root>/instincts/instincts.json; promoted global units live at ~/.claude/gdd/global-instincts.json. Persisted + queried by scripts/lib/instinct-store.cjs.
+ */
+export type InstinctUnit = {
+  [k: string]: unknown;
+} & {
+  /**
+   * Kebab-case stable identifier, e.g. "prefer-token-over-hex". Lowercase letters, digits, single hyphens.
+   */
+  id: string;
+  /**
+   * One sentence naming the situation that fires the instinct, e.g. "When a color literal appears in a component, reach for a design token first."
+   */
+  trigger: string;
+  /**
+   * Posterior trust in the instinct. Floor 0.3 (a fresh instinct is advisory, never directive); ceiling 0.9 (no instinct is ever certain). TTL decay multiplies this by 0.9 when the instinct goes unsurfaced.
+   */
+  confidence: number;
+  /**
+   * Lifecycle stage the instinct applies to, aligned to the Phase 50 lifecycle stages.
+   */
+  domain: 'intake' | 'explore' | 'decide' | 'build' | 'verify' | 'operate' | 'utility';
+  /**
+   * project = learned from one repository; global = promoted after the K/M gate across distinct projects.
+   */
+  scope: 'project' | 'global';
+  /**
+   * 8-char hex sha of the normalized git origin the instinct was first learned from. Required for project scope; optional for global (a promoted instinct is no longer tied to one origin).
+   */
+  project_id?: string;
+  /**
+   * Which producer minted the instinct: a reflection pass, the extract-learnings step, or a direct user assertion.
+   */
+  source: 'reflection' | 'extract-learnings' | 'user';
+  /**
+   * How many distinct design cycles have surfaced this instinct. Feeds the K=2 half of the promotion gate.
+   */
+  cycles_seen?: number;
+  /**
+   * Set of distinct project ids that have surfaced this instinct. Its length feeds the M=2 half of the promotion gate.
+   */
+  project_ids?: string[];
+  /**
+   * ISO date (YYYY-MM-DD) the instinct was first recorded.
+   */
+  first_seen?: string;
+  /**
+   * ISO date (YYYY-MM-DD) the instinct was last surfaced. Resets the TTL decay window.
+   */
+  last_seen?: string;
+  /**
+   * Beta posterior success weight. Seeded from the Beta(2,8) prior on promotion.
+   */
+  alpha?: number;
+  /**
+   * Beta posterior failure weight. Seeded from the Beta(2,8) prior on promotion.
+   */
+  beta?: number;
+  /**
+   * Tag recording which prior class seeded the posterior, e.g. "instinct".
+   */
+  prior_class?: string;
+};
+
+export type InstinctSchema = InstinctUnit;
+
 // ---- intel.schema.json ----
 /**
  * Shape of intel-store slice files per reference/intel-schema.md. Each slice has a generated timestamp and one array-valued payload key matching the slice name.
@@ -394,6 +563,57 @@ export interface IterationBudget {
 
 export type IterationBudgetSchema = IterationBudget;
 
+// ---- live-session.schema.json ----
+/**
+ * A single `/gdd:live` session record persisted at .design/live-sessions/<session-id>.json. Captures the pick -> generate -> accept/discard loop as an append-only event log so a session survives a crash or --resume. Written atomically by scripts/lib/live/session-store.cjs.
+ */
+export interface LiveSession {
+  /**
+   * Schema version of this session record (e.g. "47.0").
+   */
+  schema_version: string;
+  /**
+   * Stable id; also the basename of the on-disk file (no path separators).
+   */
+  session_id: string;
+  /**
+   * Lifecycle status. Only in_progress sessions are resumable.
+   */
+  status: 'in_progress' | 'completed' | 'abandoned';
+  /**
+   * ISO-8601 timestamp the session was created.
+   */
+  started_at: string;
+  /**
+   * ISO-8601 timestamp the session was closed; null while in_progress.
+   */
+  ended_at: string | null;
+  /**
+   * The page the element was picked from (optional).
+   */
+  url?: string;
+  /**
+   * Dev-server descriptor (url/port/command, or a plain string). Free-form by design.
+   */
+  dev_server?: string | {} | null;
+  /**
+   * Append-only log of session events, oldest first.
+   */
+  events: {
+    /**
+     * Event kind.
+     */
+    kind: 'pick' | 'generate' | 'accept' | 'discard';
+    /**
+     * ISO-8601 timestamp the event was recorded.
+     */
+    at: string;
+    [k: string]: unknown;
+  }[];
+}
+
+export type LiveSessionSchema = LiveSession;
+
 // ---- marketplace.schema.json ----
 /**
  * Shape of .claude-plugin/marketplace.json — the plugin marketplace descriptor.
@@ -448,7 +668,7 @@ export type McpBudgetSchema = MCPBudget;
 
 // ---- mcp-gdd-state-tools.schema.json ----
 /**
- * Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under scripts/mcp-servers/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.
+ * Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under sdk/mcp/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.
  */
 export interface McpGddStateTools {
   tools: {
@@ -482,11 +702,11 @@ export type McpGddStateToolsSchema = McpGddStateTools;
 
 // ---- mcp-gdd-tools.schema.json ----
 /**
- * Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under scripts/mcp-servers/gdd-mcp/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface (D-11).
+ * Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under sdk/mcp/gdd-mcp/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface (D-11).
  */
 export interface McpGddTools {
   /**
-   * Per-tool input/output schemas keyed by tool name. Exactly 12 entries (D-03 hard cap).
+   * Per-tool input/output schemas keyed by tool name. Exactly 13 entries (D-03 cap, raised 12 -> 13 in Phase 52 for gdd_context_query).
    */
   tools?: {
     gdd_status?: {
@@ -499,6 +719,22 @@ export interface McpGddTools {
         blocker_count: number;
       };
     };
+    gdd_context_query?: {
+      input: {
+        op: 'nodes' | 'edges' | 'path' | 'consumers-of' | 'unreachable' | 'cycles' | 'coverage';
+        type?: string;
+        tag?: string;
+        from?: string;
+        to?: string;
+        id?: string;
+      };
+      output: {
+        op: string;
+        graph_present: boolean;
+        path?: string;
+        result: unknown[] | {} | null;
+      };
+    };
     gdd_phase_current?: {
       input: {};
       output: {

package/reference/schemas/mcp-gdd-state-tools.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/reference/schemas/mcp-gdd-state-tools.schema.json",
   "title": "McpGddStateTools",
-  "description": "Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under scripts/mcp-servers/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.",
+  "description": "Combined manifest of all 11 gdd-state MCP tool input+output schemas (Plan 20-05). Individual tool schemas live under sdk/mcp/gdd-state/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface.",
   "type": "object",
   "additionalProperties": false,
   "required": ["tools"],

package/reference/schemas/mcp-gdd-tools.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/reference/schemas/mcp-gdd-tools.schema.json",
   "title": "McpGddTools",
-  "description": "Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under scripts/mcp-servers/gdd-mcp/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface (D-11).",
+  "description": "Combined manifest of all gdd-mcp tool input+output schemas (Plan 27.7-02). Individual tool schemas live under sdk/mcp/gdd-mcp/schemas/ and the tool handlers reference them; this combined schema exists so downstream validators and codegen can compile a single surface (D-11).",
   "type": "object",
   "properties": {
     "tools": {

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 94. Composition edges: 19 composes_with, 6 next_skills.
+Skills: 95. Composition edges: 19 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -65,6 +65,7 @@ flowchart TD
     n_add_backlog["add-backlog"]
     n_analyze_dependencies["analyze-dependencies"]
     n_apply_reflections["apply-reflections"]
+    n_bandit_reset["bandit-reset"]
     n_bandit_status["bandit-status"]
     n_budget["budget"]
     n_cache_manager["cache-manager"]

package/scripts/install.cjs

@@ -74,7 +74,7 @@ function helpText() {
     '  --dry-run       Print the diff without writing',
     '  --config-dir D  Override the config directory',
     '  --no-peer-prompt  Suppress the post-install peer-CLI detection nudge',
-    '  --register-mcp     Register gdd-mcp with detected harnesses (Claude Code, Codex). Opt-in.',
+    '  --register-mcp     Register gdd-mcp + gdd-state with detected harnesses (Claude Code, Codex). Opt-in.',
     '  --no-register-mcp  Skip MCP registration (default behavior; included for symmetry).',
     '  --doctor        Print Tier-2 distribution-channel status (read-only; no install)',
     '  --help, -h      Show this message',
@@ -287,6 +287,7 @@ async function main() {
   }
 
   // Phase 27.7 / Plan 27.7-04 — opt-in MCP registration (D-07).
+  // Phase 59.1 — registers BOTH gdd MCP servers (gdd-mcp + gdd-state).
   // Fires only on real install (not uninstall, not dry-run) when the user
   // passes --register-mcp explicitly. Default OFF; --no-register-mcp is a
   // no-op today (reserved for symmetry / when default flips). Idempotent
@@ -298,23 +299,29 @@ async function main() {
         try {
           const result = registerMcp({ harness });
           if (!result.detected) {
+            // CLI absent — single notice covers all servers for this harness.
             process.stderr.write('[install] ' + result.notice + '\n');
-          } else if (result.idempotent_skip) {
-            process.stdout.write(
-              '[install] gdd-mcp already registered with ' + harness + ' — skipping.\n',
-            );
-          } else if (result.applied) {
-            process.stdout.write(
-              '[install] gdd-mcp registered with ' + harness + '.\n',
-            );
-          } else {
-            process.stderr.write(
-              '[install] gdd-mcp registration with ' + harness + ' failed: exit ' + result.exit_code + '\n',
-            );
+            continue;
+          }
+          // Report each registered server individually.
+          for (const s of result.servers || []) {
+            if (s.idempotent_skip) {
+              process.stdout.write(
+                '[install] ' + s.server + ' already registered with ' + harness + ' — skipping.\n',
+              );
+            } else if (s.applied) {
+              process.stdout.write(
+                '[install] ' + s.server + ' registered with ' + harness + '.\n',
+              );
+            } else {
+              process.stderr.write(
+                '[install] ' + s.server + ' registration with ' + harness + ' failed: exit ' + s.exit_code + '\n',
+              );
+            }
           }
         } catch (err) {
           process.stderr.write(
-            '[install] gdd-mcp registration error (' + harness + '): ' + (err && err.message ? err.message : err) + '\n',
+            '[install] MCP registration error (' + harness + '): ' + (err && err.message ? err.message : err) + '\n',
           );
         }
       }

package/scripts/lib/install/mcp-register.cjs

@@ -1,10 +1,18 @@
 'use strict';
 // scripts/lib/install/mcp-register.cjs
 // ---------------------------------------------------------------------------
-// Plan 27.7-04 — registers `gdd-mcp` with the two harnesses that matter
-// (Claude Code, Codex) and detects existing registration. Idempotent;
+// Plan 27.7-04 — registers gdd's MCP servers with the two harnesses that
+// matter (Claude Code, Codex) and detects existing registration. Idempotent;
 // graceful absent-CLI fallback (D-07).
 //
+// Phase 59.1 — MCP parity: gdd ships TWO MCP servers, both registered here:
+//   - gdd-mcp   (read-only project tools; launch command `gdd-mcp`)
+//   - gdd-state (typed STATE mutators;   launch command `gdd-state-mcp`)
+// Each server is described in MCP_SERVERS as {name, launchCommand}. The
+// per-harness add-args are built per server so the registration name and the
+// launch command can differ (gdd-state registers under `gdd-state` but is
+// launched via the `gdd-state-mcp` bin).
+//
 // Pure library — no side effects on require. Invoked by:
 //   - scripts/install.cjs --register-mcp (opt-in; default off per D-07)
 //   - skills/health/SKILL.md check-mcp-registration step (read-only detect)
@@ -13,39 +21,75 @@
 // touching real CLIs in CI.
 //
 // Threat model: scripts/install.cjs --register-mcp writes to harness user-
-// level config. Command args are hardcoded in HARNESSES (no command-
-// injection surface); `--` separator before MCP_NAME prevents flag
-// injection (T-27.7-04-06).
+// level config. Command args are hardcoded in HARNESSES / MCP_SERVERS (no
+// command-injection surface); the `--` separator before the launch command
+// prevents flag injection (T-27.7-04-06).
 
 const { spawnSync } = require('node:child_process');
 
-const MCP_NAME = 'gdd-mcp';
+// The set of MCP servers gdd registers. `name` is the registration name (and
+// what appears in `<binary> mcp list`); `launchCommand` is the bin on PATH the
+// harness spawns. For gdd-mcp the two coincide; for gdd-state they differ.
+const MCP_SERVERS = Object.freeze([
+  Object.freeze({ name: 'gdd-mcp', launchCommand: 'gdd-mcp' }),
+  Object.freeze({ name: 'gdd-state', launchCommand: 'gdd-state-mcp' }),
+]);
+
+// Back-compat: the original single-server name. Retained for existing
+// importers (skills/health detection, type decls, tests).
+const MCP_NAME = MCP_SERVERS[0].name;
+
+// Build the `mcp add` argv for a given harness + server. Mirrors the original
+// per-harness shape exactly: claude pins user scope (`-s user`), codex does
+// not. The registration name precedes `--`; the launch command follows it.
+function claudeAddArgs(server) {
+  return ['mcp', 'add', server.name, '-s', 'user', '--', server.launchCommand];
+}
+function codexAddArgs(server) {
+  return ['mcp', 'add', server.name, '--', server.launchCommand];
+}
 
 const HARNESSES = Object.freeze({
   claude: Object.freeze({
     binary: 'claude',
-    addArgs: Object.freeze(['mcp', 'add', MCP_NAME, '-s', 'user', '--', MCP_NAME]),
+    addArgsFor: claudeAddArgs,
+    // Back-compat: addArgs for the primary (gdd-mcp) server.
+    addArgs: Object.freeze(claudeAddArgs(MCP_SERVERS[0])),
     listArgs: Object.freeze(['mcp', 'list']),
     listMatchPattern: /\bgdd-mcp\b/,
   }),
   codex: Object.freeze({
     binary: 'codex',
-    addArgs: Object.freeze(['mcp', 'add', MCP_NAME, '--', MCP_NAME]),
+    addArgsFor: codexAddArgs,
+    addArgs: Object.freeze(codexAddArgs(MCP_SERVERS[0])),
     listArgs: Object.freeze(['mcp', 'list']),
     listMatchPattern: /\bgdd-mcp\b/,
   }),
 });
 
+// Whether a server name appears in the harness's `mcp list` stdout. Built per
+// call so each server is matched on its own word-boundary-delimited name.
+function makeListMatchPattern(serverName) {
+  // Escape regex metacharacters in the server name (defensive; names are
+  // hardcoded today but this keeps the matcher injection-safe).
+  const escaped = serverName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp('(^|[^\\w-])' + escaped + '([^\\w-]|$)');
+}
+
 /**
- * Build the command tuple for a given harness + mode.
+ * Build the command tuple for a given harness + mode (+ optional server).
  * Currently only 'register' (add) is supported in command-build; 'detect'
  * uses listArgs internally, 'unregister' is reserved for future work.
+ *
+ * @param {'claude'|'codex'} harness
+ * @param {'register'|'detect'} [mode='register']
+ * @param {{name:string,launchCommand:string}} [server=MCP_SERVERS[0]]
  */
-function buildHarnessCommand(harness, mode = 'register') {
+function buildHarnessCommand(harness, mode = 'register', server = MCP_SERVERS[0]) {
   const h = HARNESSES[harness];
   if (!h) throw new Error('Unknown harness: ' + harness);
   if (mode === 'register') {
-    return { binary: h.binary, args: Array.from(h.addArgs) };
+    return { binary: h.binary, args: h.addArgsFor(server) };
   }
   if (mode === 'detect') {
     return { binary: h.binary, args: Array.from(h.listArgs) };
@@ -75,10 +119,16 @@ function detectHarnessPresent(harness, spawnFn = spawnSync) {
 }
 
 /**
- * Detect whether gdd-mcp is already registered with the given harness.
- * Runs `<binary> mcp list` and matches against listMatchPattern.
+ * Detect whether a given MCP server is already registered with the harness.
+ * Runs `<binary> mcp list` and matches against the server's name. When
+ * `serverName` is omitted, falls back to the harness's primary (gdd-mcp)
+ * pattern for back-compat with the original single-server signature.
+ *
+ * @param {'claude'|'codex'} harness
+ * @param {Function} [spawnFn]
+ * @param {string} [serverName]  server registration name to match
  */
-function isAlreadyRegistered(harness, spawnFn = spawnSync) {
+function isAlreadyRegistered(harness, spawnFn = spawnSync, serverName) {
   const h = HARNESSES[harness];
   if (!h) throw new Error('Unknown harness: ' + harness);
   let result;
@@ -92,45 +142,20 @@ function isAlreadyRegistered(harness, spawnFn = spawnSync) {
   }
   if (!result || result.status !== 0) return false;
   const stdout = (result.stdout || '').toString();
-  return h.listMatchPattern.test(stdout);
+  const pattern = serverName ? makeListMatchPattern(serverName) : h.listMatchPattern;
+  return pattern.test(stdout);
 }
 
 /**
- * Register gdd-mcp with the given harness.
- *
- * @param {object} opts
- * @param {'claude'|'codex'} opts.harness
- * @param {'register'|'unregister'|'detect'} [opts.mode='register']
- * @param {boolean} [opts.dryRun=false]
- * @param {Function} [opts.spawnFn]  child_process.spawnSync substitute
- * @returns {object} {harness, action, detected, command, applied,
- *                    idempotent_skip, notice?, stdout?, stderr?,
- *                    exit_code?, dry_run?}
+ * Register a single MCP server with the given harness. Assumes the harness CLI
+ * is already known to be present (caller does the PATH check once for all
+ * servers). Returns the same per-server shape the original registerMcp did.
  */
-function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spawnSync } = {}) {
-  if (!HARNESSES[harness]) {
-    throw new Error('Unknown harness: ' + harness + ' (expected one of: ' + Object.keys(HARNESSES).join(', ') + ')');
-  }
-  if (mode !== 'register' && mode !== 'detect' && mode !== 'unregister') {
-    throw new Error('Unsupported mode: ' + mode);
-  }
-
-  // Step 1 — detect harness CLI on PATH
-  if (!detectHarnessPresent(harness, spawnFn)) {
-    return {
-      harness,
-      action: mode,
-      detected: false,
-      command: null,
-      applied: false,
-      idempotent_skip: false,
-      notice: harness + ' CLI not on PATH — skipping ' + MCP_NAME + ' registration',
-    };
-  }
-
-  // Step 2 — idempotency check: already registered?
-  if (isAlreadyRegistered(harness, spawnFn)) {
+function registerOneServer(harness, server, { mode, dryRun, spawnFn }) {
+  // Idempotency check: this specific server already registered?
+  if (isAlreadyRegistered(harness, spawnFn, server.name)) {
     return {
+      server: server.name,
       harness,
       action: mode,
       detected: true,
@@ -140,12 +165,13 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
     };
   }
 
-  // Step 3 — build + dispatch add command
-  const { binary, args } = buildHarnessCommand(harness, 'register');
+  // Build + dispatch the per-server add command.
+  const { binary, args } = buildHarnessCommand(harness, 'register', server);
   const commandStr = binary + ' ' + args.join(' ');
 
   if (dryRun) {
     return {
+      server: server.name,
       harness,
       action: mode,
       detected: true,
@@ -161,6 +187,7 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
     result = spawnFn(binary, args, { stdio: 'pipe', encoding: 'utf8' });
   } catch (e) {
     return {
+      server: server.name,
       harness,
       action: mode,
       detected: true,
@@ -175,6 +202,7 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
   const stderr = (result && result.stderr) || '';
   const exit_code = result ? result.status : null;
   return {
+    server: server.name,
     harness,
     action: mode,
     detected: true,
@@ -187,6 +215,58 @@ function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spa
   };
 }
 
+/**
+ * Register all gdd MCP servers (MCP_SERVERS) with the given harness.
+ *
+ * The harness CLI presence is checked ONCE; if absent, no servers are
+ * registered. Otherwise each server in MCP_SERVERS is registered (idempotent
+ * per server). The return value keeps the original single-server fields at the
+ * top level (mirroring the primary gdd-mcp server) for back-compat, and adds a
+ * `servers` array carrying the per-server results.
+ *
+ * @param {object} opts
+ * @param {'claude'|'codex'} opts.harness
+ * @param {'register'|'unregister'|'detect'} [opts.mode='register']
+ * @param {boolean} [opts.dryRun=false]
+ * @param {Function} [opts.spawnFn]  child_process.spawnSync substitute
+ * @returns {object} {harness, action, detected, command, applied,
+ *                    idempotent_skip, notice?, stdout?, stderr?,
+ *                    exit_code?, dry_run?, servers}
+ */
+function registerMcp({ harness, mode = 'register', dryRun = false, spawnFn = spawnSync } = {}) {
+  if (!HARNESSES[harness]) {
+    throw new Error('Unknown harness: ' + harness + ' (expected one of: ' + Object.keys(HARNESSES).join(', ') + ')');
+  }
+  if (mode !== 'register' && mode !== 'detect' && mode !== 'unregister') {
+    throw new Error('Unsupported mode: ' + mode);
+  }
+
+  // Step 1 — detect harness CLI on PATH (once, for all servers).
+  if (!detectHarnessPresent(harness, spawnFn)) {
+    const names = MCP_SERVERS.map((s) => s.name).join(' + ');
+    return {
+      harness,
+      action: mode,
+      detected: false,
+      command: null,
+      applied: false,
+      idempotent_skip: false,
+      notice: harness + ' CLI not on PATH — skipping ' + names + ' registration',
+      servers: [],
+    };
+  }
+
+  // Step 2 — register each server (idempotent per server).
+  const servers = MCP_SERVERS.map((server) =>
+    registerOneServer(harness, server, { mode, dryRun, spawnFn }),
+  );
+
+  // Top-level fields mirror the primary (first) server for back-compat with
+  // the original single-server callers; `servers` carries the full detail.
+  const primary = servers[0];
+  return Object.assign({}, primary, { servers });
+}
+
 /**
  * Detect overall MCP registration state across all known harnesses.
  *
@@ -232,4 +312,5 @@ module.exports = {
   buildHarnessCommand,
   HARNESSES,
   MCP_NAME,
+  MCP_SERVERS,
 };