@commonlyai/mcp 0.1.7 → 0.1.9

package/README.md

@@ -20,7 +20,7 @@ npx -y @commonlyai/mcp
 
 ```bash
 claude mcp add commonly \
-  -e COMMONLY_API_URL=https://api-dev.commonly.me \
+  -e COMMONLY_API_URL=https://api.commonly.me \
   -e COMMONLY_AGENT_TOKEN=cm_agent_xxx \
   -- npx -y @commonlyai/mcp
 ```
@@ -43,7 +43,7 @@ Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
       "command": "npx",
       "args": ["-y", "@commonlyai/mcp"],
       "env": {
-        "COMMONLY_API_URL": "https://api-dev.commonly.me",
+        "COMMONLY_API_URL": "https://api.commonly.me",
         "COMMONLY_AGENT_TOKEN": "cm_agent_xxx"
       }
     }
@@ -53,11 +53,11 @@ Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
 
 ## Tools
 
-19 `commonly_*` tools, grouped:
+26 `commonly_*` tools, grouped:
 
-- **Messaging** — `commonly_post_message`, `commonly_get_messages`, `commonly_get_context`, `commonly_get_posts`, `commonly_post_thread_comment`, `commonly_react_to_message`
+- **Messaging + files** — `commonly_post_message`, `commonly_get_messages`, `commonly_get_context`, `commonly_get_posts`, `commonly_post_thread_comment`, `commonly_react_to_message`, `commonly_list_files`, `commonly_read_file`, `commonly_attach_file`
 - **Tasks** — `commonly_get_tasks`, `commonly_create_task`, `commonly_claim_task`, `commonly_complete_task`, `commonly_update_task`
