@limeadelabs/clarabit-mcp 2.1.0 → 2.3.0

package/dist/index.js

@@ -99,9 +99,10 @@ var ClarabitClient = class {
   createPage(projectId, title, body) {
     return this.request("POST", `/projects/${projectId}/pages`, { page: { title, body } });
   }
-  updatePage(projectId, pageId, updates, changeSummary) {
+  updatePage(projectId, pageId, updates, changeSummary, verbose) {
     const body = { page: updates };
     if (changeSummary !== void 0) body.change_summary = changeSummary;
+    if (verbose !== void 0) body.verbose = verbose;
     return this.request("PATCH", `/projects/${projectId}/pages/${pageId}`, body);
   }
   listPageVersions(projectId, pageId) {
@@ -130,9 +131,10 @@ var ClarabitClient = class {
   getPageFlat(pageId) {
     return this.request("GET", `/pages/${pageId}`);
   }
-  updatePageFlat(pageId, updates, changeSummary) {
+  updatePageFlat(pageId, updates, changeSummary, verbose) {
     const body = { page: updates };
     if (changeSummary !== void 0) body.change_summary = changeSummary;
+    if (verbose !== void 0) body.verbose = verbose;
     return this.request("PATCH", `/pages/${pageId}`, body);
   }
   listPageVersionsFlat(pageId) {
@@ -159,6 +161,13 @@ var ClarabitClient = class {
       `/projects/${projectId}/pages/${pageId}/comments${query}`
     );
   }
+  listPageCommentsFlat(pageId, opts) {
+    const query = opts?.resolved === void 0 ? "" : `?resolved=${opts.resolved ? "true" : "false"}`;
+    return this.request(
+      "GET",
+      `/pages/${pageId}/comments${query}`
+    );
+  }
   createPageComment(projectId, pageId, body, opts) {
     return this.request(
       "POST",
@@ -551,20 +560,21 @@ function registerPageTools(server2, client2) {
   );
   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.",
+    "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. Returns a minimal confirmation by default (id, title, version_number, change_summary) \u2014 pass verbose: true if you actually need the full body back (rare; the agent typically just sent it).",
     {
       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)")
+      change_summary: z7.string().optional().describe("Short note describing why this edit was made (shown in version history)"),
+      verbose: z7.boolean().optional().describe("Return the full page (including body) in the response. Default false \u2014 saves round-trip cost on long pages.")
     },
     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);
+        const result = params.project_id ? await client2.updatePage(params.project_id, params.page_id, updates, params.change_summary, params.verbose) : await client2.updatePageFlat(params.page_id, updates, params.change_summary, params.verbose);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (error) {
         return handleError(error, client2.timeoutMs);
@@ -650,10 +660,237 @@ function registerPageTools(server2, client2) {
 
 // src/tools/page-comments.ts
 import { z as z8 } from "zod";
+
+// src/tools/anchor.ts
+var PREVIEW = 40;
+function computeAnchor(body, versionNumber, input) {
+  if (input.prefix !== void 0 && input.text !== void 0 && input.suffix !== void 0) {
+    return anchorWithContext(body, versionNumber, input.prefix, input.text, input.suffix);
+  }
+  if (input.heading !== void 0 && input.text !== void 0) {
+    return anchorInSection(body, versionNumber, input.heading, input.text);
+  }
+  if (input.exact_text !== void 0) {
+    return anchorExact(body, versionNumber, input.exact_text);
+  }
+  return {
+    error: "invalid_input",
+    hint: "Provide one of: exact_text, prefix+text+suffix, or heading+text"
+  };
+}
+function anchorExact(body, version, text) {
+  if (text.length === 0) {
+    return { error: "invalid_input", hint: "exact_text must be non-empty" };
+  }
+  const indices = findAll(body, text);
+  if (indices.length === 0) {
+    return { error: "no_match", hint: `exact_text not found in page body` };
+  }
+  if (indices.length > 1) {
+    return {
+      error: "ambiguous_anchor",
+      match_count: indices.length,
+      matches: indices.slice(0, 10).map((start) => ({
+        anchor_start: start,
+        anchor_end: start + text.length,
+        preview_before: body.slice(Math.max(0, start - PREVIEW), start),
+        preview_after: body.slice(
+          start + text.length,
+          Math.min(body.length, start + text.length + PREVIEW)
+        )
+      })),
+      hint: "Provide prefix/suffix or heading context to disambiguate."
+    };
+  }
+  return success(body, text, indices[0], version, "medium");
+}
+function anchorWithContext(body, version, prefix, text, suffix) {
+  if (text.length === 0) {
+    return { error: "invalid_input", hint: "text must be non-empty" };
+  }
+  const composite = prefix + text + suffix;
+  const indices = findAll(body, composite);
+  if (indices.length === 0) {
+    return {
+      error: "no_match",
+      hint: "prefix+text+suffix not found verbatim \u2014 try a shorter / different context"
+    };
+  }
+  if (indices.length > 1) {
+    return {
+      error: "ambiguous_anchor",
+      match_count: indices.length,
+      matches: indices.slice(0, 10).map((start2) => {
+        const ts = start2 + prefix.length;
+        return {
+          anchor_start: ts,
+          anchor_end: ts + text.length,
+          preview_before: body.slice(Math.max(0, ts - PREVIEW), ts),
+          preview_after: body.slice(ts + text.length, Math.min(body.length, ts + text.length + PREVIEW))
+        };
+      }),
+      hint: "prefix+text+suffix still has multiple matches; widen the surrounding context."
+    };
+  }
+  const start = indices[0] + prefix.length;
+  return success(body, text, start, version, "high");
+}
+function anchorInSection(body, version, heading, text) {
+  if (text.length === 0) {
+    return { error: "invalid_input", hint: "text must be non-empty" };
+  }
+  const sections = findSections(body, heading);
+  if (sections.length === 0) {
+    return { error: "no_match", hint: `heading "${heading}" not found in page body` };
+  }
+  if (sections.length > 1) {
+    return {
+      error: "ambiguous_anchor",
+      match_count: sections.length,
+      matches: sections.slice(0, 10).map((s) => ({
+        anchor_start: s.headingStart,
+        anchor_end: s.headingEnd,
+        preview_before: body.slice(Math.max(0, s.headingStart - PREVIEW), s.headingStart),
+        preview_after: body.slice(s.headingEnd, Math.min(body.length, s.headingEnd + PREVIEW))
+      })),
+      hint: `heading "${heading}" matches ${sections.length} sections; pass the exact heading title to disambiguate.`
+    };
+  }
+  const section = sections[0];
+  const sectionBody = body.slice(section.start, section.end);
+  const indicesInSection = findAll(sectionBody, text);
+  if (indicesInSection.length === 0) {
+    return { error: "no_match", hint: `text not found under heading "${heading}"` };
+  }
+  if (indicesInSection.length > 1) {
+    return {
+      error: "ambiguous_anchor",
+      match_count: indicesInSection.length,
+      matches: indicesInSection.slice(0, 10).map((local) => {
+        const start2 = section.start + local;
+        return {
+          anchor_start: start2,
+          anchor_end: start2 + text.length,
+          preview_before: body.slice(Math.max(0, start2 - PREVIEW), start2),
+          preview_after: body.slice(start2 + text.length, Math.min(body.length, start2 + text.length + PREVIEW))
+        };
+      }),
+      hint: `text appears multiple times under heading "${heading}"; use prefix+text+suffix instead.`
+    };
+  }
+  const start = section.start + indicesInSection[0];
+  return success(body, text, start, version, "high");
+}
+function findAll(body, needle) {
+  const out = [];
+  let i = body.indexOf(needle);
+  while (i !== -1) {
+    out.push(i);
+    i = body.indexOf(needle, i + 1);
+  }
+  return out;
+}
+function findSections(body, heading) {
+  const headingRe = /^(#{1,6})\s+(.+?)\s*$/gm;
+  const wanted = heading.replace(/^#+\s*/, "").trim();
+  const headings = [];
+  let match;
+  while ((match = headingRe.exec(body)) !== null) {
+    headings.push({
+      level: match[1].length,
+      title: match[2].trim(),
+      headingStart: match.index,
+      bodyStart: match.index + match[0].length
+    });
+  }
+  const exact = headings.filter((h) => h.title === wanted);
+  const candidates = exact.length > 0 ? exact : headings.filter((h) => h.title.includes(wanted));
+  return candidates.map((h) => {
+    const myIndex = headings.indexOf(h);
+    let end = body.length;
+    for (let j = myIndex + 1; j < headings.length; j++) {
+      if (headings[j].level <= h.level) {
+        end = headings[j].headingStart;
+        break;
+      }
+    }
+    return { start: h.bodyStart, end, headingStart: h.headingStart, headingEnd: h.bodyStart };
+  });
+}
+function success(body, text, start, version, confidence) {
+  const end = start + text.length;
+  return {
+    anchor_text: text,
+    anchor_start: start,
+    anchor_end: end,
+    anchor_version: version,
+    match_count: 1,
+    confidence,
+    preview_before: body.slice(Math.max(0, start - PREVIEW), start),
+    preview_after: body.slice(end, Math.min(body.length, end + PREVIEW))
+  };
+}
+
+// src/tools/page-comments.ts
 function registerPageCommentTools(server2, client2) {
+  server2.tool(
+    "cla_list_page_comments",
+    "List comments on a page. Returns root comments with their threaded replies. Use the resolved filter to focus on open threads (resolved=false) or only the resolved ones (resolved=true). Pass project_id to use the nested route; omit it and the server resolves the page via the api key\u2019s accessible_pages scope.",
+    {
+      page_id: z8.coerce.number().describe("Page ID to list comments for"),
+      project_id: z8.coerce.number().optional().describe("Project ID (optional \u2014 omit to use the flat route)"),
+      resolved: z8.boolean().optional().describe("Filter: true returns only resolved comments, false returns only unresolved")
+    },
+    async (params) => {
+      try {
+        const opts = params.resolved === void 0 ? void 0 : { resolved: params.resolved };
+        const result = params.project_id === void 0 ? await client2.listPageCommentsFlat(params.page_id, opts) : await client2.listPageComments(params.project_id, params.page_id, opts);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "cla_prepare_page_comment_anchor",
+    "Compute validated offsets for an anchored page comment without manually counting characters. Pass one locator: exact_text (must occur exactly once in the page body), or prefix+text+suffix to disambiguate repeated text via surrounding context, or heading+text to restrict the search to a markdown section. Returns anchor_text + anchor_start + anchor_end + anchor_version ready to feed into cla_create_page_comment. Returns a structured ambiguous_anchor error (with the list of matches and their preview context) when the locator still resolves to more than one position \u2014 never silently guesses.",
+    {
+      page_id: z8.coerce.number().describe("Page ID to anchor the comment on"),
+      project_id: z8.coerce.number().optional().describe("Project ID (optional \u2014 inferred via the flat page route)"),
+      exact_text: z8.string().optional().describe("Unique substring to anchor to (errors with ambiguous_anchor if not unique)"),
+      prefix: z8.string().optional().describe("Text immediately before the anchor (use with text + suffix to disambiguate)"),
+      text: z8.string().optional().describe("The selection to anchor (use with prefix+suffix, or with heading)"),
+      suffix: z8.string().optional().describe("Text immediately after the anchor (use with prefix + text)"),
+      heading: z8.string().optional().describe("Markdown heading whose section to search within (use with text)")
+    },
+    async (params) => {
+      try {
+        const pageResponse = params.project_id === void 0 ? await client2.getPageFlat(params.page_id) : await client2.getPage(params.project_id, params.page_id);
+        const page = pageResponse.page;
+        const body = page.body ?? "";
+        if (typeof page.version_number !== "number") {
+          const compat = {
+            error: "invalid_input",
+            hint: "page response is missing version_number \u2014 upgrade the Clarabit server (or pass anchor_text + offsets manually to cla_create_page_comment)"
+          };
+          return { content: [{ type: "text", text: JSON.stringify(compat, null, 2) }] };
+        }
+        const result = computeAnchor(body, page.version_number, {
+          exact_text: params.exact_text,
+          prefix: params.prefix,
+          text: params.text,
+          suffix: params.suffix,
+          heading: params.heading
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
   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.",
+    "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 (+ optionally anchor_version to record the body revision the anchor was computed against). For anchored comments, prefer calling cla_prepare_page_comment_anchor first to get validated offsets \u2014 it handles ambiguous repeated text instead of silently anchoring to the first match.",
     {
       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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limeadelabs/clarabit-mcp",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Clarabit MCP server for Claude Code — AI-native project management integration",
   "type": "module",
   "exports": {