@commonlyai/mcp 0.3.27 → 0.3.29

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.29",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/client.js

@@ -132,7 +132,9 @@ export const loadConfig = (env = process.env, opts = {}) => {
  * `query` is a flat object — all values stringified and URL-encoded.
  * `_fetchImpl` is a test seam (same convention as `cli/src/lib/adapters/*.js`).
  */
-export const request = async (config, { method, path, query, body, _fetchImpl = fetch } = {}) => {
+export const request = async (config, {
+  method, path, query, body, signal, _fetchImpl = fetch,
+} = {}) => {
   let url = `${config.baseUrl}${path}`;
   if (query) {
     const params = new URLSearchParams();
@@ -154,6 +156,7 @@ export const request = async (config, { method, path, query, body, _fetchImpl =
     method,
     headers,
     body: body !== undefined ? JSON.stringify(body) : undefined,
+    signal,
   });
 
   // Read body once. Prefer JSON; fall back to text for non-JSON error pages

package/src/index.js

@@ -25,7 +25,7 @@ import {
   CallToolRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 
-import { loadConfig } from './client.js';
+import { loadConfig, request } from './client.js';
 import { buildTools } from './tools.js';
 import { PACKAGE_VERSION } from './version.js';
 
@@ -66,6 +66,20 @@ const main = async () => {
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
+
+  // One authenticated call at start (TASK-345). Until a tool ran, nothing
+  // reached Commonly, so a working install and a broken one looked the same and
+  // the agent never showed as connected. A failure goes to stderr and never
+  // ends the server: stdout belongs to the MCP transport.
+  // Bounded, so a server that never answers cannot keep the process alive
+  // after the host has gone.
+  request(config, {
+    method: 'GET', path: '/api/agents/runtime/installations', signal: AbortSignal.timeout(10000),
+  }).catch((e) => {
+    // The status says which kind of failure this is; see docs/MCP_INTEGRATION.md.
+    const status = e.status ? `HTTP ${e.status}: ` : '';
+    process.stderr.write(`[commonly-mcp] could not reach Commonly at start: ${status}${e.message}\n`);
+  });
 };
 
 main().catch((e) => {

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.',