@launchchair/agent 0.4.12 → 0.5.1

package/mcp-bridge-server.mjs

@@ -19,9 +19,12 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { resolveProjectWorkspace } from "./project-workspace.mjs";
 import { buildRunnerCommand, parseRunnerCommand } from "./runner-command.mjs";
+import { createMcpCapabilities, EXTRA_MCP_TOOLS, MCP_WORKFLOW_INSTRUCTIONS, VALIDATION_GATE_SCHEMA } from "./mcp-capabilities.mjs";
+import { MCP_WIDGET_TOOLS, MCP_WIDGET_INSTRUCTIONS, listWidgetResources, readWidgetResource, callWidgetTool } from "./mcp-widgets.mjs";
 
-const VERSION = "0.4.12";
+const VERSION = "0.5.1";
 const SERVER_NAME = "launchchair-agent-mcp";
+const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"]);
 const AGENT_SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = process.env.LAUNCHCHAIR_CONFIG_DIR?.trim()
   ? path.resolve(process.env.LAUNCHCHAIR_CONFIG_DIR.trim())
@@ -108,7 +111,7 @@ function builtInRunnerCommand(target) {
 }
 
 const config = {
-  baseUrl: env("LAUNCHCHAIR_BASE_URL", savedConfigValue("baseUrl", "http://localhost:3000")).replace(/\/+$/, ""),
+  baseUrl: env("LAUNCHCHAIR_BASE_URL", savedConfigValue("baseUrl", "https://www.launchchair.io")).replace(/\/+$/, ""),
   token: env("LAUNCHCHAIR_AGENT_TOKEN", env("LAUNCHCHAIR_API_KEY", savedConfigValue("agentToken"))),
   projectId: env("LAUNCHCHAIR_PROJECT_ID", savedConfigValue("projectId")) || null,
   clientName: env("LC_AGENT_CLIENT_NAME", "MCP Bridge"),
@@ -135,70 +138,52 @@ const config = {
   },
 };
 
-if (!config.token) {
-  // eslint-disable-next-line no-console
-  console.error(
-    `Missing LaunchChair Agent API token. Run "launchchair login" or set LAUNCHCHAIR_AGENT_TOKEN. Checked ${CONFIG_PATH}.`,
-  );
-  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);
-}
+let statusPromise = null;
+let initialized = false;
+const capabilities = createMcpCapabilities({ config, configPath: CONFIG_PATH, api, resolveProjectId, onAuthChange: () => { statusPromise = null; if (initialized) writeMessage({ jsonrpc: "2.0", method: "notifications/tools/list_changed" }); } });
 
 async function api(path, { method = "GET", body } = {}) {
+  const token = capabilities.currentToken();
+  if (!token) {
+    const error = new Error("Login required. Call launchchair_login and complete browser approval.");
+    error.status = 401;
+    error.payload = { code: "login_required", nextTool: "launchchair_login" };
+    throw error;
+  }
   const response = await fetch(`${config.baseUrl}${path}`, {
     method,
     headers: {
-      Authorization: `Bearer ${config.token}`,
+      Authorization: `Bearer ${token}`,
       "Content-Type": "application/json",
     },
     body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
   });
 
-  let payload = null;
-  try {
-    payload = await response.json();
-  } catch (_error) {
-    payload = null;
-  }
+  const raw = await response.text();
+  let payload;
+  try { payload = raw ? JSON.parse(raw) : null; } catch { payload = { content: raw, contentType: response.headers.get("content-type") }; }
 
   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.payload = response.status === 401 ? { ...payload, code: "login_required", nextTool: "launchchair_login" } : 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);
+    statusPromise = api("/api/agent/v1").catch(() => { statusPromise = null; return null; });
   }
   return statusPromise;
 }
 
 function serverInstructions(status) {
   const featureInstructions = String(status?.capabilities?.mcpServerInstructions ?? "").trim();
-  return featureInstructions ? `${BASE_SERVER_INSTRUCTIONS} ${featureInstructions}` : BASE_SERVER_INSTRUCTIONS;
+  return `${BASE_SERVER_INSTRUCTIONS} ${featureInstructions} ${MCP_WORKFLOW_INSTRUCTIONS} ${MCP_WIDGET_INSTRUCTIONS}`;
 }
 
 function targetForRun(run) {
@@ -291,6 +276,7 @@ async function executeRunner(run) {
         LC_AGENT_PROMPT_MODE: String(run.promptMode ?? ""),
         LC_AGENT_RUN_TYPE: String(run.runType ?? ""),
         [workspaceEnvName]: workspace.path,
+        ...(workspace.source === "isolated" && run?.runnerWorkspace?.requiresRepository !== true ? { LC_AGENT_CODEX_SKIP_GIT_CHECK: "1" } : {}),
       },
     });
     let stdout = "";
