@limeadelabs/clarabit-mcp 2.0.0

package/dist/index.js

@@ -0,0 +1,1300 @@
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/client.ts
+var ClarabitError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "ClarabitError";
+  }
+  statusCode;
+};
+var ClarabitClient = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+  }
+  async request(method, path2, body) {
+    const url = `${this.baseUrl}/api/v1${path2}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : void 0,
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!res.ok) {
+      const error = await res.json().catch(() => ({ error: res.statusText }));
+      throw new ClarabitError(
+        `${method} ${path2}: ${res.status} \u2014 ${error.error || res.statusText}`,
+        res.status
+      );
+    }
+    return res.json();
+  }
+  bootstrap() {
+    return this.request("GET", "/agent/bootstrap");
+  }
+  listProjects(params) {
+    const query = params?.stage ? `?stage=${encodeURIComponent(params.stage)}` : "";
+    return this.request("GET", `/projects${query}`);
+  }
+  getProject(id) {
+    return this.request("GET", `/projects/${id}`);
+  }
+  listTasks(params) {
+    const searchParams = new URLSearchParams();
+    if (params.project_id !== void 0) searchParams.set("project_id", String(params.project_id));
+    if (params.status) searchParams.set("status", params.status);
+    if (params.assignee_id !== void 0) searchParams.set("assignee_id", String(params.assignee_id));
+    if (params.priority) searchParams.set("priority", params.priority);
+    if (params.label) searchParams.set("label", params.label);
+    const query = searchParams.toString();
+    return this.request("GET", `/tasks${query ? `?${query}` : ""}`);
+  }
+  getTaskContext(id) {
+    return this.request("GET", `/tasks/${id}/context`);
+  }
+  createTask(data) {
+    return this.request("POST", "/tasks", data);
+  }
+  updateTask(id, data) {
+    return this.request("PATCH", `/tasks/${id}`, data);
+  }
+  claimTask(id) {
+    return this.request("POST", `/tasks/${id}/claim`);
+  }
+  releaseTask(id) {
+    return this.request("POST", `/tasks/${id}/release`);
+  }
+  heartbeat(id) {
+    return this.request("POST", `/tasks/${id}/heartbeat`);
+  }
+  addComment(taskId, body) {
+    return this.request("POST", `/tasks/${taskId}/comments`, { comment: { body } });
+  }
+  generatePrompt(id) {
+    return this.request("POST", `/tasks/${id}/generate_prompt`);
+  }
+  logTime(taskId, durationMinutes, description) {
+    return this.request("POST", `/tasks/${taskId}/time_entries`, {
+      duration_minutes: durationMinutes,
+      ...description !== void 0 && { description }
+    });
+  }
+  listPages(projectId) {
+    return this.request("GET", `/projects/${projectId}/pages`);
+  }
+  getPage(projectId, pageId) {
+    return this.request("GET", `/projects/${projectId}/pages/${pageId}`);
+  }
+  createPage(projectId, title, body) {
+    return this.request("POST", `/projects/${projectId}/pages`, { page: { title, body } });
+  }
+  updatePage(projectId, pageId, updates, changeSummary) {
+    const body = { page: updates };
+    if (changeSummary !== void 0) body.change_summary = changeSummary;
+    return this.request("PATCH", `/projects/${projectId}/pages/${pageId}`, body);
+  }
+  listPageVersions(projectId, pageId) {
+    return this.request(
+      "GET",
+      `/projects/${projectId}/pages/${pageId}/versions`
+    );
+  }
+  getPageVersion(projectId, pageId, versionNumber) {
+    return this.request(
+      "GET",
+      `/projects/${projectId}/pages/${pageId}/versions/${versionNumber}`
+    );
+  }
+  restorePageVersion(projectId, pageId, versionNumber, changeSummary) {
+    const body = changeSummary !== void 0 ? { change_summary: changeSummary } : void 0;
+    return this.request(
+      "POST",
+      `/projects/${projectId}/pages/${pageId}/versions/${versionNumber}/restore`,
+      body
+    );
+  }
+  // Flat (project-id-free) page endpoints — let the server resolve the owning
+  // project via the api key's accessible_pages scope so we don't have to walk
+  // every project to find one. Requires the Rails-side flat routes (LP #575).
+  getPageFlat(pageId) {
+    return this.request("GET", `/pages/${pageId}`);
+  }
+  updatePageFlat(pageId, updates, changeSummary) {
+    const body = { page: updates };
+    if (changeSummary !== void 0) body.change_summary = changeSummary;
+    return this.request("PATCH", `/pages/${pageId}`, body);
+  }
+  listPageVersionsFlat(pageId) {
+    return this.request("GET", `/pages/${pageId}/versions`);
+  }
+  getPageVersionFlat(pageId, versionNumber) {
+    return this.request(
+      "GET",
+      `/pages/${pageId}/versions/${versionNumber}`
+    );
+  }
+  restorePageVersionFlat(pageId, versionNumber, changeSummary) {
+    const body = changeSummary !== void 0 ? { change_summary: changeSummary } : void 0;
+    return this.request(
+      "POST",
+      `/pages/${pageId}/versions/${versionNumber}/restore`,
+      body
+    );
+  }
+  listPageComments(projectId, pageId, opts) {
+    const query = opts?.resolved === void 0 ? "" : `?resolved=${opts.resolved ? "true" : "false"}`;
+    return this.request(
+      "GET",
+      `/projects/${projectId}/pages/${pageId}/comments${query}`
+    );
+  }
+  createPageComment(projectId, pageId, body, opts) {
+    return this.request(
+      "POST",
+      `/projects/${projectId}/pages/${pageId}/comments`,
+      { body, ...opts ?? {} }
+    );
+  }
+  updatePageComment(projectId, pageId, commentId, body) {
+    return this.request(
+      "PATCH",
+      `/projects/${projectId}/pages/${pageId}/comments/${commentId}`,
+      { comment: { body } }
+    );
+  }
+  resolvePageComment(projectId, pageId, commentId) {
+    return this.request(
+      "PATCH",
+      `/projects/${projectId}/pages/${pageId}/comments/${commentId}/resolve`
+    );
+  }
+  unresolvePageComment(projectId, pageId, commentId) {
+    return this.request(
+      "PATCH",
+      `/projects/${projectId}/pages/${pageId}/comments/${commentId}/unresolve`
+    );
+  }
+  getWorkflow(projectId) {
+    return this.request("GET", `/projects/${projectId}/workflow`);
+  }
+  listContextEntries(params) {
+    const searchParams = new URLSearchParams();
+    if (params?.project_id !== void 0) searchParams.set("project_id", String(params.project_id));
+    if (params?.entry_type) searchParams.set("entry_type", params.entry_type);
+    if (params?.search) searchParams.set("search", params.search);
+    if (params?.limit !== void 0) searchParams.set("limit", String(params.limit));
+    if (params?.offset !== void 0) searchParams.set("offset", String(params.offset));
+    const query = searchParams.toString();
+    return this.request("GET", `/contexts${query ? `?${query}` : ""}`);
+  }
+  getContextEntry(identifier) {
+    return this.request("GET", `/contexts/${encodeURIComponent(identifier)}`);
+  }
+  getTaskContextPackage(taskId) {
+    return this.request("GET", `/tasks/${taskId}/context`);
+  }
+  updateContextEntry(identifier, data) {
+    return this.request("PATCH", `/contexts/${encodeURIComponent(identifier)}`, data);
+  }
+  createSession(taskId, agentType, agentId) {
+    return this.request("POST", "/sessions", {
+      task_id: taskId,
+      agent_type: agentType ?? "claude_code",
+      ...agentId !== void 0 && { agent_id: agentId }
+    });
+  }
+  sessionHeartbeat(sessionId) {
+    return this.request("POST", `/sessions/${sessionId}/heartbeat`);
+  }
+  updateSession(sessionId, data) {
+    return this.request("PATCH", `/sessions/${sessionId}`, data);
+  }
+  createSessionEvent(sessionId, eventType, payload) {
+    return this.request("POST", `/sessions/${sessionId}/events`, {
+      event_type: eventType,
+      payload
+    });
+  }
+};
+
+// src/tools/shared.ts
+function handleError(error, timeoutMs2) {
+  const message = error instanceof DOMException && error.name === "TimeoutError" ? `Request timed out after ${timeoutMs2}ms. Clarabit may be slow or unreachable.` : `Error: ${error.message}`;
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+async function resolveProjectIdForPage(client2, pageId) {
+  const projectsResult = await client2.listProjects();
+  const projects = projectsResult.projects ?? [];
+  for (const proj of projects) {
+    try {
+      await client2.getPage(proj.id, pageId);
+      return proj.id;
+    } catch {
+    }
+  }
+  throw new Error(`Page ${pageId} not found in any accessible project`);
+}
+
+// src/tools/bootstrap.ts
+function registerBootstrapTool(server2, client2) {
+  server2.tool(
+    "cla_bootstrap",
+    "One-call onboarding: returns workspace identity, projects, available tasks, and conventions",
+    {},
+    async () => {
+      try {
+        const result = await client2.bootstrap();
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/projects.ts
+import { z } from "zod";
+function registerProjectTools(server2, client2) {
+  server2.tool(
+    "cla_list_projects",
+    "List all accessible Clarabit projects with metadata",
+    {
+      stage: z.string().optional().describe("Filter by stage: idea, greenlit, building, shipped, killed")
+    },
+    async (params) => {
+      try {
+        const result = await client2.listProjects(params.stage ? { stage: params.stage } : void 0);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_get_project",
+    "Get project details including agent_instructions",
+    {
+      project_id: z.coerce.number().describe("Project ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getProject(params.project_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/tasks.ts
+import { z as z2 } from "zod";
+function registerTaskTools(server2, client2) {
+  server2.tool(
+    "cla_list_tasks",
+    "List tasks from Clarabit with optional filters (project, status, priority, label, assignee)",
+    {
+      project_id: z2.coerce.number().optional().describe("Filter by project ID"),
+      status: z2.string().optional().describe("Filter by status: todo, ready, in_progress, review, done"),
+      priority: z2.string().optional().describe("Filter by priority: low, medium, high"),
+      label: z2.string().optional().describe("Filter by label name"),
+      assignee_id: z2.coerce.number().optional().describe("Filter by assignee user ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.listTasks(params);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_get_task",
+    "Get full task context \u2014 description, comments, links, specs",
+    {
+      task_id: z2.coerce.number().describe("Task ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getTaskContext(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_create_task",
+    "Create a new task in Clarabit",
+    {
+      project_id: z2.coerce.number().describe("Project ID to create the task in"),
+      title: z2.string().describe("Task title"),
+      description: z2.string().optional().describe("Task description"),
+      status: z2.string().optional().describe("Initial status: todo, ready, in_progress, review, done"),
+      priority: z2.string().optional().describe("Priority: low, medium, high")
+    },
+    async (params) => {
+      try {
+        const result = await client2.createTask(params);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_update_task",
+    "Update task status and/or fields. Clarabit enforces workflow transitions \u2014 use cla_get_workflow to check valid transitions before changing status.",
+    {
+      task_id: z2.coerce.number().describe("Task ID"),
+      status: z2.string().optional().describe("New status (must be a valid workflow transition)"),
+      priority: z2.string().optional().describe("New priority: low, medium, high"),
+      assignee_id: z2.coerce.number().optional().describe("Assignee user ID"),
+      title: z2.string().optional().describe("New title"),
+      description: z2.string().optional().describe("New description")
+    },
+    async (params) => {
+      try {
+        const { task_id, ...data } = params;
+        const result = await client2.updateTask(task_id, data);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/claims.ts
+import { z as z3 } from "zod";
+function registerClaimTools(server2, client2) {
+  server2.tool(
+    "cla_claim_task",
+    "Claim a task before working on it. Prevents other agents from picking it up.",
+    {
+      task_id: z3.coerce.number().describe("Task ID to claim")
+    },
+    async (params) => {
+      try {
+        const result = await client2.claimTask(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_release_task",
+    "Release a claimed task so others can pick it up",
+    {
+      task_id: z3.coerce.number().describe("Task ID to release")
+    },
+    async (params) => {
+      try {
+        const result = await client2.releaseTask(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_heartbeat",
+    "Send a heartbeat for a claimed task to keep the claim alive. Claims expire after 30 minutes without a heartbeat.",
+    {
+      task_id: z3.coerce.number().describe("Task ID to heartbeat")
+    },
+    async (params) => {
+      try {
+        const result = await client2.heartbeat(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/comments.ts
+import { z as z4 } from "zod";
+function registerCommentTools(server2, client2) {
+  server2.tool(
+    "cla_add_comment",
+    "Post a comment on a task (progress updates, notes, questions)",
+    {
+      task_id: z4.coerce.number().describe("Task ID to comment on"),
+      body: z4.string().describe("Comment body text")
+    },
+    async (params) => {
+      try {
+        const result = await client2.addComment(params.task_id, params.body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/time.ts
+import { z as z5 } from "zod";
+function registerTimeTools(server2, client2) {
+  server2.tool(
+    "cla_log_time",
+    "Track time spent on a task",
+    {
+      task_id: z5.coerce.number().describe("Task ID"),
+      duration_minutes: z5.coerce.number().positive().describe("Duration in minutes"),
+      description: z5.string().optional().describe("Description of work done")
+    },
+    async (params) => {
+      try {
+        const result = await client2.logTime(params.task_id, params.duration_minutes, params.description);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/prompts.ts
+import { z as z6 } from "zod";
+function registerPromptTools(server2, client2) {
+  server2.tool(
+    "cla_generate_prompt",
+    "Generate a build-ready prompt/spec for a task with full context, conventions, and acceptance criteria",
+    {
+      task_id: z6.coerce.number().describe("Task ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.generatePrompt(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/pages.ts
+import { z as z7 } from "zod";
+function registerPageTools(server2, client2) {
+  server2.tool(
+    "cla_list_pages",
+    "List spec/doc pages for a project (titles and IDs only \u2014 use cla_get_page to fetch full content)",
+    {
+      project_id: z7.coerce.number().describe("Project ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.listPages(params.project_id);
+        const pages = result.pages ?? result;
+        const summary = Array.isArray(pages) ? pages.map(({ id, title, project, author, created_at, updated_at }) => ({ id, title, project_id: project?.id, project_name: project?.name, author, created_at, updated_at })) : pages;
+        return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_get_page",
+    "Get a page's full content. Accepts page_id or id. project_id is optional \u2014 if omitted, it will be inferred automatically.",
+    {
+      project_id: z7.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z7.coerce.number().optional().describe("Page ID"),
+      id: z7.coerce.number().optional().describe("Page ID (alias for page_id)")
+    },
+    async (params) => {
+      try {
+        const pageId = params.page_id ?? params.id;
+        if (!pageId) throw new Error("page_id or id is required");
+        const result = params.project_id ? await client2.getPage(params.project_id, pageId) : await client2.getPageFlat(pageId);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_create_page",
+    "Create a new spec/doc page in a Clarabit project",
+    {
+      project_id: z7.coerce.number().describe("Project ID"),
+      title: z7.string().describe("Page title"),
+      body: z7.string().describe("Page body (markdown)")
+    },
+    async (params) => {
+      try {
+        const result = await client2.createPage(params.project_id, params.title, params.body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_update_page",
+    "Update an existing spec/doc page in a Clarabit project. Every MCP edit creates a new PageVersion (no debounce). Optionally pass change_summary to label the snapshot.",
+    {
+      project_id: z7.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z7.coerce.number().describe("Page ID"),
+      title: z7.string().optional().describe("New page title (optional)"),
+      body: z7.string().optional().describe("New page body in markdown (optional)"),
+      change_summary: z7.string().optional().describe("Short note describing why this edit was made (shown in version history)")
+    },
+    async (params) => {
+      try {
+        const updates = {};
+        if (params.title) updates.title = params.title;
+        if (params.body) updates.body = params.body;
+        const result = params.project_id ? await client2.updatePage(params.project_id, params.page_id, updates, params.change_summary) : await client2.updatePageFlat(params.page_id, updates, params.change_summary);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_list_page_versions",
+    "List version history for a page (newest first). Returns version_number, change_summary, user, and created_at \u2014 call cla_get_page_version to read a specific version's body.",
+    {
+      project_id: z7.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z7.coerce.number().describe("Page ID")
+    },
+    async (params) => {
+      try {
+        const result = params.project_id ? await client2.listPageVersions(params.project_id, params.page_id) : await client2.listPageVersionsFlat(params.page_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_get_page_version",
+    "Get the full body and title of a specific historical page version.",
+    {
+      project_id: z7.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z7.coerce.number().describe("Page ID"),
+      version_number: z7.coerce.number().describe("Version number to fetch")
+    },
+    async (params) => {
+      try {
+        const result = params.project_id ? await client2.getPageVersion(params.project_id, params.page_id, params.version_number) : await client2.getPageVersionFlat(params.page_id, params.version_number);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_restore_page_version",
+    "Restore a page to a previous version. The pre-restore content is itself snapshotted as a new version, so restores are reversible.",
+    {
+      project_id: z7.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z7.coerce.number().describe("Page ID"),
+      version_number: z7.coerce.number().describe("Version number to restore from"),
+      change_summary: z7.string().optional().describe("Optional summary for the new snapshot of the pre-restore state")
+    },
+    async (params) => {
+      try {
+        const result = params.project_id ? await client2.restorePageVersion(
+          params.project_id,
+          params.page_id,
+          params.version_number,
+          params.change_summary
+        ) : await client2.restorePageVersionFlat(
+          params.page_id,
+          params.version_number,
+          params.change_summary
+        );
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_get_workflow",
+    "Get valid workflow states and transitions for a project",
+    {
+      project_id: z7.coerce.number().describe("Project ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getWorkflow(params.project_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/page-comments.ts
+import { z as z8 } from "zod";
+function registerPageCommentTools(server2, client2) {
+  server2.tool(
+    "cla_create_page_comment",
+    "Post a comment on a page. Optionally thread under another comment via parent_comment_id, or anchor to a text selection via anchor_text/anchor_start/anchor_end.",
+    {
+      project_id: z8.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z8.coerce.number().describe("Page ID to comment on"),
+      body: z8.string().describe("Comment body (markdown)"),
+      parent_comment_id: z8.coerce.number().optional().describe("Parent comment ID to reply under"),
+      anchor_text: z8.string().optional().describe("Text selection the comment is anchored to"),
+      anchor_start: z8.coerce.number().optional().describe("Character offset where anchor begins"),
+      anchor_end: z8.coerce.number().optional().describe("Character offset where anchor ends"),
+      anchor_version: z8.coerce.number().optional().describe("Page version_number the anchor refers to")
+    },
+    async (params) => {
+      try {
+        const projectId = params.project_id ?? await resolveProjectIdForPage(client2, params.page_id);
+        const result = await client2.createPageComment(projectId, params.page_id, params.body, {
+          parent_comment_id: params.parent_comment_id,
+          anchor_text: params.anchor_text,
+          anchor_start: params.anchor_start,
+          anchor_end: params.anchor_end,
+          anchor_version: params.anchor_version
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_update_page_comment",
+    "Edit the body of your own page comment. Returns 403 if you are not the author \u2014 only the original author can edit comment text.",
+    {
+      project_id: z8.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z8.coerce.number().describe("Page ID the comment lives on"),
+      comment_id: z8.coerce.number().describe("Comment ID to edit"),
+      body: z8.string().describe("New comment body")
+    },
+    async (params) => {
+      try {
+        const projectId = params.project_id ?? await resolveProjectIdForPage(client2, params.page_id);
+        const result = await client2.updatePageComment(
+          projectId,
+          params.page_id,
+          params.comment_id,
+          params.body
+        );
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_resolve_page_comment",
+    "Mark a page comment as resolved. Anyone with project access can resolve a comment (including comments authored by others) \u2014 this is non-destructive.",
+    {
+      project_id: z8.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z8.coerce.number().describe("Page ID the comment lives on"),
+      comment_id: z8.coerce.number().describe("Comment ID to resolve")
+    },
+    async (params) => {
+      try {
+        const projectId = params.project_id ?? await resolveProjectIdForPage(client2, params.page_id);
+        const result = await client2.resolvePageComment(projectId, params.page_id, params.comment_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_unresolve_page_comment",
+    "Reopen a previously resolved page comment. Anyone with project access can unresolve.",
+    {
+      project_id: z8.coerce.number().optional().describe("Project ID (optional \u2014 inferred if omitted)"),
+      page_id: z8.coerce.number().describe("Page ID the comment lives on"),
+      comment_id: z8.coerce.number().describe("Comment ID to unresolve")
+    },
+    async (params) => {
+      try {
+        const projectId = params.project_id ?? await resolveProjectIdForPage(client2, params.page_id);
+        const result = await client2.unresolvePageComment(projectId, params.page_id, params.comment_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/context.ts
+import { z as z9 } from "zod";
+function registerContextTools(server2, client2) {
+  server2.tool(
+    "cla_context_list",
+    "List available context entries with optional filters",
+    {
+      project_id: z9.coerce.number().optional().describe("Filter by project ID"),
+      entry_type: z9.string().optional().describe("Filter by entry type"),
+      search: z9.string().optional().describe("Text search on entry name"),
+      limit: z9.coerce.number().min(1).max(100).optional().describe("Max entries to return (default 50)"),
+      offset: z9.coerce.number().min(0).optional().describe("Offset for pagination")
+    },
+    async (params) => {
+      try {
+        const result = await client2.listContextEntries(params);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_context_get",
+    "Fetch a specific context entry by slug or ID",
+    {
+      slug: z9.string().optional().describe("Entry slug"),
+      id: z9.coerce.number().optional().describe("Entry ID")
+    },
+    async (params) => {
+      const identifier = params.slug || (params.id !== void 0 ? String(params.id) : void 0);
+      if (!identifier) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: true, code: "validation_error", message: "Either slug or id is required" }) }],
+          isError: true
+        };
+      }
+      try {
+        const result = await client2.getContextEntry(identifier);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_context_package",
+    "Get the assembled context package for a task \u2014 task details, context entries, specs, pages, comments",
+    {
+      task_id: z9.coerce.number().describe("Task ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getTaskContextPackage(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_context_update",
+    "Update a context entry's content (requires write access)",
+    {
+      slug: z9.string().optional().describe("Entry slug"),
+      id: z9.coerce.number().optional().describe("Entry ID"),
+      content: z9.string().describe("New markdown content"),
+      change_summary: z9.string().describe("What changed and why")
+    },
+    async (params) => {
+      const identifier = params.slug || (params.id !== void 0 ? String(params.id) : void 0);
+      if (!identifier) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: true, code: "validation_error", message: "Either slug or id is required" }) }],
+          isError: true
+        };
+      }
+      try {
+        const result = await client2.updateContextEntry(identifier, {
+          content: params.content,
+          change_summary: params.change_summary
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/sessions.ts
+import { z as z10 } from "zod";
+
+// src/session-store.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var SESSION_FILE = path.join(os.homedir(), ".clarabit", "active-session.json");
+function saveSession(taskId, sessionId) {
+  const dir = path.dirname(SESSION_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const data = fs.existsSync(SESSION_FILE) ? JSON.parse(fs.readFileSync(SESSION_FILE, "utf8")) : {};
+  data[String(taskId)] = sessionId;
+  fs.writeFileSync(SESSION_FILE, JSON.stringify(data, null, 2));
+}
+function getSessionId(taskId) {
+  if (!fs.existsSync(SESSION_FILE)) return null;
+  const data = JSON.parse(fs.readFileSync(SESSION_FILE, "utf8"));
+  return data[String(taskId)] ?? null;
+}
+function clearSession(taskId) {
+  if (!fs.existsSync(SESSION_FILE)) return;
+  const data = JSON.parse(fs.readFileSync(SESSION_FILE, "utf8"));
+  delete data[String(taskId)];
+  fs.writeFileSync(SESSION_FILE, JSON.stringify(data, null, 2));
+}
+
+// src/tools/sessions.ts
+function registerSessionTools(server2, client2) {
+  server2.tool(
+    "cla_session_start",
+    "Start a new agent session for a task. Creates session via API and saves session_id to disk for later lookup.",
+    {
+      task_id: z10.coerce.number().describe("Clarabit task ID"),
+      agent_type: z10.string().optional().describe("Agent type (default: claude_code)")
+    },
+    async ({ task_id, agent_type }) => {
+      try {
+        const result = await client2.createSession(task_id, agent_type);
+        saveSession(task_id, result.session.id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_session_heartbeat",
+    "Send a heartbeat for an active session. Provide session_id directly or task_id to look up session from disk. Graceful no-op if neither provided.",
+    {
+      session_id: z10.coerce.number().optional().describe("Session ID"),
+      task_id: z10.coerce.number().optional().describe("Task ID to look up session from disk")
+    },
+    async ({ session_id, task_id }) => {
+      try {
+        const resolvedId = session_id ?? (task_id !== void 0 ? getSessionId(task_id) : null);
+        if (resolvedId === null) {
+          return {
+            content: [{ type: "text", text: "No active session found. Provide session_id or task_id." }]
+          };
+        }
+        const result = await client2.sessionHeartbeat(resolvedId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_session_progress",
+    "Report progress on an active session. Provide session_id directly or task_id to look up session from disk.",
+    {
+      session_id: z10.coerce.number().optional().describe("Session ID"),
+      task_id: z10.coerce.number().optional().describe("Task ID to look up session from disk"),
+      message: z10.string().optional().describe("Progress message (use this)"),
+      detail: z10.string().optional().describe("Progress message (alias for message)")
+    },
+    async ({ session_id, task_id, message, detail }) => {
+      try {
+        const resolvedId = session_id ?? (task_id !== void 0 ? getSessionId(task_id) : null);
+        if (resolvedId === null) {
+          return { content: [{ type: "text", text: "No active session found. Provide session_id or task_id." }] };
+        }
+        const text = message ?? detail;
+        if (!text) return { content: [{ type: "text", text: "message or detail is required" }] };
+        const result = await client2.updateSession(resolvedId, {
+          activity: { action: "progress", detail: text }
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_session_event",
+    "Log a discrete event for a session (commit, ci_pass, ci_fail, pr_opened, blocker, cost_update). Provide session_id or task_id.",
+    {
+      session_id: z10.coerce.number().optional().describe("Session ID"),
+      task_id: z10.coerce.number().optional().describe("Task ID to look up session from disk"),
+      event_type: z10.enum(["commit", "ci_pass", "ci_fail", "pr_opened", "blocker", "cost_update"]).describe("Type of event"),
+      payload: z10.record(z10.unknown()).describe("Event payload data")
+    },
+    async ({ session_id, task_id, event_type, payload }) => {
+      try {
+        const resolvedId = session_id ?? (task_id !== void 0 ? getSessionId(task_id) : null);
+        if (resolvedId === null) {
+          return { content: [{ type: "text", text: "No active session found. Provide session_id or task_id." }] };
+        }
+        const result = await client2.createSessionEvent(resolvedId, event_type, payload);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_session_blocked",
+    'Mark a session as blocked. Updates status to "blocked" and logs a blocker event. Provide session_id or task_id.',
+    {
+      session_id: z10.coerce.number().optional().describe("Session ID"),
+      task_id: z10.coerce.number().optional().describe("Task ID to look up session from disk"),
+      reason: z10.string().describe("Reason the session is blocked")
+    },
+    async ({ session_id, task_id, reason }) => {
+      try {
+        const resolvedId = session_id ?? (task_id !== void 0 ? getSessionId(task_id) : null);
+        if (resolvedId === null) {
+          return { content: [{ type: "text", text: "No active session found. Provide session_id or task_id." }] };
+        }
+        const [sessionResult, eventResult] = await Promise.all([
+          client2.updateSession(resolvedId, { status: "blocked" }),
+          client2.createSessionEvent(resolvedId, "blocker", { reason })
+        ]);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({ session: sessionResult.session, event: eventResult.event }, null, 2)
+          }]
+        };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_session_complete",
+    "Mark a session as completed with a result summary. Clears session from disk.",
+    {
+      session_id: z10.coerce.number().describe("Session ID"),
+      result_summary: z10.string().describe("Summary of what was accomplished"),
+      task_id: z10.coerce.number().optional().describe("Task ID to clear from disk (if not provided, derived from session)")
+    },
+    async ({ session_id, result_summary, task_id }) => {
+      try {
+        const result = await client2.updateSession(session_id, {
+          status: "completed",
+          result_summary
+        });
+        const resolvedTaskId = task_id ?? result.session.task_id;
+        clearSession(resolvedTaskId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_session_fail",
+    "Mark a session as failed with an error detail. Clears session from disk.",
+    {
+      session_id: z10.coerce.number().describe("Session ID"),
+      error_detail: z10.string().describe("Description of the failure"),
+      task_id: z10.coerce.number().optional().describe("Task ID to clear from disk (if not provided, derived from session)")
+    },
+    async ({ session_id, error_detail, task_id }) => {
+      try {
+        const result = await client2.updateSession(session_id, {
+          status: "failed",
+          result_summary: error_detail
+        });
+        const resolvedTaskId = task_id ?? result.session.task_id;
+        clearSession(resolvedTaskId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/resources/project-context.ts
+function registerProjectContextResource(server2, client2) {
+  server2.resource(
+    "project-context",
+    "clarabit://project/{project_id}/context",
+    {
+      description: "Project agent_instructions, conventions, and active spec summaries"
+    },
+    async (uri) => {
+      const match = uri.pathname.match(/^\/\/project\/(\d+)\/context$/);
+      if (!match) {
+        throw new Error(`Invalid URI: ${uri.href}`);
+      }
+      const projectId = parseInt(match[1], 10);
+      const project = await client2.getProject(projectId);
+      const pages = await client2.listPages(projectId);
+      const parts = [];
+      parts.push(`# ${project.project.name}`);
+      if (project.project.description) {
+        parts.push(`
+${project.project.description}`);
+      }
+      if (project.project.agent_instructions) {
+        parts.push(`
+## Agent Instructions
+
+${project.project.agent_instructions}`);
+      }
+      if (pages.pages.length > 0) {
+        parts.push(`
+## Pages
+`);
+        for (const page of pages.pages) {
+          parts.push(`- **${page.title}** (updated ${page.updated_at})`);
+        }
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: parts.join("\n")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/resources/task-spec.ts
+function registerTaskSpecResource(server2, client2) {
+  server2.resource(
+    "task-spec",
+    "clarabit://task/{task_id}/spec",
+    {
+      description: "Full task spec generated by Clarabit"
+    },
+    async (uri) => {
+      const match = uri.pathname.match(/^\/\/task\/(\d+)\/spec$/);
+      if (!match) {
+        throw new Error(`Invalid URI: ${uri.href}`);
+      }
+      const taskId = parseInt(match[1], 10);
+      const result = await client2.generatePrompt(taskId);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: result.prompt
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/resources/context-entries.ts
+function registerContextEntriesResource(server2, client2) {
+  server2.resource(
+    "context-entries",
+    "context://entries",
+    {
+      description: "Browse all active context entries"
+    },
+    async (uri) => {
+      const result = await client2.listContextEntries();
+      const lines = ["# Context Entries\n"];
+      for (const entry of result.entries) {
+        const project = entry.project ? ` (${entry.project.name})` : "";
+        lines.push(`- **${entry.name}**${project} \u2014 \`${entry.slug}\` [${entry.entry_type}] (v${entry.version_count}, updated ${entry.updated_at})`);
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: lines.join("\n")
+          }
+        ]
+      };
+    }
+  );
+  server2.resource(
+    "context-entry",
+    "context://entries/{slug}",
+    {
+      description: "Read a specific context entry by slug"
+    },
+    async (uri) => {
+      if (uri.host !== "entries" || !uri.pathname || uri.pathname === "/") {
+        throw new Error(`Invalid URI: ${uri.href}`);
+      }
+      const slug = decodeURIComponent(uri.pathname.slice(1));
+      if (!slug) throw new Error("Empty slug in context entry URI");
+      const result = await client2.getContextEntry(slug);
+      const entry = result.entry;
+      const text = [
+        `# ${entry.name}`,
+        ``,
+        `- **Type:** ${entry.entry_type}`,
+        `- **Slug:** ${entry.slug}`,
+        `- **Version:** ${entry.version}`,
+        `- **Updated:** ${entry.updated_at}`,
+        entry.project ? `- **Project:** ${entry.project.name}` : null,
+        ``,
+        `---`,
+        ``,
+        entry.content
+      ].filter(Boolean).join("\n");
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/prompts/start-task.ts
+import { z as z11 } from "zod";
+function registerStartTaskPrompt(server2) {
+  server2.prompt(
+    "cla_start_task",
+    "Guided workflow: find a task, claim it, get context, start working",
+    {
+      project_id: z11.string().optional().describe("Optional project ID to filter tasks")
+    },
+    async (args) => {
+      const projectLine = args.project_id ? ` Project ID: ${args.project_id}.` : "";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `I want to start working on a Clarabit task.${projectLine}
+
+Please:
+1. Call cla_bootstrap to see available projects and tasks
+2. Show me the available tasks (status: ready) and let me pick one
+3. Once I pick a task, call cla_claim_task to claim it
+4. Call cla_get_task to get the full context
+5. Call cla_generate_prompt to get the build spec
+6. Present the spec and let's start building
+
+IMPORTANT: If this task takes more than 20 minutes, call cla_heartbeat every 20 minutes to keep the claim alive. Claims expire after 30 minutes without a heartbeat.`
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/prompts/submit-task.ts
+import { z as z12 } from "zod";
+function registerSubmitTaskPrompt(server2) {
+  server2.prompt(
+    "cla_submit_task",
+    "Guided workflow: mark task done, add summary comment, release claim",
+    {
+      task_id: z12.string().describe("Task ID to submit"),
+      summary: z12.string().describe("Summary of what was completed")
+    },
+    async (args) => {
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `I've finished working on Clarabit task #${args.task_id}.
+
+Summary of what was done: ${args.summary}
+
+Please:
+1. Call cla_add_comment with a summary of what was completed
+2. Call cla_update_task to move the task to "review" status (check cla_get_workflow first to confirm valid transitions)
+3. Call cla_release_task to release the claim
+4. Confirm everything is done`
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/index.ts
+function readEnvVar(newName, oldName) {
+  const newVal = process.env[newName];
+  if (newVal !== void 0) return newVal;
+  const oldVal = process.env[oldName];
+  if (oldVal !== void 0) {
+    console.error(`Warning: ${oldName} is deprecated; please rename it to ${newName}. (Old name will be removed in a future release.)`);
+    return oldVal;
+  }
+  return void 0;
+}
+var apiKey = readEnvVar("CLARABIT_API_KEY", "LAUNCHPAD_API_KEY");
+if (!apiKey) {
+  console.error("Error: CLARABIT_API_KEY environment variable is required.");
+  console.error("Get an API key from your Clarabit workspace settings.");
+  process.exit(1);
+}
+var baseUrl = readEnvVar("CLARABIT_URL", "LAUNCHPAD_URL") || "https://app.clarabit.ai";
+var timeoutMs = parseInt(readEnvVar("CLARABIT_TIMEOUT_MS", "LAUNCHPAD_TIMEOUT_MS") || "10000", 10);
+var client = new ClarabitClient({ baseUrl, apiKey, timeoutMs });
+try {
+  const bootstrap = await client.bootstrap();
+  console.error(`Clarabit MCP: Connected as "${bootstrap.agent?.name}" (${bootstrap.projects?.length || 0} projects)`);
+} catch (err) {
+  if (err instanceof ClarabitError && err.statusCode === 401) {
+    console.error("Error: Invalid CLARABIT_API_KEY. Get a valid key from Clarabit workspace settings.");
+  } else {
+    console.error(`Error: Cannot reach Clarabit at ${baseUrl}. Check CLARABIT_URL. (${err.message})`);
+  }
+  process.exit(1);
+}
+var server = new McpServer({
+  name: "clarabit",
+  version: "2.0.0"
+});
+registerBootstrapTool(server, client);
+registerProjectTools(server, client);
+registerTaskTools(server, client);
+registerClaimTools(server, client);
+registerCommentTools(server, client);
+registerTimeTools(server, client);
+registerPromptTools(server, client);
+registerPageTools(server, client);
+registerPageCommentTools(server, client);
+registerContextTools(server, client);
+registerSessionTools(server, client);
+registerProjectContextResource(server, client);
+registerTaskSpecResource(server, client);
+registerContextEntriesResource(server, client);
+registerStartTaskPrompt(server);
+registerSubmitTaskPrompt(server);
+var transport = new StdioServerTransport();
+await server.connect(transport);