@launchchair/agent 0.4.11 → 0.5.0

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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchchair/agent",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "mcpName": "io.launchchair/agent",
   "description": "LaunchChair Agent CLI, MCP bridge, local bridge, and runners for Codex, Claude Code, ChatGPT, Claude, and Hermes workflows.",
   "type": "module",
@@ -15,6 +15,8 @@
     "launchchair-cli.mjs",
     "local-bridge.mjs",
     "mcp-bridge-server.mjs",
+    "mcp-capabilities.mjs",
+    "project-workspace.mjs",
     "runner-command.mjs",
     "codex-runner.mjs",
     "claude-code-runner.mjs",

package/project-workspace.mjs

@@ -0,0 +1,309 @@
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function text(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function readConfig(configPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    return asRecord(parsed);
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(configPath, next) {
+  const directory = path.dirname(configPath);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const temporary = path.join(directory, `.${path.basename(configPath)}.${process.pid}.${Date.now()}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, configPath);
+    try {
+      chmodSync(configPath, 0o600);
+    } catch {
+      // Best effort for filesystems without POSIX permissions.
+    }
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+function safeProjectKey(projectId) {
+  const value = text(projectId);
+  if (!value) throw new Error("LaunchChair projectId is required to resolve a local workspace.");
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 160);
+}
+
+export function normalizeGitRemote(value) {
+  let remote = text(value);
+  if (!remote) return "";
+  if (remote.startsWith("git@")) {
+    const match = remote.match(/^git@([^:]+):(.+)$/);
+    if (match) remote = `https://${match[1]}/${match[2]}`;
+  } else if (remote.startsWith("ssh://git@")) {
+    remote = remote.replace(/^ssh:\/\/git@/, "https://");
+  }
+  try {
+    const parsed = new URL(remote);
+    const pathname = parsed.pathname.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "");
+    return `${parsed.hostname.toLowerCase()}/${pathname.toLowerCase()}`;
+  } catch {
+    return remote.replace(/\.git$/i, "").replace(/\/+$/, "").toLowerCase();
+  }
+}
+
+export function repositoryNameFromUrl(value) {
+  const normalized = normalizeGitRemote(value);
+  return normalized.split("/").filter(Boolean).at(-1) ?? "";
+}
+
+function gitDirectory(repoPath) {
+  const dotGit = path.join(repoPath, ".git");
+  if (!existsSync(dotGit)) return "";
+  try {
+    if (statSync(dotGit).isDirectory()) return dotGit;
+    const pointer = readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/im)?.[1]?.trim();
+    if (!pointer) return "";
+    return path.resolve(repoPath, pointer);
+  } catch {
+    return "";
+  }
+}
+
+export function readGitOrigin(repoPath) {
+  const gitDir = gitDirectory(repoPath);
+  if (!gitDir) return "";
+  try {
+    // Linked worktrees keep remote configuration in their common Git directory.
+    const commonPointer = path.join(gitDir, "commondir");
+    const commonDir = existsSync(commonPointer) ? path.resolve(gitDir, readFileSync(commonPointer, "utf8").trim()) : gitDir;
+    const raw = readFileSync(path.join(commonDir, "config"), "utf8");
+    const remoteBlock = raw.match(/\[remote\s+"origin"\]([\s\S]*?)(?=\n\[|$)/i)?.[1] ?? "";
+    return remoteBlock.match(/^\s*url\s*=\s*(.+)$/im)?.[1]?.trim() ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function projectBindings(config) {
+  return asRecord(config.projectWorkspaces);
+}
+
+function bindingPath(config, projectId) {
+  const value = projectBindings(config)[projectId];
+  if (typeof value === "string") return text(value);
+  return text(asRecord(value).path);
+}
+
+function repositoryMatches(repoPath, expectedRepositoryUrl) {
+  const origin = readGitOrigin(repoPath);
+  if (!origin) return false;
+  const expected = normalizeGitRemote(expectedRepositoryUrl);
+  return !expected || normalizeGitRemote(origin) === expected;
+}
+
+function standardSearchRoots(config, legacyPaths = [], extraRoots = []) {
+  const home = os.homedir();
+  const configuredRoots = Array.isArray(config.repoSearchRoots) ? config.repoSearchRoots.map(text) : [];
+  const bindingParents = Object.values(projectBindings(config))
+    .map((value) => (typeof value === "string" ? value : asRecord(value).path))
+    .map(text)
+    .filter(Boolean)
+    .map((value) => path.dirname(path.resolve(value)));
+  const legacyParents = legacyPaths.map(text).filter(Boolean).map((value) => path.dirname(path.resolve(value)));
+  const legacyRoots = legacyPaths.map(text).filter(Boolean).map((value) => path.resolve(value));
+  return Array.from(
+    new Set(
+      [
+        ...extraRoots,
+        ...configuredRoots,
+        ...bindingParents,
+        ...legacyRoots,
+        ...legacyParents,
+        home ? path.join(home, "Documents", "GitHub") : "",
+        home ? path.join(home, "Developer") : "",
+        home ? path.join(home, "Projects") : "",
+        home ? path.join(home, "repos") : "",
+      ]
+        .map(text)
+        .filter(Boolean)
+        .map((value) => path.resolve(value)),
+    ),
+  );
+}
+
+function saveBinding(configPath, projectId, repoPath, repositoryUrl, source) {
+  const config = readConfig(configPath);
+  const bindings = projectBindings(config);
+  const next = {
+    ...config,
+    projectWorkspaces: {
+      ...bindings,
+      [projectId]: {
+        path: path.resolve(repoPath),
+        repositoryUrl: text(repositoryUrl) || text(asRecord(bindings[projectId]).repositoryUrl) || undefined,
+        source,
+        updatedAt: new Date().toISOString(),
+      },
+    },
+  };
+  writeConfig(configPath, next);
+  return next.projectWorkspaces[projectId];
+}
+
+export function bindProjectWorkspace({ configPath, projectId, cwd, repositoryUrl = "", source = "explicit" }) {
+  const id = text(projectId);
+  safeProjectKey(id);
+  const resolved = path.resolve(text(cwd));
+  if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+    throw new Error(`Local project directory does not exist: ${resolved}`);
+  }
+  const expected = text(repositoryUrl);
+  const origin = readGitOrigin(resolved);
+  if (expected && !origin) {
+    throw new Error(`The selected directory is not a Git clone. Expected ${expected}.`);
+  }
+  if (expected && normalizeGitRemote(origin) !== normalizeGitRemote(expected)) {
+    throw new Error(`Git origin mismatch. Expected ${expected}, found ${origin || "no origin"}.`);
+  }
+  return saveBinding(configPath, id, resolved, expected || origin, source);
+}
+
+export function unbindProjectWorkspace({ configPath, projectId }) {
+  const id = text(projectId);
+  safeProjectKey(id);
+  const config = readConfig(configPath);
+  const bindings = { ...projectBindings(config) };
+  const existed = Object.prototype.hasOwnProperty.call(bindings, id);
+  delete bindings[id];
+  writeConfig(configPath, { ...config, projectWorkspaces: bindings });
+  return existed;
+}
+
+export function listProjectWorkspaceBindings(configPath) {
+  return projectBindings(readConfig(configPath));
+}
+
+export function isolatedProjectWorkspace(configDir, projectId) {
+  const key = safeProjectKey(projectId);
+  const target = path.join(configDir, "projects", key, "workspace");
+  mkdirSync(target, { recursive: true, mode: 0o700 });
+  const instructionsPath = path.join(target, "AGENTS.md");
+  if (!existsSync(instructionsPath)) {
+    writeFileSync(
+      instructionsPath,
+      [
+        "# LaunchChair isolated project workspace",
+        "",
+        `This folder belongs only to LaunchChair project ${projectId}.`,
+        "Use the LaunchChair prompt and MCP/API context for pre-code work.",
+        "Do not inspect, edit, or execute against unrelated repositories.",
+        "Before code-changing work, bind a verified local Git clone with `launchchair bind --project-id <id> --cwd <path>`.",
+        "",
+      ].join("\n"),
+      { mode: 0o600 },
+    );
+  }
+  return target;
+}
+
+export function resolveProjectWorkspace({
+  configDir,
+  configPath,
+  projectId,
+  repository = {},
+  requireRepository = false,
+  preferRepository = false,
+  legacyPaths = [],
+  searchRoots = [],
+}) {
+  const id = text(projectId);
+  safeProjectKey(id);
+  const config = readConfig(configPath);
+  const repo = asRecord(repository);
+  const repositoryUrl = text(repo.repoUrl) || text(repo.cloneUrl);
+  const cloneUrl = text(repo.cloneUrl) || repositoryUrl;
+  const repoName = text(repo.repoName) || repositoryNameFromUrl(repositoryUrl);
+  const boundPath = bindingPath(config, id);
+  const scratchPath = isolatedProjectWorkspace(configDir, id);
+
+  if (!requireRepository && !preferRepository) {
+    return {
+      path: scratchPath,
+      source: "isolated",
+      repositoryVerified: false,
+      repositoryUrl,
+      cloneUrl,
+    };
+  }
+
+  if (!repositoryUrl) {
+    if (requireRepository) {
+      throw new Error(
+        `LaunchChair project ${id} does not have repository metadata yet. Finish Stack Setup before running code-changing work.`,
+      );
+    }
+    return {
+      path: scratchPath,
+      source: "isolated",
+      repositoryVerified: false,
+      repositoryUrl: "",
+      cloneUrl: "",
+    };
+  }
+
+  const candidates = [boundPath, scratchPath, ...legacyPaths.map(text).filter(Boolean)];
+
+  if (repoName) {
+    for (const root of standardSearchRoots(config, legacyPaths, searchRoots)) {
+      candidates.push(path.join(root, repoName));
+    }
+  }
+
+  for (const candidate of Array.from(new Set(candidates.filter(Boolean).map((value) => path.resolve(value))))) {
+    if (!existsSync(candidate)) continue;
+    if (!repositoryMatches(candidate, repositoryUrl)) continue;
+    const source = candidate === boundPath ? "binding" : "auto_detected";
+    if (candidate !== boundPath) saveBinding(configPath, id, candidate, repositoryUrl || readGitOrigin(candidate), source);
+    return {
+      path: candidate,
+      source,
+      repositoryVerified: true,
+      repositoryUrl: repositoryUrl || readGitOrigin(candidate),
+      cloneUrl,
+    };
+  }
+
+  if (requireRepository) {
+    const expected = repositoryUrl ? ` for ${repositoryUrl}` : "";
+    const cloneStep = cloneUrl && repoName ? ` Clone it with: git clone ${cloneUrl} \"${repoName}\".` : "";
+    throw new Error(
+      `No verified local Git clone is bound to LaunchChair project ${id}${expected}.${cloneStep} Then run: launchchair bind --project-id ${id} --cwd \"/absolute/path/to/${repoName || "repo"}\"`,
+    );
+  }
+
+  return {
+    path: scratchPath,
+    source: "isolated",
+    repositoryVerified: false,
+    repositoryUrl,
+    cloneUrl,
+  };
+}

package/server.json

@@ -3,13 +3,13 @@
   "name": "io.launchchair/agent",
   "title": "LaunchChair",
   "description": "Plan, validate, and build products and features with LaunchChair.",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "websiteUrl": "https://www.launchchair.io/docs/mcp",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@launchchair/agent",
-      "version": "0.4.11",
+      "version": "0.5.0",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {
@@ -29,8 +29,8 @@
       "environmentVariables": [
         {
           "name": "LAUNCHCHAIR_AGENT_TOKEN",
-          "description": "LaunchChair Agent API token from Settings > API Access.",
-          "isRequired": true,
+          "description": "Optional pre-existing token. Without it, call launchchair_login for browser approval and private token storage.",
+          "isRequired": false,
           "isSecret": true,
           "format": "string"
         }