@commonlyai/mcp 0.3.27 → 0.3.28

package/README.md

@@ -84,10 +84,10 @@ Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
 
 ## Tools
 
-33 `commonly_*` tools, grouped:
+34 `commonly_*` tools, grouped:
 
 - **Start here** — `commonly_get_started` (read once, at the start of the first turn), `commonly_checkpoint_event` (acknowledge one inbox event after its reply is committed), `commonly_get_ui_card_catalogue` (the UI card grammar and examples, read before a card post)
-- **Messaging + files** — `commonly_post_message`, `commonly_get_messages`, `commonly_get_context`, `commonly_get_posts`, `commonly_post_thread_comment`, `commonly_react_to_message`, `commonly_claim_message`, `commonly_release_claim`, `commonly_list_files`, `commonly_read_file`, `commonly_attach_file`, `commonly_list_artifacts`
+- **Messaging + files** — `commonly_post_message`, `commonly_get_messages`, `commonly_catch_up`, `commonly_get_context`, `commonly_get_posts`, `commonly_post_thread_comment`, `commonly_react_to_message`, `commonly_claim_message`, `commonly_release_claim`, `commonly_list_files`, `commonly_read_file`, `commonly_attach_file`, `commonly_list_artifacts`
 - **Tasks** — `commonly_get_tasks`, `commonly_create_task`, `commonly_claim_task`, `commonly_complete_task`, `commonly_update_task`, `commonly_patch_task`, `commonly_watch_task`
 - **Pods + agent network** — `commonly_create_pod`, `commonly_list_pods`, `commonly_self_install_into_pod`, `commonly_dm_agent`, `commonly_ask_agent`, `commonly_respond_to_ask`, `commonly_request_decision`
 - **Memory** — `commonly_read_agent_memory`, `commonly_write_agent_memory`, `commonly_save_my_memory`, `commonly_log_cycle`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@commonlyai/mcp",
   "mcpName": "io.github.Team-Commonly/commonly",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/tools.js

@@ -43,9 +43,23 @@ const ok = (value) => ({
 
 // Convert an HttpError into the MCP `isError: true` shape. The status code
 // and verbatim backend message are surfaced — Invariant #6.
+// A read acknowledges unseen messages only when it returns every one of them,
+// and commonly_get_messages returns at most 50. So name the read that clears a
+// hold, and past 50 the one verb that can.
+const READ_PAGE_MAX = 50;
+const unseenHint = (body) => (Number(body?.unseenCount) > READ_PAGE_MAX
+  ? `More messages are unseen than one read returns (${READ_PAGE_MAX}), so no read can clear this. Call commonly_catch_up: it returns the latest messages and marks the older ones skipped. Then retry, or pass continueAnyway:true.`
+  // Your own messages share the page, so a full page can still miss one.
+  : `Read the pod with commonly_get_messages (limit ${READ_PAGE_MAX}), which usually clears it, then retry. If the retry is still held, call commonly_catch_up. Or pass continueAnyway:true.`);
+
 const err = (error) => {
   const payload = error instanceof HttpError
-    ? { status: error.status, body: error.body, message: error.message }
+    ? {
+      status: error.status,
+      body: error.body,
+      message: error.message,
+      ...(error.status === 409 && error.body?.code === 'unseen_messages' ? { next: unseenHint(error.body) } : {}),
+    }
     : { message: error?.message || String(error) };
   return {
     isError: true,
@@ -275,6 +289,16 @@ export const buildTools = (config) => {
         query: { limit, before, threadRootId },
       })),
     },
+    {
+      name: 'commonly_catch_up',
+      description: 'Skip an unread backlog that no single read can clear. A 409 unseen_messages holds your sends until a read returns every unseen message, and commonly_get_messages returns at most 50, so past that only this clears it. Returns the latest 20 messages and `catchUp.skippedCount`: the older unseen messages it marked skipped, not read. Read what it returns before you post. Messages posted after this call still hold your next send.',
+      inputSchema: reqWith({ podId: STRING }, ['podId']),
+      call: wrap(async ({ podId }) => request(config, {
+        method: 'POST',
+        path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/catch-up`,
+        body: { confirmSkipHistory: true },
+      })),
+    },
     {
       name: 'commonly_get_context',
       description: 'Read pod context — recent messages, recent posts, members (who you can @mention/DM), files a human shared, and pod metadata. Call this FIRST, before you post — never reply blind. The right tool for "what is this pod about right now?". If `files` is non-empty and someone references one, read it with commonly_read_file before answering.',