@@ -347,6 +333,7 @@ async function claimNextRun(args = {}) {
     method: "POST",
     body: {
       projectId,
+      ...(args.runId ? { runId: String(args.runId) } : {}),
       clientName: String(args.clientName ?? "").trim() || config.clientName,
       clientType: normalizeTarget(args.clientType ?? config.clientType, "other"),
       clientVersion: String(args.clientVersion ?? "").trim() || config.clientVersion,
@@ -600,15 +587,19 @@ async function continueProjectLoop(args = {}) {
       break;
     }
 
-    const run = loop.run
-      ? { ...loop.run, runnerWorkspace: loop.runnerWorkspace ?? runnerWorkspaceContext }
-      : null;
-    if (!run?.id || !run?.prompt) {
-      final = loop;
+    const claimed = loop.run?.id ? await claimNextRun({ ...args, projectId, runId: loop.run.id }) : null;
+    if (!claimed) {
+      final = { ...loop, run: loop.run?.id ? { id: loop.run.id } : null, message: "Run already claimed; do not execute it again." };
+      break;
+    }
+    const run = { ...claimed, runnerWorkspace: claimed.runnerWorkspace ?? loop.runnerWorkspace ?? runnerWorkspaceContext };
+    let execution;
+    try { execution = await executeRunner(run); }
+    catch (error) {
+      await completeRun({ runId: run.id, status: "failed", error: error.message, resultRaw: error.stdout || error.stderr || "" });
+      final = { status: "stopped_after_failed_step", projectId, runId: run.id, message: error.message };
       break;
     }
-
-    const execution = await executeRunner(run);
     const stdout = String(execution.stdout ?? "").trim();
     const stderr = String(execution.stderr ?? "").trim();
     const output = stdout || stderr;
@@ -695,6 +686,7 @@ async function createProject(args = {}) {
   delete createArgs.maxSteps;
   delete createArgs.fullLoop;
   delete createArgs.buildMaxSteps;
+  delete createArgs.executionMode;
   const body = {
     ...createArgs,
     name: String(args.name ?? args.projectName ?? "").trim(),
@@ -721,6 +713,8 @@ async function createProject(args = {}) {
     return payload;
   }
 
+  if (args.executionMode !== "local_runner") return { ...payload, next: { ...payload.next, tool: "launchchair_next_step", arguments: { projectId, stopPhaseKey: "build", completionTarget: fullLoop ? "phase_complete" : "build_board_ready" }, execution: "host", instructions: MCP_WORKFLOW_INSTRUCTIONS } };
+
   const planning = await continueProjectLoop({
     projectId,
     stopPhaseKey: "build",
@@ -997,10 +991,11 @@ const READ_ONLY_TOOLS = new Set(["launchchair_status", "launchchair_list_project
 function annotateTool(tool) {
   return {
     ...tool,
+    ...(tool.name === "launchchair_select_choice" ? { _meta: { ...tool._meta, ui: { visibility: ["model", "app"] }, "openai/widgetAccessible": true } } : {}),
     annotations: {
       ...(tool.annotations ?? {}),
-      readOnlyHint: READ_ONLY_TOOLS.has(tool.name),
-      destructiveHint: false,
+      readOnlyHint: tool.annotations?.readOnlyHint ?? READ_ONLY_TOOLS.has(tool.name),
+      destructiveHint: tool.annotations?.destructiveHint ?? false,
       openWorldHint: true,
     },
   };
@@ -1016,7 +1011,12 @@ function mergeToolOverrides(baseTools, overrides) {
       merged.push(override);
     }
   }
-  return merged.map(annotateTool);
+  return merged.map((tool) => {
+    if (["launchchair_create_project", "launchchair_create_feature_project"].includes(tool.name)) tool = { ...tool, inputSchema: { ...tool.inputSchema, properties: { ...tool.inputSchema.properties, idempotencyKey: { type: "string" }, ideaIntent: { type: "string", enum: ["preserve", "explore"], default: "preserve" }, validationGate: VALIDATION_GATE_SCHEMA, executionMode: { type: "string", enum: ["host", "local_runner"], default: "host" } } } };
+    if (tool.name === "launchchair_claim_next_run") tool = { ...tool, inputSchema: { ...tool.inputSchema, properties: { ...tool.inputSchema.properties, runId: { type: "string" } } } };
+    if (tool.name === "launchchair_continue_project") tool = { ...tool, description: "Advance one step in the current host agent by default. Only use executionMode=local_runner to spawn a separate local CLI.", inputSchema: { ...tool.inputSchema, properties: { ...tool.inputSchema.properties, executionMode: { type: "string", enum: ["host", "local_runner"], default: "host" } } } };
+    return annotateTool(tool);
+  });
 }
 
 function writeMessage(obj) {
@@ -1037,6 +1037,7 @@ function writeError(id, code, message, data = undefined) {
 
 function textResult(payload) {
   return {
+    ...(payload && typeof payload === "object" && !Array.isArray(payload) ? { structuredContent: payload } : {}),
     content: [
       {
         type: "text",
@@ -1057,9 +1058,10 @@ async function handleRpc(request) {
   if (method === "initialize") {
     const status = await loadStatus();
     writeResult(id, {
-      protocolVersion: "2024-11-05",
+      protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.has(request?.params?.protocolVersion) ? request.params.protocolVersion : "2025-11-25",
       capabilities: {
-        tools: {},
+        tools: { listChanged: true },
+        resources: {},
       },
       serverInfo: {
         name: SERVER_NAME,
@@ -1071,6 +1073,23 @@ async function handleRpc(request) {
   }
 
   if (method === "notifications/initialized") {
+    initialized = true;
+    return;
+  }
+
+  if (method === "resources/list") {
+    writeResult(id, { resources: listWidgetResources() });
+    return;
+  }
+
+  if (method === "resources/read") {
+    try { writeResult(id, readWidgetResource(request?.params?.uri)); }
+    catch (error) { writeError(id, -32002, error.message); }
+    return;
+  }
+
+  if (method === "ping") {
+    writeResult(id, {});
     return;
   }
 
@@ -1079,7 +1098,7 @@ async function handleRpc(request) {
     const overrides = Array.isArray(status?.capabilities?.mcpToolOverrides)
       ? status.capabilities.mcpToolOverrides
       : [];
-    const tools = mergeToolOverrides(MCP_TOOLS, overrides);
+    const tools = [...mergeToolOverrides([...MCP_TOOLS, ...EXTRA_MCP_TOOLS], overrides), ...MCP_WIDGET_TOOLS];
     writeResult(id, { tools });
     return;
   }
@@ -1089,9 +1108,17 @@ async function handleRpc(request) {
     const toolName = String(params.name ?? "");
     const args = typeof params.arguments === "object" && params.arguments ? params.arguments : {};
     try {
+      if (MCP_WIDGET_TOOLS.some((tool) => tool.name === toolName)) {
+        writeResult(id, await callWidgetTool(toolName, args, { api, resolveProjectId, baseUrl: config.baseUrl }));
+        return;
+      }
+      if (EXTRA_MCP_TOOLS.some((tool) => tool.name === toolName)) {
+        writeResult(id, textResult(await capabilities.dispatch(toolName, args)));
+        return;
+      }
       if (toolName === "launchchair_status") {
         const status = await api("/api/agent/v1");
-        writeResult(id, textResult(status));
+        writeResult(id, textResult({ ...status, authenticated: true }));
         return;
       }
       if (toolName === "launchchair_create_project") {
@@ -1140,7 +1167,7 @@ async function handleRpc(request) {
         return;
       }
       if (toolName === "launchchair_continue_project") {
-        const payload = await continueProjectLoop(args);
+        const payload = args.executionMode === "local_runner" ? await continueProjectLoop(args) : await capabilities.dispatch("launchchair_next_step", { ...args, executionMode: undefined, maxSteps: undefined });
         writeResult(id, textResult(payload));
         return;
       }

package/mcp-capabilities.mjs

@@ -0,0 +1,227 @@
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { bindProjectWorkspace } from "./project-workspace.mjs";
+
+const string = { type: "string" };
+const object = { type: "object", additionalProperties: true };
+const patch = { type: "array", items: { type: "object", properties: { op: { type: "string", enum: ["add", "replace", "remove"] }, path: string, value: {} }, required: ["op", "path"], additionalProperties: false } };
+const project = { projectId: string, projectName: string };
+const bucket = { ...project, phaseKey: string, bucketKey: string };
+const card = { ...project, cardId: string };
+export const VALIDATION_GATE_SCHEMA = { anyOf: [{ type: "string", enum: ["very_high"] }, { type: "object", properties: { minPain: { type: "number", minimum: 0, maximum: 100 }, minOpportunity: { type: "number", minimum: 0, maximum: 100 }, maxSaturation: { type: "number", minimum: 0, maximum: 100 } }, additionalProperties: false }] };
+export const MCP_WORKFLOW_INSTRUCTIONS = "Prefer launchchair_next_step: execute the returned claimed prompt in THIS host agent using its existing research, repository, GitHub, Vercel and Supabase tools, then launchchair_complete_run and repeat. Do not start a second model/CLI unless the user requests local-runner execution. The server cannot inherit or call the host's other plugins itself. Preserve a supplied idea by default, including when scores are low; report risks without rewriting the source problem, audience, solution or specified requirements. Only use ideaIntent=explore when the user requests discovery/pivots. Validation gates are opt-in: do not impose a gate on an established idea unless the user requested one. For 'VERY high' scores use validationGate=very_high (pain>=85, opportunity>=85, saturation<=30). Research real evidence, create separate candidates, finish validation and compare LaunchChair scorecards, never inflate evidence or use direction-option scores as validation. Stop at a failed gate. If no candidate qualifies, report that honestly. Use connected infrastructure plugins only after the gate passes, save their verified results with update_bucket plus executionEvidence, bind the repository, and continue. Present actual authorization/production SQL checkpoints; reuse existing plugin authorization. Do not claim external actions were done without evidence. Complete runnable QA yourself and record results; ask for human checks only when truly necessary. Never disclose bearer tokens or private login device codes.";
+
+function tool(name, description, properties = {}, required = [], readOnly = false) {
+  return { name: `launchchair_${name}`, description, inputSchema: { type: "object", properties, required, additionalProperties: false }, annotations: { readOnlyHint: readOnly, destructiveHint: ["revoke_token", "cancel_run", "write_competitor_note", "upload_logo"].includes(name), openWorldHint: true } };
+}
+
+const definitions = [
+  ["list_competitor_notes", "Read competitor research notes in the current project.", project, [], "GET", "/competitor-notes"],
+  ["write_competitor_note", "Create, update, or delete a competitor note. Updating/deleting requires authorship or active owner access.", { ...project, operation: { type: "string", enum: ["create", "update", "delete"] }, noteId: string, competitorKey: string, competitorName: string, content: string }, ["operation"], "POST", "/competitor-notes"],
+  ["upload_logo", "Upload a PNG/WebP logo (base64, up to 1 MiB) or remove the existing logo with remove=true. Use the host's image tools to create the logo first.", { ...project, contentBase64: string, mimeType: { type: "string", enum: ["image/png", "image/webp"] }, generationPrompt: string, remove: { type: "boolean" } }, [], "POST", "/logo"],
+  ["research_sources", "Fetch LaunchChair research sources: Hacker News search, Product Hunt ranked posts, or a public HTTPS RSS feed (including Reddit/Indie Hackers). Returns source material without changing the idea. Inspect evidence before saving findings via bucket tools.", { ...project, source: { type: "string", enum: ["hn", "product_hunt", "rss"] }, query: string, url: string, limit: { type: "integer", minimum: 1, maximum: 40 } }, ["source"], "POST", "/research"],
+  ["search_media", "Search LaunchChair's Pexels integration for photos/videos. Retain source and creator attribution; save selected assets through the appropriate bucket.", { ...project, query: string, kind: { type: "string", enum: ["photo", "video"] }, limit: { type: "integer", minimum: 1, maximum: 40 } }, ["query"], "POST", "/media"],
+  ["get_starter", "Read the private LaunchChair starter manifest, then download batches of files (base64) using paths and treeSha. Paid, scoped, and validation-gated. Create/commit/deploy the repository with the host GitHub/Vercel/Supabase tools; no provider credentials are transferred to LaunchChair.", { ...project, paths: { type: "array", items: string, minItems: 1, maxItems: 20 }, treeSha: string }, [], "POST", "/starter"],
+  ["get_spec", "Read the normalized project spec, validation scores and saved idea intent.", project, [], "GET", "/spec"],
+  ["update_spec", "Advanced guarded spec patch. Requires spec.write; default tokens use bucket-specific tools. Cannot change idea intent or validation policy.", { ...project, patch }, ["patch"], "PATCH", "/spec"],
+  ["list_buckets", "List all phases/buckets and progress.", project, [], "GET", "/buckets"],
+  ["get_bucket", "Read a bucket's data, allowed patch paths and evidence requirements before editing.", bucket, ["phaseKey", "bucketKey"], "GET", "/buckets/:phaseKey/:bucketKey"],
+  ["update_bucket", "Save form/checklist data using allowed JSON Patch paths, or update status. For setup and checklists supply factual executionEvidence {source,checkedAt,summary} from the host's connected plugins/tests. Never store credentials. Read get_bucket first. Does not provision infrastructure itself.", { ...bucket, patch, status: { type: "string", enum: ["not_started", "in_progress", "done"] }, executionEvidence: object }, ["phaseKey", "bucketKey"], "PATCH", "/buckets/:phaseKey/:bucketKey"],
+  ["get_bucket_prompt", "Read a bucket's compiled prompt for execution by the current host agent. Brand supports variant=tagline or logo; campaign_builder requires campaignId. Save generated form output with update_bucket.", { ...bucket, variant: { type: "string", enum: ["tagline", "logo"] }, campaignId: string }, ["phaseKey", "bucketKey"], "GET", "/buckets/:phaseKey/:bucketKey/prompt"],
+  ["apply_bucket_update", "Apply validated SPEC_UPDATE JSON Patch for a prompt bucket. Prefer complete_run for claimed runs so validation/remediation executes.", { ...bucket, patch, compiledPrompt: string, templateKey: string, pastedResponse: string }, ["phaseKey", "bucketKey", "patch"], "POST", "/buckets/:phaseKey/:bucketKey/apply-spec-update"],
+  ["get_build_cards", "Inspect build cards, dependencies, SQL actions and QA checkpoints.", project, [], "GET", "/build-cards"],
+  ["update_build_card", "Record build-card status, acceptance, SQL completion and QA results only after verification. Supply executionEvidence {source,checkedAt,summary} when completing a card or checking results. This records results, it does not execute SQL or tests.", { ...card, status: { type: "string", enum: ["To Do", "In Progress", "Needs Review", "Done"] }, notes: string, acceptanceStatus: object, testingNotesStatus: object, sqlActionsStatus: object, executionEvidence: object }, ["cardId", "status"], "PATCH", "/build-cards/:cardId"],
+  ["get_build_card_prompt", "Read the compiled build-card prompt. Requires a passing validation gate when configured.", card, ["cardId"], "GET", "/build-cards/:cardId/prompt"],
+  ["apply_build_card_run", "Apply CHANGELOG_JSON/REQUIRES from an executed build card. Use the API payload contract returned by the catalog.", { ...card, payload: object }, ["cardId", "payload"], "POST", "/build-cards/:cardId/apply-run"],
+  ["export_mvp_spec", "Export the AI-ready MVP markdown specification.", project, [], "GET", "/exports/mvp-ai-spec"],
+  ["export_phase", "Export a phase synthesis as markdown.", { ...project, phaseKey: string }, ["phaseKey"], "GET", "/exports/phase/:phaseKey"],
+  ["get_runner_workspace", "Read expected repository and workspace requirements.", project, [], "GET", "/runner-workspace"],
+  ["get_validation_gate", "Evaluate the saved validation gate using current calculated LaunchChair scores.", project, [], "GET", "/validation-gate"],
+  ["set_validation_gate", "Set or tighten an explicitly user-requested gate. Does not authorize changing the user's idea. An existing gate cannot be weakened by this tool.", { ...project, validationGate: VALIDATION_GATE_SCHEMA }, ["validationGate"], "POST", "/validation-gate"],
+  ["list_runs", "List recent runs belonging to this token and project.", project, [], "GET", "/runs"],
+  ["queue_run", "Queue a specific prompt bucket or build-card run, including research reruns. Then claim it and execute in this host agent; complete_run applies and validates the result.", { ...bucket, cardId: string }, [], "POST", "/runs"],
+];
+
+export const EXTRA_MCP_TOOLS = [
+  ...definitions.map(([name, description, properties, required, method]) => tool(name, description, properties, required, method === "GET")),
+  tool("login", "Start browser-assisted LaunchChair login/token creation without an existing token. Return the existing LaunchChair approval URL for the user; then poll login_status. No password or token is requested in chat.", { tokenName: string, restart: { type: "boolean" } }),
+  tool("login_status", "Poll the pending browser approval once. Respect retryAfterSeconds. On approval save the token privately and authenticate this MCP session immediately.", {}),
+  tool("logout", "Disconnect this MCP and remove its saved token. Optionally revoke the current token on the server first.", { revoke: { type: "boolean", default: false } }),
+  tool("list_tokens", "List redacted tokens. Requires fresh owner authorization with tokens.manage and workspace-wide access.", {}, [], true),
+  tool("create_token", "Create a token with no more privileges/lifetime than the current token. Store its secret in a private local file and return only metadata/path. Optionally activate it for this MCP. Requires tokens.manage from owner-approved login.", { name: string, projectIds: { type: "array", items: string }, scopes: { type: "array", items: string }, expiresAt: string, activate: { type: "boolean", default: false } }, ["name"]),
+  tool("revoke_token", "Revoke a token in the authorized workspace. Revoking the current token disconnects this MCP.", { tokenId: string }, ["tokenId"]),
+  tool("get_run", "Read a run's status and output. Do not execute a run already claimed by another worker.", { runId: string }, ["runId"], true),
+  tool("cancel_run", "Cancel a queued/running run so further results cannot be applied. Stop any host process separately.", { runId: string }, ["runId"]),
+  tool("next_step", "Queue and atomically claim ONE next step for THIS host agent, without spawning a separate runner. Execute its prompt with your own tools/plugins, complete_run, then call again. Returns forms/setup/gate checkpoints when applicable. Set stopPhaseKey=launch_sales for the entire Product workflow, or market_validation for research only.", { ...project, stopPhaseKey: string, completionTarget: { type: "string", enum: ["phase_complete", "build_board_ready"] }, ideaSnapshot: object, choiceSelections: { type: "array", items: object }, agentSetup: object }, []),
+  tool("bind_repository", "Bind a local clone after checking its Git origin against the repository saved in LaunchChair. No cloning or infrastructure provisioning occurs.", { ...project, cwd: string }, ["cwd"]),
+  tool("compare_projects", "Compare up to 20 candidate ideas using calculated validation scores and requested thresholds. Never mutates ideas or inflates scores; returns qualifying candidates separately.", { projectIds: { type: "array", items: string, minItems: 1, maxItems: 20 }, validationGate: VALIDATION_GATE_SCHEMA }, ["projectIds"], true),
+  tool("research_opportunities", "Get a bounded research workflow for an explicitly exploratory user request. Execute the research using this host's search tools, then create and validate separate LaunchChair candidates. This tool itself does not research or create projects.", { audience: string, maxCandidates: { type: "integer", minimum: 1, maximum: 20, default: 5 }, validationGate: VALIDATION_GATE_SCHEMA }, ["audience"], true),
+];
+
+export function createMcpCapabilities({ config, configPath, api, resolveProjectId, onAuthChange }) {
+  let sessionToken;
+  let pollInFlight = false;
+  let authEpoch = 0;
+  const projectSteps = new Set();
+  const configDir = path.dirname(configPath);
+  function readConfig() { try { const value = JSON.parse(readFileSync(configPath, "utf8")); return value && typeof value === "object" && !Array.isArray(value) ? value : {}; } catch { return {}; } }
+  function saveConfig(changes) {
+    const next = { ...readConfig(), ...changes };
+    for (const key of Object.keys(next)) if (next[key] === undefined) delete next[key];
+    mkdirSync(configDir, { recursive: true, mode: 0o700 });
+    const temporary = `${configPath}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    renameSync(temporary, configPath);
+    chmodSync(configPath, 0o600);
+  }
+  function currentToken() {
+    if (sessionToken !== undefined) return sessionToken;
+    const saved = readConfig();
+    if (saved.mcpLoggedOut === true) return "";
+    if (saved.mcpPreferSavedToken === true && saved.agentToken) return saved.agentToken;
+    return process.env.LAUNCHCHAIR_AGENT_TOKEN?.trim() || process.env.LAUNCHCHAIR_API_KEY?.trim() || saved.agentToken || "";
+  }
+  function activate(token) {
+    saveConfig({ agentToken: token, baseUrl: config.baseUrl, mcpLoggedOut: false, mcpPreferSavedToken: true, pendingMcpLogin: undefined });
+    sessionToken = token;
+    onAuthChange();
+  }
+  function disconnect() {
+    authEpoch += 1;
+    saveConfig({ agentToken: undefined, pendingMcpLogin: undefined, mcpLoggedOut: true });
+    sessionToken = "";
+    onAuthChange();
+  }
+  async function publicRequest(endpoint, body) {
+    const response = await fetch(`${config.baseUrl}${endpoint}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+    const payload = await response.json();
+    if (response.status === 429) return { status: "pending", retryAfterSeconds: Math.max(5, Number(response.headers.get("retry-after")) || 10) };
+    if (!response.ok) {
+      const error = new Error(String(payload.error || payload.status || `HTTP ${response.status}`));
+      error.status = response.status;
+      throw error;
+    }
+    return payload;
+  }
+  async function loginStatus() {
+    const saved = readConfig().pendingMcpLogin;
+    if (!saved) return { status: currentToken() ? "authenticated" : "not_started", nextTool: currentToken() ? "launchchair_status" : "launchchair_login" };
+    if (Date.now() >= saved.expiresAt) { saveConfig({ pendingMcpLogin: undefined }); return { status: "expired", nextTool: "launchchair_login" }; }
+    if (pollInFlight || Date.now() < (saved.nextPollAt || 0)) return { status: "pending", retryAfterSeconds: Math.max(1, Math.ceil(((saved.nextPollAt || Date.now() + 5000) - Date.now()) / 1000)) };
+    pollInFlight = true;
+    const epoch = authEpoch;
+    try {
+      const result = await publicRequest("/api/agent/v1/cli-login/poll", { deviceCode: saved.deviceCode });
+      if (epoch !== authEpoch || readConfig().pendingMcpLogin?.deviceCode !== saved.deviceCode) return { status: "cancelled", nextTool: "launchchair_login" };
+      if (result.status === "approved" && result.token) {
+        activate(result.token);
+        return { status: "authenticated", tokenRecord: result.tokenRecord, nextTool: "launchchair_status", message: "Login approved; token saved privately. MCP is ready without restarting." };
+      }
+      const retryAfterSeconds = Math.max(5, Number(result.retryAfterSeconds || result.interval) || 5);
+      saveConfig({ pendingMcpLogin: { ...saved, nextPollAt: Date.now() + retryAfterSeconds * 1000 } });
+      return { status: result.status || "pending", retryAfterSeconds };
+    } catch (error) {
+      if ([400, 403, 404, 410].includes(error.status)) saveConfig({ pendingMcpLogin: undefined });
+      throw error;
+    } finally { pollInFlight = false; }
+  }
+  async function dispatch(name, args) {
+    if (name === "launchchair_login") {
+      let pending = readConfig().pendingMcpLogin;
+      if (!pending || pending.expiresAt <= Date.now() || args.restart === true) {
+        const epoch = ++authEpoch;
+        const started = await publicRequest("/api/agent/v1/cli-login/start", { clientName: "LaunchChair MCP", tokenName: args.tokenName || "LaunchChair MCP" });
+        if (epoch !== authEpoch) return { status: "cancelled", nextTool: "launchchair_login" };
+        if (!started.deviceCode || !started.verificationUriComplete) return { status: "rate_limited", retryAfterSeconds: started.retryAfterSeconds || 10 };
+        const approvalUrl = new URL(started.verificationUriComplete);
+        if (approvalUrl.origin !== new URL(config.baseUrl).origin) throw new Error("Login approval URL does not match the configured LaunchChair origin.");
+        pending = { deviceCode: started.deviceCode, userCode: started.userCode, approvalUrl: approvalUrl.toString(), expiresAt: Date.now() + Number(started.expiresIn || 600) * 1000, nextPollAt: 0 };
+        saveConfig({ pendingMcpLogin: pending });
+      }
+      return { status: "approval_required", approvalUrl: pending.approvalUrl, userCode: pending.userCode, expiresAt: new Date(pending.expiresAt).toISOString(), nextTool: "launchchair_login_status", message: "Open this LaunchChair URL, sign in if needed, and approve this MCP. The workspace owner authorizes token creation." };
+    }
+    if (name === "launchchair_login_status") return loginStatus();
+    if (name === "launchchair_logout") {
+      if (args.revoke === true && currentToken()) {
+        const tokens = await api("/api/agent/v1/tokens");
+        await api(`/api/agent/v1/tokens/${encodeURIComponent(tokens.currentTokenId)}/revoke`, { method: "POST", body: {} });
+      }
+      disconnect();
+      return { status: "logged_out", revoked: args.revoke === true };
+    }
+    if (name === "launchchair_list_tokens") return api("/api/agent/v1/tokens");
+    if (name === "launchchair_create_token") {
+      const { activate: useToken, ...body } = args;
+      const created = await api("/api/agent/v1/tokens", { method: "POST", body });
+      if (!created.token || !created.tokenRecord?.id) throw new Error("Token creation returned incomplete credentials.");
+      const credentialPath = path.join(configDir, "tokens", `${randomUUID()}.json`);
+      mkdirSync(path.dirname(credentialPath), { recursive: true, mode: 0o700 });
+      writeFileSync(credentialPath, JSON.stringify({ agentToken: created.token, baseUrl: config.baseUrl, tokenRecord: created.tokenRecord }) + "\n", { mode: 0o600, flag: "wx" });
+      if (useToken === true) activate(created.token);
+      return { tokenRecord: created.tokenRecord, credentialPath, activated: useToken === true, message: "Token secret saved privately; do not print the credential file in chat." };
+    }
+    if (name === "launchchair_revoke_token") {
+      const result = await api(`/api/agent/v1/tokens/${encodeURIComponent(args.tokenId)}/revoke`, { method: "POST", body: {} });
+      if (result.currentTokenRevoked) disconnect();
+      return result;
+    }
+    if (name === "launchchair_get_run" || name === "launchchair_cancel_run") return api(`/api/agent/v1/runs/${encodeURIComponent(args.runId)}`, name.endsWith("cancel_run") ? { method: "PATCH", body: {} } : {});
+    if (name === "launchchair_next_step") {
+      const projectId = await resolveProjectId(args);
+      const { projectId: _id, projectName: _name, ...body } = args;
+      if (projectSteps.has(projectId)) return { status: "waiting_for_run", projectId, message: "A next_step request is already in progress for this project. Wait for its result." };
+      projectSteps.add(projectId);
+      try {
+      const step = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/loop/continue`, { method: "POST", body });
+      if (step.status === "needs_human_input" && step.current) return { ...step, hostAction: { tool: step.current.cardId ? "launchchair_get_build_cards" : "launchchair_get_bucket", arguments: { projectId, phaseKey: step.current.phaseKey, bucketKey: step.current.bucketKey }, instructions: "Inspect the checkpoint and act with existing user authorization and connected tools. Save verified form/QA results or select a choice consistent with the supplied idea. Ask the user only for information or authorization that is actually missing." } };
+      if (!["queued_run", "waiting_for_run"].includes(step.status) || !step.run?.id) return step;
+      const claimed = await api("/api/agent/v1/runs/next", { method: "POST", body: { projectId, runId: step.run.id, clientName: config.clientName, clientType: config.clientType, clientVersion: config.clientVersion } });
+      if (!claimed.run) return { ...step, run: { id: step.run.id }, status: "waiting_for_run", message: "This run is already claimed. Poll get_run; do not execute it again." };
+      return { ...step, status: "run_ready", run: claimed.run, execution: "host", nextTool: "launchchair_complete_run", instructions: MCP_WORKFLOW_INSTRUCTIONS };
+      } finally { projectSteps.delete(projectId); }
+    }
+    if (name === "launchchair_bind_repository") {
+      const projectId = await resolveProjectId(args);
+      const { workspace } = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/runner-workspace`);
+      const repositoryUrl = workspace?.repository?.repoUrl;
+      if (!repositoryUrl) throw new Error("Save the project repository URL in LaunchChair before binding a clone.");
+      const bound = bindProjectWorkspace({ configPath, projectId, cwd: args.cwd, repositoryUrl });
+      return { projectId, binding: bound };
+    }
+    if (name === "launchchair_research_opportunities") return { audience: args.audience, maxCandidates: args.maxCandidates || 5, validationGate: args.validationGate ?? null, ideaIntent: "explore", steps: ["Research the audience's complaints, current workflows, substitutes, willingness to pay and named competitors using the host's search tools. Cite real sources and distinguish hypotheses from evidence.", "Create separate Product candidates with ideaSnapshot, ideaIntent=explore and a stable idempotencyKey. Include validationGate only when the user requested a score threshold.", "For each candidate call next_step with stopPhaseKey=market_validation, execute the prompt, complete_run and repeat. Inspect errors and perform requested remediation.", "Compare using compare_projects. Build only a qualifying candidate; if none qualifies, continue bounded research or report the unmet thresholds honestly.", "Use host GitHub/Vercel/Supabase plugins after the gate passes, record verified setup with update_bucket, bind_repository, then next_step through launch_sales."], instructions: MCP_WORKFLOW_INSTRUCTIONS };
+    if (name === "launchchair_compare_projects") {
+      if (!Array.isArray(args.projectIds) || !args.projectIds.length || args.projectIds.length > 20) throw new Error("Provide 1–20 projectIds.");
+      const thresholds = args.validationGate && typeof args.validationGate === "object" ? { minPain: 85, minOpportunity: 85, maxSaturation: 30, ...args.validationGate } : { minPain: 85, minOpportunity: 85, maxSaturation: 30 };
+      if (Object.values(thresholds).some((value) => typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100)) throw new Error("Validation thresholds must be numbers between 0 and 100.");
+      const candidates = [];
+      for (const projectId of [...new Set(args.projectIds)]) {
+        const payload = await api(`/api/agent/v1/projects/${encodeURIComponent(projectId)}/scorecards`);
+        const validation = payload.validationScorecards || payload.scorecards;
+        const cards = Array.isArray(validation) ? validation : validation?.scorecards || [];
+        const score = (id) => cards.find((entry) => entry.id === id)?.score;
+        const pain = score("icp_pain"), opportunity = score("wedge_opportunity"), saturation = score("market_saturation");
+        const qualifies = [pain, opportunity, saturation].every((value) => typeof value === "number") && pain >= thresholds.minPain && opportunity >= thresholds.minOpportunity && saturation <= thresholds.maxSaturation;
+        candidates.push({ projectId, qualifies, pain, opportunity, saturation, validationScorecards: payload });
+      }
+      return { thresholds, candidates, qualifyingProjectIds: candidates.filter((candidate) => candidate.qualifies).map((candidate) => candidate.projectId), message: "These are calculated LaunchChair validation scores, not a guarantee of market success. Preserve supplied ideas; only explore alternatives when requested." };
+    }
+    const definition = definitions.find(([short]) => name === `launchchair_${short}`);
+    if (!definition) return undefined;
+    const [, , , , method, suffix] = definition;
+    const projectId = await resolveProjectId(args);
+    let endpoint = `/api/agent/v1/projects/${encodeURIComponent(projectId)}${suffix.replace(/:(\w+)/g, (_, key) => {
+      if (!args[key]) throw new Error(`${key} is required.`);
+      return encodeURIComponent(args[key]);
+    })}`;
+    if (name === "launchchair_get_bucket_prompt") {
+      const query = new URLSearchParams();
+      if (args.variant) query.set("variant", args.variant);
+      if (args.campaignId) query.set("campaignId", args.campaignId);
+      if (query.size) endpoint += `?${query}`;
+    }
+    const body = args.payload || Object.fromEntries(Object.entries(args).filter(([key]) => !["projectId", "projectName", ...(name === "launchchair_queue_run" ? [] : ["phaseKey", "bucketKey", "cardId"])].includes(key)));
+    return api(endpoint, method === "GET" ? {} : { method, body });
+  }
+  return { currentToken, dispatch };
+}