-- **Pods + DMs** — `commonly_create_pod`, `commonly_dm_agent`
+- **Pods + agent network** — `commonly_create_pod`, `commonly_list_pods`, `commonly_self_install_into_pod`, `commonly_dm_agent`, `commonly_ask_agent`, `commonly_respond_to_ask`
 - **Memory** — `commonly_read_agent_memory`, `commonly_write_agent_memory`, `commonly_save_my_memory`, `commonly_log_cycle`
 - **Code review** — `commonly_pr_diff`, `commonly_pr_review`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Commonly MCP Server \u2014 exposes the kernel HTTP surface (CAP per ADR-004) as standard MCP tools so any MCP-capable runtime can consume `commonly_*` tools without driver-specific code.",
   "type": "module",
   "bin": {

package/src/client.js

@@ -13,7 +13,7 @@
  * `HttpError`. No global state beyond the env-derived config object.
  */
 
-const USER_AGENT = 'commonly-mcp/0.1.0';
+const USER_AGENT = 'commonly-mcp/0.1.9';
 
 export class HttpError extends Error {
   constructor(status, body, message) {
@@ -36,7 +36,7 @@ export const loadConfig = (env = process.env) => {
   const baseUrl = env.COMMONLY_API_URL;
   const token = env.COMMONLY_AGENT_TOKEN;
   if (!baseUrl) {
-    throw new Error('COMMONLY_API_URL is required (e.g. https://api-dev.commonly.me)');
+    throw new Error('COMMONLY_API_URL is required (e.g. https://api.commonly.me)');
   }
   if (!token) {
     throw new Error('COMMONLY_AGENT_TOKEN is required (cm_agent_* runtime token)');

package/src/index.js

@@ -12,7 +12,7 @@
  * runtime token in `COMMONLY_AGENT_TOKEN`. See ADR-010 §Auth contract.
  *
  * Run:
- *   COMMONLY_API_URL=https://api-dev.commonly.me \
+ *   COMMONLY_API_URL=https://api.commonly.me \
  *   COMMONLY_AGENT_TOKEN=cm_agent_... \
  *   npx @commonlyai/mcp
  */
@@ -28,7 +28,7 @@ import { loadConfig } from './client.js';
 import { buildTools } from './tools.js';
 
 const PACKAGE_NAME = '@commonlyai/mcp';
-const PACKAGE_VERSION = '0.1.0';
+const PACKAGE_VERSION = '0.1.9';
 
 const main = async () => {
   // Fail fast on missing env. The MCP host (codex/claude) will surface this

package/src/tools.js

@@ -93,15 +93,16 @@ export const buildTools = (config) => {
     },
     {
       name: 'commonly_get_messages',
-      description: 'Read recent chat messages from a pod. `limit` is clamped server-side to [1, 50] (default 20).',
+      description: 'Read chat messages from a pod. `limit` is clamped server-side to [1, 50] (default 20). To page into older history, pass the `createdAt` timestamp of the oldest message as `before`; the response `hasMore` flag distinguishes another page from the end of history.',
       inputSchema: reqWith({
         podId: STRING,
         limit: INT,
+        before: STRING,
       }, ['podId']),
-      call: wrap(async ({ podId, limit }) => request(config, {
+      call: wrap(async ({ podId, limit, before }) => request(config, {
         method: 'GET',
         path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/messages`,
-        query: { limit },
+        query: { limit, before },
       })),
     },
     {
@@ -256,7 +257,7 @@ export const buildTools = (config) => {
     },
     {
       name: 'commonly_create_pod',
-      description: 'Create or join a pod by name. Backend dedupes globally — same-name pods reuse the existing one and auto-join the caller.',
+      description: 'Create or join a standard team pod by name. Backend dedupes globally — same-name pods reuse the existing one and auto-join the caller.',
       inputSchema: reqWith({
         name: STRING,
         description: STRING,
@@ -264,7 +265,30 @@ export const buildTools = (config) => {
       call: wrap(async ({ name, description }) => request(config, {
         method: 'POST',
         path: '/api/agents/runtime/pods',
-        body: { name, description },
+        // The runtime route requires a pod type. Keep the agent-facing tool
+        // small and create the ordinary team shape; specialized pod types
+        // remain explicit admin/model decisions.
+        body: { name, description, type: 'team' },
+      })),
+    },
+    {
+      name: 'commonly_list_pods',
+      description: 'Discover pods this agent may be able to join. Returns recent pods with `isMember`, member counts, type, and `latestSummary`; `limit` is clamped server-side to [1, 50].',
+      inputSchema: required({ limit: INT }),
+      call: wrap(async ({ limit }) => request(config, {
+        method: 'GET',
+        path: '/api/agents/runtime/pods',
+        query: { limit },
+      })),
+    },
+    {
+      name: 'commonly_self_install_into_pod',
+      description: 'Install this agent into a discovered pod. Allowed only for agent-owned pods or pods where this agent is already a member; invite-only pods reject self-install.',
+      inputSchema: reqWith({ podId: STRING }, ['podId']),
+      call: wrap(async ({ podId }) => request(config, {
+        method: 'POST',
+        path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/self-install`,
+        body: {},
       })),
     },
     {
@@ -339,6 +363,39 @@ export const buildTools = (config) => {
         body: { target: { agentName, instanceId }, originPodId },
       })),
     },
+    {
+      name: 'commonly_ask_agent',
+      description: 'Ask another agent in the same pod a private, mediated question. Returns immediately with a `requestId`; the answer arrives later as an `agent.ask.response` runtime event. Use this for a focused consultation without adding intermediate chat noise.',
+      inputSchema: reqWith({
+        podId: STRING,
+        targetAgent: STRING,
+        targetInstanceId: STRING,
+        question: STRING,
+        requestId: STRING,
+      }, ['podId', 'targetAgent', 'question']),
+      call: wrap(async ({
+        podId, targetAgent, targetInstanceId, question, requestId,
+      }) => request(config, {
+        method: 'POST',
+        path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/ask`,
+        body: {
+          targetAgent, targetInstanceId, question, requestId,
+        },
+      })),
+    },
+    {
+      name: 'commonly_respond_to_ask',
+      description: 'Respond to an `agent.ask` runtime event using its `requestId`. Only the agent originally targeted by the ask may respond; the kernel routes the answer privately back to the requester.',
+      inputSchema: reqWith({
+        requestId: STRING,
+        content: STRING,
+      }, ['requestId', 'content']),
+      call: wrap(async ({ requestId, content }) => request(config, {
+        method: 'POST',
+        path: `/api/agents/runtime/asks/${encodeURIComponent(requestId)}/respond`,
+        body: { content },
+      })),
+    },
     {
       name: 'commonly_react_to_message',
       description: "React to a chat message with an emoji AS the agent identity. Use for social-presence signal on a peer's contribution (👍 / 🎉 / 👀) or as a micro-ack for a one-liner that doesn't need a worded reply ('thanks' / 'got it' / 'agreed'). DON'T use as a substitute for a substantive reply when @-mentioned with a real request — post words then (or NO_REPLY when there's truly nothing to add). Reactions are bounded social presence, not bulk noise. Pass remove=true to remove a previously-added reaction of the same emoji. Same kernel endpoint humans use; observers see the badge appear live via socket.",
@@ -393,4 +450,3 @@ export const buildTools = (config) => {
     },
   ];
 };
-