gsd-pi 2.67.0-dev.5399650 → 2.67.0-dev.fe39184

package/src/resources/extensions/claude-code-cli/tests/stream-adapter.test.ts

@@ -4,15 +4,15 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "nod
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import {
+	makeStreamExhaustedErrorMessage,
 	buildPromptFromContext,
-	buildFinalClaudeCodeContent,
 	buildSdkOptions,
+	extractToolResultsFromSdkUserMessage,
 	getClaudeLookupCommand,
-	makeStreamExhaustedErrorMessage,
 	parseClaudeLookupOutput,
-	sanitizeClaudeCodeStreamingEvent,
 } from "../stream-adapter.ts";
-import type { AssistantMessage, Context, Message } from "@gsd/pi-ai";
+import type { Context, Message } from "@gsd/pi-ai";
+import type { SDKUserMessage } from "../sdk-types.ts";
 
 // ---------------------------------------------------------------------------
 // Existing tests — exhausted stream fallback (#2575)
@@ -108,6 +108,65 @@ describe("stream-adapter — full context prompt (#2859)", () => {
 	});
 });
 
+describe("stream-adapter — Claude Code external tool results", () => {
+	test("extractToolResultsFromSdkUserMessage maps tool_result content to tool payloads", () => {
+		const message: SDKUserMessage = {
+			type: "user",
+			session_id: "sess-1",
+			parent_tool_use_id: "tool-bash-1",
+			message: {
+				role: "user",
+				content: [
+					{
+						type: "tool_result",
+						tool_use_id: "tool-bash-1",
+						content: "line 1\nline 2",
+						is_error: false,
+					},
+				],
+			},
+		};
+
+		const results = extractToolResultsFromSdkUserMessage(message);
+		assert.deepEqual(results, [
+			{
+				toolUseId: "tool-bash-1",
+				result: {
+					content: [{ type: "text", text: "line 1\nline 2" }],
+					details: {},
+					isError: false,
+				},
+			},
+		]);
+	});
+
+	test("extractToolResultsFromSdkUserMessage falls back to tool_use_result", () => {
+		const message: SDKUserMessage = {
+			type: "user",
+			session_id: "sess-1",
+			parent_tool_use_id: "tool-read-1",
+			message: { role: "user", content: [] },
+			tool_use_result: {
+				tool_use_id: "tool-read-1",
+				content: "file contents",
+				is_error: true,
+			},
+		};
+
+		const results = extractToolResultsFromSdkUserMessage(message);
+		assert.deepEqual(results, [
+			{
+				toolUseId: "tool-read-1",
+				result: {
+					content: [{ type: "text", text: "file contents" }],
+					details: {},
+					isError: true,
+				},
+			},
+		]);
+	});
+});
+
 describe("stream-adapter — session persistence (#2859)", () => {
 	test("buildSdkOptions enables persistSession by default", () => {
 		const options = buildSdkOptions("claude-sonnet-4-20250514", "test prompt");
@@ -149,18 +208,15 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			process.env.GSD_WORKFLOW_MCP_CWD = "/tmp/project";
 
 			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
-			assert.deepEqual(options.mcpServers, {
-				"gsd-workflow": {
-					command: "node",
-					args: ["packages/mcp-server/dist/cli.js"],
-					env: {
-						GSD_CLI_PATH: "/tmp/gsd",
-						GSD_PERSIST_WRITE_GATE_STATE: "1",
-						GSD_WORKFLOW_PROJECT_ROOT: "/tmp/project",
-					},
-					cwd: "/tmp/project",
-				},
-			});
+			const mcpServers = options.mcpServers as Record<string, any>;
+			assert.ok(mcpServers?.["gsd-workflow"], "expected gsd-workflow server config");
+			const srv = mcpServers["gsd-workflow"];
+			assert.equal(srv.command, "node");
+			assert.deepEqual(srv.args, ["packages/mcp-server/dist/cli.js"]);
+			assert.equal(srv.cwd, "/tmp/project");
+			assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd");
+			assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1");
+			assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
 			process.env.GSD_WORKFLOW_MCP_NAME = prev.GSD_WORKFLOW_MCP_NAME;
@@ -170,7 +226,7 @@ describe("stream-adapter — session persistence (#2859)", () => {
 		}
 	});
 
-	test("buildSdkOptions omits workflow MCP server config when env is unset", () => {
+	test("buildSdkOptions auto-discovers bundled MCP server even without env hints", () => {
 		const prev = {
 			GSD_WORKFLOW_MCP_COMMAND: process.env.GSD_WORKFLOW_MCP_COMMAND,
 			GSD_WORKFLOW_MCP_NAME: process.env.GSD_WORKFLOW_MCP_NAME,
@@ -190,7 +246,13 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			process.chdir(emptyDir);
 			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
 			process.chdir(originalCwd);
-			assert.equal((options as any).mcpServers, undefined);
+			// The bundled CLI may or may not be discoverable depending on
+			// whether the build output exists relative to import.meta.url.
+			// Either outcome is valid — the key invariant is no crash.
+			const mcpServers = (options as any).mcpServers;
+			if (mcpServers) {
+				assert.ok(mcpServers["gsd-workflow"], "if present, must be gsd-workflow");
+			}
 			rmSync(emptyDir, { recursive: true, force: true });
 		} finally {
 			process.env.GSD_WORKFLOW_MCP_COMMAND = prev.GSD_WORKFLOW_MCP_COMMAND;
@@ -227,18 +289,15 @@ describe("stream-adapter — session persistence (#2859)", () => {
 			const resolvedRepoDir = realpathSync(repoDir);
 
 			const options = buildSdkOptions("claude-sonnet-4-20250514", "test");
-			assert.deepEqual(options.mcpServers, {
-				"gsd-workflow": {
-					command: process.execPath,
-					args: [realpathSync(resolve(repoDir, "packages", "mcp-server", "dist", "cli.js"))],
-					env: {
-						GSD_CLI_PATH: "/tmp/gsd",
-						GSD_PERSIST_WRITE_GATE_STATE: "1",
-						GSD_WORKFLOW_PROJECT_ROOT: resolvedRepoDir,
-					},
-					cwd: resolvedRepoDir,
-				},
-			});
+			const mcpServers = options.mcpServers as Record<string, any>;
+			assert.ok(mcpServers?.["gsd-workflow"], "expected gsd-workflow server config");
+			const srv = mcpServers["gsd-workflow"];
+			assert.equal(srv.command, process.execPath);
+			assert.deepEqual(srv.args, [realpathSync(resolve(repoDir, "packages", "mcp-server", "dist", "cli.js"))]);
+			assert.equal(srv.cwd, resolvedRepoDir);
+			assert.equal(srv.env.GSD_CLI_PATH, "/tmp/gsd");
+			assert.equal(srv.env.GSD_PERSIST_WRITE_GATE_STATE, "1");
+			assert.equal(srv.env.GSD_WORKFLOW_PROJECT_ROOT, resolvedRepoDir);
 		} finally {
 			process.chdir(originalCwd);
 			rmSync(repoDir, { recursive: true, force: true });
@@ -252,92 +311,6 @@ describe("stream-adapter — session persistence (#2859)", () => {
 	});
 });
 
-describe("stream-adapter — final content filtering (#3861)", () => {
-	test("buildFinalClaudeCodeContent strips intermediate tool calls from the final assistant message", () => {
-		const finalContent = buildFinalClaudeCodeContent(
-			[
-				{ type: "toolCall", id: "tc_1", name: "Read", arguments: {} },
-				{ type: "thinking", thinking: "Planning next step" },
-				{ type: "text", text: "Done." },
-			] as any,
-			"",
-			"",
-		);
-
-		assert.deepEqual(finalContent, [
-			{ type: "thinking", thinking: "Planning next step" },
-			{ type: "text", text: "Done." },
-		]);
-	});
-
-	test("buildFinalClaudeCodeContent falls back to cached text when the final turn only had tool calls", () => {
-		const finalContent = buildFinalClaudeCodeContent(
-			[
-				{ type: "toolCall", id: "tc_2", name: "Edit", arguments: { file_path: "app.ts" } },
-			] as any,
-			"",
-			"User-facing answer",
-		);
-
-		assert.deepEqual(finalContent, [{ type: "text", text: "User-facing answer" }]);
-	});
-});
-
-describe("stream-adapter — streaming content filtering follow-up (#3867)", () => {
-	function makePartial(content: AssistantMessage["content"]): AssistantMessage {
-		return {
-			role: "assistant",
-			content,
-			api: "anthropic-messages",
-			provider: "claude-code",
-			model: "claude-sonnet-4-20250514",
-			usage: {
-				input: 0,
-				output: 0,
-				cacheRead: 0,
-				cacheWrite: 0,
-				totalTokens: 0,
-				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-			},
-			stopReason: "stop",
-			timestamp: Date.now(),
-		};
-	}
-
-	test("sanitizeClaudeCodeStreamingEvent strips tool calls from streamed partials and remaps contentIndex", () => {
-		const event = sanitizeClaudeCodeStreamingEvent({
-			type: "text_delta",
-			contentIndex: 2,
-			delta: "Done.",
-			partial: makePartial([
-				{ type: "toolCall", id: "tc_1", name: "ToolSearch", arguments: {} },
-				{ type: "thinking", thinking: "Planning next step" },
-				{ type: "text", text: "Done." },
-			] as any),
-		});
-
-		assert.ok(event, "text events should still be forwarded");
-		assert.equal(event!.type, "text_delta");
-		assert.equal((event! as any).contentIndex, 1);
-		assert.deepEqual((event! as any).partial.content, [
-			{ type: "thinking", thinking: "Planning next step" },
-			{ type: "text", text: "Done." },
-		]);
-	});
-
-	test("sanitizeClaudeCodeStreamingEvent suppresses internal tool streaming events entirely", () => {
-		const event = sanitizeClaudeCodeStreamingEvent({
-			type: "toolcall_start",
-			contentIndex: 0,
-			partial: makePartial([
-				{ type: "toolCall", id: "tc_1", name: "Bash", arguments: {} },
-			] as any),
-		});
-
-		assert.equal(event, null);
-	});
-});
-
 describe("stream-adapter — Windows Claude path lookup (#3770)", () => {
 	test("getClaudeLookupCommand uses where on Windows", () => {
 		assert.equal(getClaudeLookupCommand("win32"), "where claude");

package/src/resources/extensions/gsd/auto-start.ts

@@ -340,6 +340,21 @@ export async function bootstrapAutoSession(
       }
     }
 
+    if (ctx.model?.provider === "claude-code") {
+      try {
+        const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
+        const result = ensureProjectWorkflowMcpConfig(base);
+        if (result.status !== "unchanged") {
+          ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
+        }
+      } catch (err) {
+        ctx.ui.notify(
+          `Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`,
+          "warning",
+        );
+      }
+    }
+
     // Initialize GitServiceImpl
     s.gitService = new GitServiceImpl(
       s.basePath,
@@ -909,4 +924,3 @@ export async function bootstrapAutoSession(
     throw err;
   }
 }
-

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -70,7 +70,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "templates", desc: "List available workflow templates" },
   { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
   { cmd: "fast", desc: "Toggle OpenAI service tier (on/off/flex/status)" },
-  { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
+  { cmd: "mcp", desc: "MCP server status, connectivity, and local config bootstrap (status, check, init)" },
   { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
   { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
   { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
@@ -201,6 +201,7 @@ const NESTED_COMPLETIONS: CompletionMap = {
   mcp: [
     { cmd: "status", desc: "Show all MCP server statuses (default)" },
     { cmd: "check", desc: "Detailed status for a specific server" },
+    { cmd: "init", desc: "Write .mcp.json for the local GSD workflow MCP server" },
   ],
   doctor: [
     { cmd: "fix", desc: "Auto-fix detected issues" },

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -60,7 +60,7 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd hooks          Show post-unit hook configuration",
     "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
     "  /gsd fast           Toggle OpenAI service tier  [on|off|flex|status]",
-    "  /gsd mcp            MCP server status and connectivity  [status|check <server>]",
+    "  /gsd mcp            MCP server status and connectivity  [status|check <server>|init [dir]]",
     "",
     "MAINTENANCE",
     "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",

package/src/resources/extensions/gsd/commands-mcp-status.ts

@@ -7,12 +7,15 @@
  *   /gsd mcp             — Overview of all servers (alias: /gsd mcp status)
  *   /gsd mcp status      — Same as bare /gsd mcp
  *   /gsd mcp check <srv> — Detailed status for a specific server
+ *   /gsd mcp init [dir]  — Write project-local GSD workflow MCP config
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+
+import { ensureProjectWorkflowMcpConfig } from "./mcp-project-config.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -28,6 +31,28 @@ export interface McpServerDetail extends McpServerStatus {
   tools: string[];
 }
 
+export function formatMcpInitResult(
+  status: "created" | "updated" | "unchanged",
+  configPath: string,
+  targetPath: string,
+): string {
+  const summary =
+    status === "created"
+      ? "Created project MCP config."
+      : status === "updated"
+        ? "Updated project MCP config."
+        : "Project MCP config is already up to date.";
+
+  return [
+    summary,
+    "",
+    `Project: ${targetPath}`,
+    `Config:   ${configPath}`,
+    "",
+    "Claude Code can now load the GSD workflow MCP server from this folder.",
+  ].join("\n");
+}
+
 // ─── Config reader (standalone — does not import mcp-client internals) ──────
 
 interface McpServerRawConfig {
@@ -94,6 +119,7 @@ export function formatMcpStatusReport(servers: McpServerStatus[]): string {
       "No MCP servers configured.",
       "",
       "Add servers to .mcp.json or .gsd/mcp.json to enable MCP integrations.",
+      "Tip: run /gsd mcp init . to write the local GSD workflow MCP config.",
       "See: https://modelcontextprotocol.io/quickstart",
     ].join("\n");
   }
@@ -153,12 +179,31 @@ export async function handleMcpStatus(
   args: string,
   ctx: ExtensionCommandContext,
 ): Promise<void> {
-  const trimmed = args.trim().toLowerCase();
+  const trimmed = args.trim();
+  const lowered = trimmed.toLowerCase();
   const configs = readMcpConfigs();
 
+  // /gsd mcp init [dir]
+  if (!lowered || lowered === "status") {
+    // handled below
+  } else if (lowered === "init" || lowered.startsWith("init ")) {
+    const rawPath = trimmed.slice("init".length).trim();
+    const targetPath = resolve(rawPath || ".");
+    try {
+      const result = ensureProjectWorkflowMcpConfig(targetPath);
+      ctx.ui.notify(formatMcpInitResult(result.status, result.configPath, targetPath), "info");
+    } catch (err) {
+      ctx.ui.notify(
+        `Failed to prepare MCP config for ${targetPath}: ${err instanceof Error ? err.message : String(err)}`,
+        "error",
+      );
+    }
+    return;
+  }
+
   // /gsd mcp check <server>
-  if (trimmed.startsWith("check ")) {
-    const serverName = args.trim().slice("check ".length).trim();
+  if (lowered.startsWith("check ")) {
+    const serverName = trimmed.slice("check ".length).trim();
     const config = configs.find((c) => c.name === serverName);
     if (!config) {
       const available = configs.map((c) => c.name).join(", ") || "(none)";
@@ -202,7 +247,7 @@ export async function handleMcpStatus(
   }
 
   // /gsd mcp or /gsd mcp status
-  if (!trimmed || trimmed === "status") {
+  if (!lowered || lowered === "status") {
     // Build status for each server
     const statuses: McpServerStatus[] = [];
 
@@ -239,9 +284,10 @@ export async function handleMcpStatus(
 
   // Unknown subcommand
   ctx.ui.notify(
-    "Usage: /gsd mcp [status|check <server>]\n\n" +
+    "Usage: /gsd mcp [status|check <server>|init [dir]]\n\n" +
     "  status           Show all MCP server statuses (default)\n" +
-    "  check <server>   Detailed status for a specific server",
+    "  check <server>   Detailed status for a specific server\n" +
+    "  init [dir]       Write .mcp.json for the local GSD workflow MCP server",
     "warning",
   );
 }

package/src/resources/extensions/gsd/doctor-git-checks.ts

@@ -10,7 +10,7 @@ import { deriveState, isMilestoneComplete } from "./state.js";
 import { listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { getAllWorktreeHealth } from "./worktree-health.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 
@@ -386,19 +386,19 @@ export async function checkGitHealth(
             code: "stale_uncommitted_changes",
             scope: "project",
             unitId: "project",
-            message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting uncommitted changes.`,
+            message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting tracked files.`,
             fixable: true,
           });
 
           if (shouldFix("stale_uncommitted_changes")) {
             try {
-              nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
+              nativeAddTracked(basePath);
               const commitMsg = `gsd snapshot: uncommitted changes after ${mins}m inactivity`;
               const result = nativeCommit(basePath, commitMsg);
               if (result) {
                 fixesApplied.push(`created gsd snapshot after ${mins}m of uncommitted changes`);
               } else {
-                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging changes");
+                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging tracked files");
               }
             } catch {
               fixesApplied.push("failed to create gsd snapshot commit");

package/src/resources/extensions/gsd/doctor-proactive.ts

@@ -21,8 +21,8 @@ import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.j
 import { abortAndReset } from "./git-self-heal.js";
 import { rebuildState } from "./doctor.js";
 import { deriveState } from "./state.js";
-import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
+import { resolveMilestoneIntegrationBranch } from "./git-service.js";
+import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 
@@ -312,7 +312,7 @@ export async function preDispatchHealthGate(basePath: string): Promise<PreDispat
         if (minutesSinceCommit >= thresholdMinutes) {
           const mins = Math.floor(minutesSinceCommit);
           try {
-            nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
+            nativeAddTracked(basePath);
             const commitMsg = `gsd snapshot: pre-dispatch, uncommitted changes after ${mins}m inactivity`;
             const result = nativeCommit(basePath, commitMsg);
             if (result) {

package/src/resources/extensions/gsd/init-wizard.ts

@@ -238,15 +238,11 @@ export async function showProjectInit(
   // Initialize SQLite database so GSD starts in full-capability mode (#3880).
   // Without this, isDbAvailable() returns false and GSD enters degraded
   // markdown-only mode until a tool handler happens to call ensureDbOpen().
-  let dbReady = false;
   try {
     const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
-    dbReady = await ensureDbOpen(basePath);
+    await ensureDbOpen(basePath);
   } catch {
-    // Swallowed — warning surfaced below
-  }
-  if (!dbReady) {
-    ctx.ui.notify("Warning: database initialization failed — GSD will run in degraded mode until the next /gsd invocation.", "warning");
+    // Non-fatal — DB creation failure should not block project init
   }
 
   // Ensure .gitignore
@@ -267,7 +263,6 @@ export async function showProjectInit(
   // Write initial STATE.md so it exists before the first /gsd invocation.
   // The explicit /gsd init path (ops.ts) returns without entering showSmartEntry(),
   // which would otherwise generate STATE.md at guided-flow.ts:1358.
-  let stateReady = false;
   try {
     const { deriveState } = await import("./state.js");
     const { buildStateMarkdown } = await import("./doctor.js");
@@ -275,12 +270,23 @@ export async function showProjectInit(
     const { resolveGsdRootFile } = await import("./paths.js");
     const state = await deriveState(basePath);
     await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state));
-    stateReady = true;
   } catch {
-    // Swallowed — warning surfaced below
+    // Non-fatal — STATE.md will be regenerated on next /gsd invocation
   }
-  if (!stateReady) {
-    ctx.ui.notify("Warning: initial STATE.md generation failed — it will be created on the next /gsd invocation.", "warning");
+
+  if (ctx.model?.provider === "claude-code") {
+    try {
+      const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
+      const result = ensureProjectWorkflowMcpConfig(basePath);
+      if (result.status !== "unchanged") {
+        ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
+      }
+    } catch (err) {
+      ctx.ui.notify(
+        `Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+    }
   }
 
   ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");

package/src/resources/extensions/gsd/mcp-project-config.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assertSafeDirectory } from "./validate-directory.js";
+import { detectWorkflowMcpLaunchConfig } from "./workflow-mcp.js";
+
+export const GSD_WORKFLOW_MCP_SERVER_NAME = "gsd-workflow";
+
+export interface ProjectMcpServerConfig {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  url?: string;
+}
+
+export interface EnsureProjectWorkflowMcpConfigResult {
+  configPath: string;
+  serverName: string;
+  status: "created" | "updated" | "unchanged";
+}
+
+interface McpConfigFile {
+  mcpServers?: Record<string, ProjectMcpServerConfig>;
+  servers?: Record<string, ProjectMcpServerConfig>;
+  [key: string]: unknown;
+}
+
+export function resolveBundledGsdCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const explicit = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+  if (explicit) return explicit;
+
+  const candidates = [
+    resolve(fileURLToPath(new URL("../../../../scripts/dev-cli.js", import.meta.url))),
+    resolve(fileURLToPath(new URL("../../../../dist/loader.js", import.meta.url))),
+    resolve(fileURLToPath(new URL("../../../loader.js", import.meta.url))),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+export function buildProjectWorkflowMcpServerConfig(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ProjectMcpServerConfig {
+  const resolvedProjectRoot = resolve(projectRoot);
+  const gsdCliPath = resolveBundledGsdCliPath(env);
+  const launch = detectWorkflowMcpLaunchConfig(resolvedProjectRoot, {
+    ...env,
+    ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath, GSD_BIN_PATH: gsdCliPath } : {}),
+  });
+
+  if (!launch) {
+    throw new Error(
+      "Unable to resolve the GSD workflow MCP server. Build this checkout or install gsd-mcp-server on PATH.",
+    );
+  }
+
+  return {
+    command: launch.command,
+    ...(launch.args && launch.args.length > 0 ? { args: launch.args } : {}),
+    ...(launch.cwd ? { cwd: launch.cwd } : {}),
+    ...(launch.env ? { env: launch.env } : {}),
+  };
+}
+
+function readExistingConfig(configPath: string): McpConfigFile {
+  if (!existsSync(configPath)) return {};
+
+  const raw = readFileSync(configPath, "utf-8");
+  try {
+    const parsed = JSON.parse(raw) as McpConfigFile;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (err) {
+    throw new Error(
+      `Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export function ensureProjectWorkflowMcpConfig(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): EnsureProjectWorkflowMcpConfigResult {
+  const resolvedProjectRoot = resolve(projectRoot);
+  assertSafeDirectory(resolvedProjectRoot);
+
+  const configPath = resolve(resolvedProjectRoot, ".mcp.json");
+  const existing = readExistingConfig(configPath);
+  const desiredServer = buildProjectWorkflowMcpServerConfig(resolvedProjectRoot, env);
+  const previousServers = existing.mcpServers ?? {};
+  const nextServers = {
+    ...previousServers,
+    [GSD_WORKFLOW_MCP_SERVER_NAME]: desiredServer,
+  };
+
+  const alreadyPresent = existsSync(configPath);
+  const unchanged =
+    JSON.stringify(previousServers[GSD_WORKFLOW_MCP_SERVER_NAME] ?? null)
+      === JSON.stringify(desiredServer)
+    && existing.mcpServers !== undefined;
+
+  if (unchanged) {
+    return {
+      configPath,
+      serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+      status: "unchanged",
+    };
+  }
+
+  const nextConfig: McpConfigFile = {
+    ...existing,
+    mcpServers: nextServers,
+  };
+
+  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8");
+
+  return {
+    configPath,
+    serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+    status: alreadyPresent ? "updated" : "created",
+  };
+}