@launchchair/agent 0.4.0

package/mcp-bridge-server.mjs

@@ -0,0 +1,1101 @@
+#!/usr/bin/env node
+
+/**
+ * LaunchChair MCP bridge (stdio).
+ *
+ * Implements minimal MCP tools over stdio so desktop clients can:
+ * - heartbeat connection
+ * - claim queued runs
+ * - complete runs
+ * - run a queued prompt end-to-end
+ * - continue a project loop until human input, completion, or max steps
+ */
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
+
+const VERSION = "0.4.0";
+const SERVER_NAME = "launchchair-agent-mcp";
+const AGENT_SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const BASE_SERVER_INSTRUCTIONS =
+  "Use LaunchChair MCP tools—not web browsing—for LaunchChair project discovery, creation, planning, and loops. Call the most specific available tool. If a requested workflow is unavailable, explain the access or setup issue instead of silently substituting another project type or workflow.";
+
+function nodeScriptCommand(scriptName) {
+  return `${JSON.stringify(process.execPath)} ${JSON.stringify(path.join(AGENT_SCRIPT_DIR, scriptName))}`;
+}
+
+function env(name, fallback = "") {
+  const value = process.env[name];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function toInt(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function trimToBytes(input, maxBytes) {
+  const text = String(input ?? "");
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+  const prefix = text.slice(0, Math.floor(text.length * 0.45));
+  const suffix = text.slice(Math.floor(text.length * 0.85));
+  const marker = "\n\n...[truncated by mcp bridge]...\n\n";
+  let result = `${prefix}${marker}${suffix}`;
+  while (Buffer.byteLength(result, "utf8") > maxBytes && result.length > 64) {
+    result = result.slice(0, Math.floor(result.length * 0.9));
+  }
+  return result;
+}
+
+function normalizeTarget(value, fallback = "other") {
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "_");
+  if (["chatgpt", "claude", "codex", "claude_code", "other"].includes(normalized)) return normalized;
+  return fallback;
+}
+
+function hasOpenAiKey() {
+  return String(process.env.OPENAI_API_KEY ?? "").trim().length > 0;
+}
+
+function hasAnthropicKey() {
+  return String(process.env.ANTHROPIC_API_KEY ?? "").trim().length > 0;
+}
+
+function builtInRunnerCommand(target) {
+  if (target === "codex") {
+    return nodeScriptCommand("codex-runner.mjs");
+  }
+  if (target === "claude_code") {
+    return nodeScriptCommand("claude-code-runner.mjs");
+  }
+  if (target === "chatgpt" && hasOpenAiKey()) {
+    return nodeScriptCommand("chatgpt-runner.mjs");
+  }
+  if (target === "claude" && hasAnthropicKey()) {
+    return nodeScriptCommand("claude-runner.mjs");
+  }
+  return "";
+}
+
+const config = {
+  baseUrl: env("LAUNCHCHAIR_BASE_URL", "http://localhost:3000").replace(/\/+$/, ""),
+  token: env("LAUNCHCHAIR_AGENT_TOKEN", env("LAUNCHCHAIR_API_KEY")),
+  projectId: env("LAUNCHCHAIR_PROJECT_ID") || null,
+  clientName: env("LC_AGENT_CLIENT_NAME", "MCP Bridge"),
+  clientType: env("LC_AGENT_CLIENT_TYPE", "other"),
+  clientVersion: env("LC_AGENT_CLIENT_VERSION", VERSION),
+  maxPayloadBytes: toInt(process.env.LC_AGENT_MAX_PAYLOAD_BYTES, 850 * 1024),
+  mockResponse: process.env.AGENT_MOCK_RESPONSE ?? "",
+  modeTargets: {
+    gpt: normalizeTarget(env("LC_AGENT_ROUTER_GPT_TARGET", "codex"), "codex"),
+    codex: normalizeTarget(env("LC_AGENT_ROUTER_CODEX_TARGET", "codex"), "codex"),
+  },
+  runnerCommands: {
+    generic: env("LC_AGENT_RUNNER_CMD"),
+    gpt: env("LC_AGENT_RUNNER_CMD_GPT"),
+    codex: env("LC_AGENT_RUNNER_CMD_CODEX"),
+    chatgpt: env("LC_AGENT_RUNNER_CMD_CHATGPT", builtInRunnerCommand("chatgpt")),
+    claude: env("LC_AGENT_RUNNER_CMD_CLAUDE", builtInRunnerCommand("claude")),
+    codexTarget: env("LC_AGENT_RUNNER_CMD_CODEX", builtInRunnerCommand("codex")),
+    claudeCode: env("LC_AGENT_RUNNER_CMD_CLAUDE_CODE", builtInRunnerCommand("claude_code")),
+  },
+  localRepoPaths: {
+    codex: env("LC_AGENT_CODEX_CWD", process.cwd()),
+    claudeCode: env("LC_AGENT_CLAUDE_CODE_CWD", process.cwd()),
+  },
+};
+
+if (!config.token) {
+  // eslint-disable-next-line no-console
+  console.error("Missing LAUNCHCHAIR_AGENT_TOKEN for MCP bridge. LAUNCHCHAIR_API_KEY is also supported as an alias.");
+  process.exit(1);
+}
+
+if (
+  !config.mockResponse &&
+  !config.runnerCommands.generic &&
+  !config.runnerCommands.gpt &&
+  !config.runnerCommands.codex &&
+  !config.runnerCommands.chatgpt &&
+  !config.runnerCommands.claude &&
+  !config.runnerCommands.codexTarget &&
+  !config.runnerCommands.claudeCode
+) {
+  // eslint-disable-next-line no-console
+  console.error(
+    "No runner command configured for MCP bridge. Set LC_AGENT_RUNNER_CMD* or use the built-in Codex/Claude Code runners; ChatGPT/Claude API fallbacks require provider API keys.",
+  );
+  process.exit(1);
+}
+
+async function api(path, { method = "GET", body } = {}) {
+  const response = await fetch(`${config.baseUrl}${path}`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+      "Content-Type": "application/json",
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch (_error) {
+    payload = null;
+  }
+
+  if (!response.ok) {
+    const err = new Error(`HTTP ${response.status}: ${String(payload?.error ?? response.statusText ?? "Request failed")}`);
+    err.status = response.status;
+    err.payload = payload;
+    err.retryAfterSeconds = Number.parseInt(response.headers.get("retry-after") ?? "", 10) || null;
+    throw err;
+  }
+  return payload;
+}
+
+let statusPromise = null;
+
+function loadStatus() {
+  if (!statusPromise) {
+    statusPromise = api("/api/agent/v1").catch(() => null);
+  }
+  return statusPromise;
+}
+
+function serverInstructions(status) {
+  const featureInstructions = String(status?.capabilities?.mcpServerInstructions ?? "").trim();
+  return featureInstructions ? `${BASE_SERVER_INSTRUCTIONS} ${featureInstructions}` : BASE_SERVER_INSTRUCTIONS;
+}
+
+function targetForRun(run) {
+  const mode = String(run?.promptMode ?? "").trim().toLowerCase();
+  if (mode === "gpt") return config.modeTargets.gpt;
+  if (mode === "codex") return config.modeTargets.codex;
+  return "other";
+}
+
+function commandForRun(run) {
+  const mode = String(run?.promptMode ?? "").trim().toLowerCase();
+  const target = targetForRun(run);
+  if (mode === "gpt") {
+    if (target === "codex" && config.runnerCommands.codexTarget) return config.runnerCommands.codexTarget;
+    if (target === "claude_code" && config.runnerCommands.claudeCode) return config.runnerCommands.claudeCode;
+    if (target === "chatgpt" && config.runnerCommands.chatgpt) return config.runnerCommands.chatgpt;
+    if (target === "claude" && config.runnerCommands.claude) return config.runnerCommands.claude;
+    if (config.runnerCommands.gpt) return config.runnerCommands.gpt;
+    return config.runnerCommands.generic;
+  }
+  if (mode === "codex") {
+    if (target === "codex" && config.runnerCommands.codexTarget) return config.runnerCommands.codexTarget;
+    if (target === "claude_code" && config.runnerCommands.claudeCode) return config.runnerCommands.claudeCode;
+    if (config.runnerCommands.codex) return config.runnerCommands.codex;
+    return config.runnerCommands.generic;
+  }
+  return config.runnerCommands.generic;
+}
+
+async function executeRunner(run) {
+  if (config.mockResponse) {
+    return {
+      stdout: config.mockResponse,
+      stderr: "",
+      exitCode: 0,
+      durationMs: 0,
+    };
+  }
+
+  const template = commandForRun(run);
+  if (!template) {
+    throw new Error(
+      `No runner command configured for promptMode=${String(run?.promptMode ?? "unknown")} target=${targetForRun(run)}.`,
+    );
+  }
+  const command = buildRunnerCommand(template, run);
+  const parsedCommand = parseRunnerCommand(command);
+  const startedAt = Date.now();
+  return new Promise((resolve, reject) => {
+    const child = spawn(parsedCommand.file, parsedCommand.args, {
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        LC_AGENT_RUN_ID: String(run.id ?? ""),
+        LC_AGENT_PROJECT_ID: String(run.projectId ?? ""),
+        LC_AGENT_PHASE_KEY: String(run.phaseKey ?? ""),
+        LC_AGENT_BUCKET_KEY: String(run.bucketKey ?? ""),
+        LC_AGENT_CARD_ID: String(run.cardId ?? ""),
+        LC_AGENT_PROMPT_MODE: String(run.promptMode ?? ""),
+        LC_AGENT_RUN_TYPE: String(run.runType ?? ""),
+      },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => reject(error));
+    child.on("close", (code) => {
+      const durationMs = Date.now() - startedAt;
+      if ((code ?? 1) !== 0) {
+        const error = new Error(`Runner exited with code ${String(code ?? 1)}${stderr ? `: ${stderr.trim()}` : ""}`);
+        error.code = code ?? 1;
+        error.stdout = stdout;
+        error.stderr = stderr;
+        error.durationMs = durationMs;
+        reject(error);
+        return;
+      }
+      resolve({
+        stdout,
+        stderr,
+        exitCode: code ?? 0,
+        durationMs,
+      });
+    });
+    child.stdin.write(String(run.prompt ?? ""));
+    child.stdin.end();
+  });
+}
+
+async function heartbeat(args = {}) {
+  const projectId = await resolveProjectId(args, false);
+  return api("/api/agent/v1/heartbeat", {
+    method: "POST",
+    body: {
+      projectId,
+      clientName: String(args.clientName ?? "").trim() || config.clientName,
+      clientType: normalizeTarget(args.clientType ?? config.clientType, "other"),
+      clientVersion: String(args.clientVersion ?? "").trim() || config.clientVersion,
+      lastAction: String(args.lastAction ?? "").trim() || "heartbeat",
+      lastActionAt: new Date().toISOString(),
+    },
+  });
+}
+
+async function claimNextRun(args = {}) {
+  const projectId = await resolveProjectId(args, false);
+  const payload = await api("/api/agent/v1/runs/next", {
+    method: "POST",
+    body: {
+      projectId,
+      clientName: String(args.clientName ?? "").trim() || config.clientName,
+      clientType: normalizeTarget(args.clientType ?? config.clientType, "other"),
+      clientVersion: String(args.clientVersion ?? "").trim() || config.clientVersion,
+    },
+  });
+  return payload.run ?? null;
+}
+
+async function completeRun(args = {}) {
+  const runId = String(args.runId ?? "").trim();
+  if (!runId) {
+    throw new Error("runId is required.");
+  }
+  return api(`/api/agent/v1/runs/${encodeURIComponent(runId)}/complete`, {
+    method: "POST",
+    body: {
+      status: String(args.status ?? "").trim().toLowerCase() === "failed" ? "failed" : "completed",
+      resultRaw: trimToBytes(String(args.resultRaw ?? ""), config.maxPayloadBytes),
+      resultJsonPayload: trimToBytes(String(args.resultJsonPayload ?? ""), config.maxPayloadBytes),
+      resultMeta: typeof args.resultMeta === "object" && args.resultMeta && !Array.isArray(args.resultMeta) ? args.resultMeta : {},
+      error: String(args.error ?? "").trim() || null,
+      clientName: String(args.clientName ?? "").trim() || config.clientName,
+      clientType: normalizeTarget(args.clientType ?? config.clientType, "other"),
+      clientVersion: String(args.clientVersion ?? "").trim() || config.clientVersion,
+    },
+  });
+}
+
+async function runOnce(args = {}) {
+  const run = await claimNextRun(args);
+  if (!run) {
+    return { run: null, completed: null };
+  }
+  try {
+    const execution = await executeRunner(run);
+    const stdout = String(execution.stdout ?? "").trim();
+    const stderr = String(execution.stderr ?? "").trim();
+    const output = stdout || stderr;
+    const completion = await api(`/api/agent/v1/runs/${encodeURIComponent(String(run.id))}/complete`, {
+      method: "POST",
+      body: {
+        status: "completed",
+        resultRaw: trimToBytes(output, config.maxPayloadBytes),
+        resultJsonPayload: trimToBytes(output, config.maxPayloadBytes),
+        resultMeta: {
+          exitCode: execution.exitCode ?? 0,
+          durationMs: execution.durationMs ?? 0,
+          target: targetForRun(run),
+          autoApplyRequested: run.autoApply === true,
+          runIntent: run.runIntent ?? "initial",
+          attemptNumber: run.attemptNumber ?? 1,
+          maxAttempts: run.maxAttempts ?? 1,
+        },
+        error: null,
+        clientName: String(args.clientName ?? "").trim() || config.clientName,
+        clientType: normalizeTarget(args.clientType ?? config.clientType, "other"),
+        clientVersion: String(args.clientVersion ?? "").trim() || config.clientVersion,
+      },
+    });
+    return { run, completed: completion?.run ?? null };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error ?? "Runner failed");
+    const stdout = typeof error?.stdout === "string" ? error.stdout : "";
+    const stderr = typeof error?.stderr === "string" ? error.stderr : "";
+    const completion = await api(`/api/agent/v1/runs/${encodeURIComponent(String(run.id))}/complete`, {
+      method: "POST",
+      body: {
+        status: "failed",
+        resultRaw: trimToBytes(`${stdout}\n${stderr}`.trim() || message, config.maxPayloadBytes),
+        resultJsonPayload: "",
+        resultMeta: {
+          exitCode: typeof error?.code === "number" ? error.code : null,
+          durationMs: typeof error?.durationMs === "number" ? error.durationMs : null,
+          target: targetForRun(run),
+        },
+        error: message,
+        clientName: String(args.clientName ?? "").trim() || config.clientName,
+        clientType: normalizeTarget(args.clientType ?? config.clientType, "other"),
+        clientVersion: String(args.clientVersion ?? "").trim() || config.clientVersion,
+      },
+    });
+    return { run, completed: completion?.run ?? null, error: message };
+  }
+}
+
+async function listProjects(args = {}) {
+  const params = new URLSearchParams();
+  const query = String(args.query ?? args.projectName ?? "").trim();
+  const limit = Number.parseInt(String(args.limit ?? ""), 10);
+  if (query) {
+    params.set("query", query);
+  }
+  if (Number.isFinite(limit) && limit > 0) {
+    params.set("limit", String(Math.min(limit, 50)));
+  }
+  const suffix = params.toString();
+  return api(`/api/agent/v1/projects${suffix ? `?${suffix}` : ""}`);
+}
+
+function normalizeProjectName(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+async function resolveProjectId(args = {}, required = true) {
+  const explicitProjectId = String(args.projectId ?? "").trim() || config.projectId || "";
+  if (explicitProjectId) {
+    return explicitProjectId;
+  }
+
+  const projectName = String(args.projectName ?? args.query ?? "").trim();
+  if (!projectName) {
+    if (!required) {
+      return null;
+    }
+    throw new Error("projectId is required. Pass projectId, set LAUNCHCHAIR_PROJECT_ID, or pass projectName.");
+  }
+
+  const listed = await listProjects({ query: projectName, limit: 10 });
+  const projects = Array.isArray(listed?.projects) ? listed.projects : [];
+  const normalizedName = normalizeProjectName(projectName);
+  const exactMatch = projects.find((project) => normalizeProjectName(project?.name) === normalizedName);
+  const selected = exactMatch ?? (projects.length === 1 ? projects[0] : null);
+  const resolvedProjectId = String(selected?.id ?? "").trim();
+  if (resolvedProjectId) {
+    config.projectId = resolvedProjectId;
+    return resolvedProjectId;
+  }
+
+  const names = projects.map((project) => `${String(project?.name ?? "Untitled")} (${String(project?.id ?? "unknown")})`);
+  throw new Error(
+    names.length > 0
+      ? `Could not resolve a unique LaunchChair project for "${projectName}". Matching projects: ${names.join(", ")}. Pass projectId.`
+      : `Could not find a LaunchChair project named "${projectName}" for this token.`,
+  );
+}
+
+function normalizeChoiceSelections(args = {}) {
+  if (Array.isArray(args.choiceSelections)) {
+    return args.choiceSelections.filter((item) => item && typeof item === "object" && !Array.isArray(item));
+  }
+  if (args.choiceSelection && typeof args.choiceSelection === "object" && !Array.isArray(args.choiceSelection)) {
+    return [args.choiceSelection];
+  }
+  if (Array.isArray(args.generatedChoices)) {
+    return args.generatedChoices.filter((item) => item && typeof item === "object" && !Array.isArray(item));
+  }
+  if (args.generatedChoices && typeof args.generatedChoices === "object" && !Array.isArray(args.generatedChoices)) {
+    if (typeof args.generatedChoices.domain === "string") {
+      return [args.generatedChoices];
+    }
+    return ["wedge", "pricing", "feature"].flatMap((domain) => {
+      const value = args.generatedChoices[domain];
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [];
+      }
+      return [{ domain, ...value }];
+    });
+  }
+  return [];
+}
+
+async function selectChoice(args = {}) {
+  const projectId = await resolveProjectId(args);
+  if (!projectId) {
+    throw new Error("projectId is required. Pass projectId, set LAUNCHCHAIR_PROJECT_ID, or pass projectName.");
+  }
+  return api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/choices/select`, {
+    method: "POST",
+    body: {
+      domain: String(args.domain ?? "").trim() || undefined,
+      phaseKey: String(args.phaseKey ?? "").trim() || undefined,
+      bucketKey: String(args.bucketKey ?? "").trim() || undefined,
+      optionId: String(args.optionId ?? "").trim() || undefined,
+      optionTitle: String(args.optionTitle ?? "").trim() || undefined,
+      optionQuery: String(args.optionQuery ?? "").trim() || undefined,
+      resetDownstream: args.resetDownstream !== false,
+    },
+  });
+}
+
+async function continueProjectLoop(args = {}) {
+  const projectId = await resolveProjectId(args);
+  if (!projectId) {
+    throw new Error("projectId is required. Pass projectId, set LAUNCHCHAIR_PROJECT_ID, or pass projectName.");
+  }
+  const maxSteps = Math.min(Math.max(toInt(args.maxSteps, 8), 1), 25);
+  const stopPhaseKey = String(args.stopPhaseKey ?? "").trim();
+  const completionTarget =
+    String(args.completionTarget ?? "").trim() === "build_board_ready" ? "build_board_ready" : undefined;
+  const ideaSnapshot =
+    typeof args.ideaSnapshot === "object" && args.ideaSnapshot !== null && !Array.isArray(args.ideaSnapshot)
+      ? args.ideaSnapshot
+      : null;
+  const runnerTarget = config.modeTargets.codex === "claude_code" ? "claude_code" : config.modeTargets.codex;
+  const localRepoPath =
+    runnerTarget === "claude_code" ? config.localRepoPaths.claudeCode : config.localRepoPaths.codex;
+  const agentSetup = {
+    localRepoPath,
+    runnerTarget,
+    clientType: config.clientType,
+    ...(typeof args.agentSetup === "object" && args.agentSetup !== null && !Array.isArray(args.agentSetup)
+      ? args.agentSetup
+      : {}),
+  };
+  let pendingChoiceSelections = normalizeChoiceSelections(args);
+  const steps = [];
+  let final = null;
+
+  for (let index = 0; index < maxSteps; index += 1) {
+    const loop = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/loop/continue`, {
+      method: "POST",
+      body: {
+        ...(stopPhaseKey ? { stopPhaseKey } : {}),
+        ...(completionTarget ? { completionTarget } : {}),
+        ...(ideaSnapshot ? { ideaSnapshot } : {}),
+        ...(pendingChoiceSelections.length > 0 ? { choiceSelections: pendingChoiceSelections } : {}),
+        agentSetup,
+      },
+    });
+    pendingChoiceSelections = [];
+
+    if (loop.status !== "queued_run" && loop.status !== "waiting_for_run") {
+      final = loop;
+      break;
+    }
+
+    const run = loop.run;
+    if (!run?.id || !run?.prompt) {
+      final = loop;
+      break;
+    }
+
+    const execution = await executeRunner(run);
+    const stdout = String(execution.stdout ?? "").trim();
+    const stderr = String(execution.stderr ?? "").trim();
+    const output = stdout || stderr;
+    const completion = await api(`/api/agent/v1/runs/${encodeURIComponent(String(run.id))}/complete`, {
+      method: "POST",
+      body: {
+        status: "completed",
+        resultRaw: trimToBytes(output, config.maxPayloadBytes),
+        resultJsonPayload: trimToBytes(output, config.maxPayloadBytes),
+        resultMeta: {
+          exitCode: execution.exitCode ?? 0,
+          durationMs: execution.durationMs ?? 0,
+          target: targetForRun(run),
+          autoApplyRequested: run.autoApply === true,
+          runIntent: run.runIntent ?? "initial",
+          attemptNumber: run.attemptNumber ?? 1,
+          maxAttempts: run.maxAttempts ?? 1,
+          projectLoopStep: index + 1,
+        },
+        error: null,
+        clientName: String(args.clientName ?? "").trim() || config.clientName,
+        clientType: normalizeTarget(args.clientType ?? config.clientType, "other"),
+        clientVersion: String(args.clientVersion ?? "").trim() || config.clientVersion,
+      },
+    });
+
+    steps.push({
+      step: index + 1,
+      loop,
+      completed: completion?.run ?? null,
+      phaseComplete: completion?.run?.resultMeta?.loop?.phaseComplete ?? null,
+      queuedChildRun: completion?.run?.queuedChildRun ?? null,
+    });
+
+    const decision = String(completion?.run?.resultMeta?.loop?.decision ?? "");
+    if (decision.includes("failed") || decision.includes("blocked") || decision === "loop_error") {
+      final = {
+        status: "stopped_after_failed_step",
+        projectId,
+        message: `Project loop stopped after ${decision}.`,
+      };
+      break;
+    }
+  }
+
+  if (!final) {
+    final = {
+      status: "max_steps_reached",
+      projectId,
+      message: `Project loop stopped after maxSteps=${maxSteps}. Run again to continue.`,
+    };
+  }
+
+  return { projectId, stopPhaseKey: stopPhaseKey || null, completionTarget: completionTarget ?? null, steps, final };
+}
+
+async function createProject(args = {}) {
+  const requestedProjectKind = String(args.projectKind ?? "").trim().toLowerCase();
+  const featureProject = requestedProjectKind === "feature";
+  const fullLoop = featureProject && args.fullLoop === true;
+  const featureSnapshot =
+    typeof args.featureSnapshot === "object" && args.featureSnapshot !== null && !Array.isArray(args.featureSnapshot)
+      ? args.featureSnapshot
+      : undefined;
+  const planToBuildBoard = featureProject && (fullLoop || args.planToBuildBoard !== false);
+  if (featureProject) {
+    const description = String(
+      featureSnapshot?.description ??
+        featureSnapshot?.featureDescription ??
+        featureSnapshot?.desiredOutcome ??
+        args.oneLiner ??
+        "",
+    ).trim();
+    const problem = String(featureSnapshot?.problem ?? "").trim();
+    if (!featureSnapshot || !description || !problem) {
+      throw new Error(
+        "Feature project creation requires featureSnapshot with description and problem. Infer both from the user's request and available product context before calling this tool.",
+      );
+    }
+  }
+  const createArgs = { ...args };
+  delete createArgs.planToBuildBoard;
+  delete createArgs.maxSteps;
+  delete createArgs.fullLoop;
+  delete createArgs.buildMaxSteps;
+  const body = {
+    ...createArgs,
+    name: String(args.name ?? args.projectName ?? "").trim(),
+    oneLiner: String(args.oneLiner ?? "").trim(),
+    projectKind: requestedProjectKind || undefined,
+    projectType: featureProject ? undefined : String(args.projectType ?? "").trim() || undefined,
+    startLoop: planToBuildBoard ? false : args.startLoop === true,
+    stopPhaseKey: String(args.stopPhaseKey ?? "").trim() || undefined,
+    ideaSnapshot:
+      typeof args.ideaSnapshot === "object" && args.ideaSnapshot !== null && !Array.isArray(args.ideaSnapshot)
+        ? args.ideaSnapshot
+        : undefined,
+    featureSnapshot,
+  };
+  const payload = await api("/api/agent/v1/projects", {
+    method: "POST",
+    body,
+  });
+  const projectId = String(payload?.project?.id ?? payload?.projectId ?? "").trim();
+  if (projectId) {
+    config.projectId = projectId;
+  }
+  if (!planToBuildBoard || !projectId) {
+    return payload;
+  }
+
+  const planning = await continueProjectLoop({
+    projectId,
+    stopPhaseKey: "build",
+    completionTarget: "build_board_ready",
+    maxSteps: args.maxSteps ?? 12,
+  });
+  const build =
+    fullLoop && planning.final?.status === "build_board_ready"
+      ? await continueProjectLoop({
+          projectId,
+          stopPhaseKey: "build",
+          completionTarget: "phase_complete",
+          maxSteps: args.buildMaxSteps ?? 25,
+        })
+      : null;
+  return {
+    ...payload,
+    planning,
+    ...(build ? { build } : {}),
+    next: {
+      ...(payload?.next ?? {}),
+      planningStatus: planning.final?.status ?? "unknown",
+      ...(build ? { buildStatus: build.final?.status ?? "unknown" } : {}),
+      message:
+        build
+          ? build.final?.message ?? "Feature build loop stopped."
+          : planning.final?.status === "build_board_ready"
+          ? "Feature planning is complete and the Build Board is ready. No build cards were executed."
+          : planning.final?.message ?? "Feature project was created, but planning stopped before the Build Board was ready.",
+    },
+  };
+}
+
+const MCP_TOOLS = [
+  {
+    name: "launchchair_create_project",
+    description:
+      "Create a new LaunchChair Product project in the token workspace, optionally save the first Idea Snapshot, and optionally start the project loop. Requires a workspace-scoped token with projects.write.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        projectName: { type: "string" },
+        oneLiner: { type: "string" },
+        projectType: { type: "string", enum: ["b2b", "b2c", "both", "free"] },
+        startLoop: { type: "boolean", description: "If true, LaunchChair immediately calls loop/continue after creation." },
+        stopPhaseKey: { type: "string", description: "Optional stop phase when startLoop is true." },
+        ideaSnapshot: {
+          type: "object",
+          description:
+            "Optional first-bucket seed. Include problem, targetUser, solution, and optional jobToBeDone/whyNow.",
+          properties: {
+            problem: { type: "string" },
+            targetUser: { type: "string" },
+            solution: { type: "string" },
+            jobToBeDone: { type: "string" },
+            whyNow: { type: "string" },
+            resetDownstream: { type: "boolean" },
+          },
+          required: ["problem", "targetUser", "solution"],
+          additionalProperties: false,
+        },
+      },
+      anyOf: [{ required: ["name"] }, { required: ["projectName"] }],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "launchchair_status",
+    description: "Read LaunchChair Agent API catalog and scopes.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "launchchair_list_projects",
+    description:
+      "List LaunchChair projects visible to the current Agent API token. Use this to resolve a user-provided project name like LeafLore when LAUNCHCHAIR_PROJECT_ID is not configured.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Optional project-name search." },
+        projectName: { type: "string", description: "Alias for query." },
+        limit: { type: "number", description: "Default 25, max 50." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "launchchair_heartbeat",
+    description: "Send heartbeat and update connected agent metadata.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        projectName: { type: "string" },
+        clientName: { type: "string" },
+        clientType: { type: "string" },
+        clientVersion: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "launchchair_claim_next_run",
+    description: "Claim next queued Run with Agent job for token/project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        projectName: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "launchchair_complete_run",
+    description: "Complete/fail a claimed run by id. LaunchChair handles configured apply, validation, retry, and remediation decisions after completion.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        runId: { type: "string" },
+        status: { type: "string" },
+        resultRaw: { type: "string" },
+        resultJsonPayload: { type: "string" },
+        error: { type: "string" },
+      },
+      required: ["runId"],
+      additionalProperties: true,
+    },
+  },
+  {
+    name: "launchchair_run_once",
+    description: "Claim next queued run, execute local runner, then complete run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        projectName: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "launchchair_select_choice",
+    description:
+      "Select or change a generated LaunchChair user-choice option, such as wedge, pricing, or feature direction. Use this instead of generic SPEC_UPDATE for user-choice buckets.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        projectName: { type: "string" },
+        domain: { type: "string", enum: ["wedge", "pricing", "feature"] },
+        phaseKey: { type: "string" },
+        bucketKey: { type: "string" },
+        optionId: { type: "string" },
+        optionTitle: { type: "string" },
+        optionQuery: { type: "string" },
+        resetDownstream: {
+          type: "boolean",
+          description: "Defaults true. Reset downstream generated phases so the loop can rerun from the changed choice.",
+        },
+      },
+      anyOf: [{ required: ["domain"] }, { required: ["phaseKey", "bucketKey"] }],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "launchchair_continue_project",
+    description:
+      "Continue a LaunchChair project loop: inspect project state, queue the next agent-actionable step, execute it with the configured runner, complete it, apply/validate/remediate through LaunchChair, and return phase synthesis links when phases finish.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        projectName: {
+          type: "string",
+          description: "Optional project name to resolve through launchchair_list_projects when projectId is omitted.",
+        },
+        stopPhaseKey: {
+          type: "string",
+          description: "Optional stop phase. When omitted, LaunchChair selects the correct default for the project workflow.",
+        },
+        completionTarget: {
+          type: "string",
+          enum: ["phase_complete", "build_board_ready"],
+          description: "Optional completion boundary. build_board_ready stops after board generation and before card execution when supported.",
+        },
+        maxSteps: { type: "number", description: "Default 8, max 25." },
+        choiceSelection: {
+          type: "object",
+          description:
+            "Optional generated-choice override to apply before continuing, for example { domain: 'wedge', optionTitle: 'Local Plant Walk Companion', resetDownstream: true }.",
+          properties: {
+            domain: { type: "string", enum: ["wedge", "pricing", "feature"] },
+            phaseKey: { type: "string" },
+            bucketKey: { type: "string" },
+            optionId: { type: "string" },
+            optionTitle: { type: "string" },
+            optionQuery: { type: "string" },
+            resetDownstream: { type: "boolean" },
+          },
+          additionalProperties: false,
+        },
+        choiceSelections: {
+          type: "array",
+          description: "Optional list of generated-choice overrides to apply once before continuing.",
+          items: {
+            type: "object",
+            properties: {
+              domain: { type: "string", enum: ["wedge", "pricing", "feature"] },
+              phaseKey: { type: "string" },
+              bucketKey: { type: "string" },
+              optionId: { type: "string" },
+              optionTitle: { type: "string" },
+              optionQuery: { type: "string" },
+              resetDownstream: { type: "boolean" },
+            },
+            additionalProperties: false,
+          },
+        },
+        generatedChoices: {
+          type: "object",
+          description:
+            "Backward-compatible alias for choiceSelection(s). Prefer choiceSelection. Supports { domain, optionTitle } or { wedge: { optionTitle } }.",
+          additionalProperties: true,
+        },
+        ideaSnapshot: {
+          type: "object",
+          description:
+            "Optional first-bucket seed for Product Ideation / Idea Snapshot. If the loop is blocked on idea_snapshot, LaunchChair saves this structured brief and continues.",
+          properties: {
+            projectName: { type: "string" },
+            oneLiner: { type: "string" },
+            projectType: { type: "string", enum: ["b2b", "b2c", "both", "free"] },
+            problem: { type: "string" },
+            targetUser: { type: "string" },
+            solution: { type: "string" },
+            jobToBeDone: { type: "string" },
+            whyNow: { type: "string" },
+            resetDownstream: { type: "boolean" },
+          },
+          required: ["problem", "targetUser", "solution"],
+          additionalProperties: false,
+        },
+        agentSetup: {
+          type: "object",
+          description:
+            "Optional Stack Setup evidence. The MCP bridge sends localRepoPath, runnerTarget, and clientType automatically.",
+          additionalProperties: true,
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+const READ_ONLY_TOOLS = new Set(["launchchair_status", "launchchair_list_projects"]);
+
+function annotateTool(tool) {
+  return {
+    ...tool,
+    annotations: {
+      ...(tool.annotations ?? {}),
+      readOnlyHint: READ_ONLY_TOOLS.has(tool.name),
+      destructiveHint: false,
+      openWorldHint: true,
+    },
+  };
+}
+
+function mergeToolOverrides(baseTools, overrides) {
+  const baseByName = new Map(baseTools.map((tool) => [tool.name, tool]));
+  const overrideByName = new Map(overrides.map((tool) => [String(tool?.name ?? ""), tool]));
+  const merged = baseTools.map((tool) => ({ ...tool, ...(overrideByName.get(tool.name) ?? {}) }));
+  for (const override of overrides) {
+    const name = String(override?.name ?? "").trim();
+    if (name && !baseByName.has(name)) {
+      merged.push(override);
+    }
+  }
+  return merged.map(annotateTool);
+}
+
+function writeMessage(obj) {
+  const body = Buffer.from(JSON.stringify(obj), "utf8");
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  process.stdout.write(body);
+}
+
+function writeResult(id, result) {
+  writeMessage({ jsonrpc: "2.0", id, result });
+}
+
+function writeError(id, code, message, data = undefined) {
+  writeMessage({
+    jsonrpc: "2.0",
+    id,
+    error: { code, message, data },
+  });
+}
+
+function textResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}
+
+async function handleRpc(request) {
+  const method = String(request?.method ?? "");
+  const id = request?.id;
+  if (!method) {
+    if (id !== undefined) writeError(id, -32600, "Invalid Request");
+    return;
+  }
+
+  if (method === "initialize") {
+    const status = await loadStatus();
+    writeResult(id, {
+      protocolVersion: "2024-11-05",
+      capabilities: {
+        tools: {},
+      },
+      serverInfo: {
+        name: SERVER_NAME,
+        version: VERSION,
+      },
+      instructions: serverInstructions(status),
+    });
+    return;
+  }
+
+  if (method === "notifications/initialized") {
+    return;
+  }
+
+  if (method === "tools/list") {
+    const status = await loadStatus();
+    const overrides = Array.isArray(status?.capabilities?.mcpToolOverrides)
+      ? status.capabilities.mcpToolOverrides
+      : [];
+    const tools = mergeToolOverrides(MCP_TOOLS, overrides);
+    writeResult(id, { tools });
+    return;
+  }
+
+  if (method === "tools/call") {
+    const params = request?.params ?? {};
+    const toolName = String(params.name ?? "");
+    const args = typeof params.arguments === "object" && params.arguments ? params.arguments : {};
+    try {
+      if (toolName === "launchchair_status") {
+        const status = await api("/api/agent/v1");
+        writeResult(id, textResult(status));
+        return;
+      }
+      if (toolName === "launchchair_create_project") {
+        const payload = await createProject(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
+      if (toolName === "launchchair_create_feature_project") {
+        const payload = await createProject({ ...args, projectKind: "feature" });
+        writeResult(id, textResult(payload));
+        return;
+      }
+      if (toolName === "launchchair_list_projects") {
+        const payload = await listProjects(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
+      if (toolName === "launchchair_heartbeat") {
+        const payload = await heartbeat(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
+      if (toolName === "launchchair_claim_next_run") {
+        const payload = await claimNextRun(args);
+        writeResult(id, textResult({ run: payload }));
+        return;
+      }
+      if (toolName === "launchchair_complete_run") {
+        const payload = await completeRun(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
+      if (toolName === "launchchair_run_once") {
+        const payload = await runOnce(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
+      if (toolName === "launchchair_select_choice") {
+        const payload = await selectChoice(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
+      if (toolName === "launchchair_continue_project") {
+        const payload = await continueProjectLoop(args);
+        writeResult(id, textResult(payload));
+        return;
+      }
+      writeError(id, -32601, `Unknown tool: ${toolName}`);
+    } catch (error) {
+      writeResult(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                error: error instanceof Error ? error.message : String(error ?? "Tool failed"),
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+        isError: true,
+      });
+    }
+    return;
+  }
+
+  writeError(id, -32601, `Method not found: ${method}`);
+}
+
+let buffer = Buffer.alloc(0);
+process.stdin.on("data", (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const headerEnd = buffer.indexOf("\r\n\r\n");
+    if (headerEnd === -1) break;
+    const headerRaw = buffer.slice(0, headerEnd).toString("utf8");
+    const lines = headerRaw.split("\r\n");
+    let contentLength = -1;
+    for (const line of lines) {
+      const [key, value] = line.split(":");
+      if (key && value && key.toLowerCase() === "content-length") {
+        contentLength = Number.parseInt(value.trim(), 10);
+      }
+    }
+    if (!Number.isFinite(contentLength) || contentLength < 0) {
+      buffer = Buffer.alloc(0);
+      break;
+    }
+    const bodyStart = headerEnd + 4;
+    const bodyEnd = bodyStart + contentLength;
+    if (buffer.length < bodyEnd) break;
+    const body = buffer.slice(bodyStart, bodyEnd).toString("utf8");
+    buffer = buffer.slice(bodyEnd);
+    let parsed = null;
+    try {
+      parsed = JSON.parse(body);
+    } catch (_error) {
+      continue;
+    }
+    void handleRpc(parsed);
+  }
+});