@commonlyai/mcp 0.1.6 → 0.1.8

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.6",
+  "version": "0.1.8",
   "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.8';
 
 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)');
@@ -98,3 +98,42 @@ export const request = async (config, { method, path, query, body, _fetchImpl =
   }
   return parsed;
 };
+
+/**
+ * Multipart upload — for attaching a local file to a pod. Node 18+ has global
+ * FormData / Blob, so no runtime deps. `fileField` is the multipart field name
+ * the backend's multer middleware expects. Same response handling as `request`.
+ */
+export const requestUpload = async (config, {
+  path, fileBuffer, fileName, contentType, fileField = 'file', fields = {}, _fetchImpl = fetch,
+} = {}) => {
+  const url = `${config.baseUrl}${path}`;
+  const form = new FormData();
+  form.append(
+    fileField,
+    new Blob([fileBuffer], { type: contentType || 'application/octet-stream' }),
+    fileName,
+  );
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== undefined && v !== null) form.append(k, String(v));
+  }
+  // Do NOT set Content-Type — fetch sets the multipart boundary itself.
+  const res = await _fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${config.token}`,
+      'User-Agent': USER_AGENT,
+      Accept: 'application/json',
+    },
+    body: form,
+  });
+  const raw = await res.text();
+  let parsed;
+  try { parsed = raw ? JSON.parse(raw) : null; } catch { parsed = raw; }
+  if (!res.ok) {
+    const message = (parsed && typeof parsed === 'object' && parsed.message)
+      || (typeof parsed === 'string' ? parsed.slice(0, 500) : `HTTP ${res.status}`);
+    throw new HttpError(res.status, parsed, message);
+  }
+  return parsed;
+};

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.8';
 
 const main = async () => {
   // Fail fast on missing env. The MCP host (codex/claude) will surface this

package/src/tools.js

@@ -18,7 +18,21 @@
  * human-JWT-only route.
  */
 
-import { request, HttpError } from './client.js';
+import { readFileSync } from 'fs';
+import { basename, extname } from 'path';
+import { request, requestUpload, HttpError } from './client.js';
+
+// Minimal content-type guess for attach — the backend re-derives `kind`, this
+// just sets a sensible multipart type. Keep the map small; default is generic.
+const CONTENT_TYPES = {
+  '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv',
+  '.json': 'application/json', '.pdf': 'application/pdf', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.html': 'text/html', '.xml': 'application/xml', '.log': 'text/plain',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
 
 // Convert a successful response into the MCP `content` shape. Strings and
 // JSON-serialisable values both go through `JSON.stringify` so the model
@@ -117,6 +131,35 @@ export const buildTools = (config) => {
         path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/files/${encodeURIComponent(fileName)}/content`,
       })),
     },
+    {
+      name: 'commonly_attach_file',
+      description: 'Attach a file from THIS machine into a pod so humans and other agents can see and read it — a report you wrote, a diff, a generated CSV/deck, etc. Pass `filePath` (a path on the local filesystem). It uploads the file and posts it into the pod as a file card; add `message` for a line of context alongside it. Returns the uploaded file metadata (its `fileName` is what commonly_read_file takes).',
+      inputSchema: reqWith({ podId: STRING, filePath: STRING, message: STRING }, ['podId', 'filePath']),
+      call: wrap(async ({ podId, filePath, message }) => {
+        const buffer = readFileSync(filePath);
+        const name = basename(filePath);
+        const contentType = CONTENT_TYPES[extname(name).toLowerCase()] || 'application/octet-stream';
+        const uploaded = await requestUpload(config, {
+          path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/uploads`,
+          fileBuffer: buffer,
+          fileName: name,
+          contentType,
+          fileField: 'file',
+          fields: { podId },
+        });
+        // Post a message with the [[upload:…]] directive so it renders as a
+        // file pill in the thread (same shape the human composer emits).
+        const u = uploaded || {};
+        const directive = `[[upload:${u.fileName || name}|${u.originalName || name}|${u.size || buffer.length}|${u.kind || 'document'}]]`;
+        const content = message ? `${message} ${directive}` : directive;
+        await request(config, {
+          method: 'POST',
+          path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/messages`,
+          body: { content },
+        });
+        return uploaded;
+      }),
+    },
     {
       name: 'commonly_get_posts',
       description: 'List recent posts in a pod. Each post includes recent human comments (full text, last 5) and recent agent comments (60-char preview, last 3).',
@@ -213,7 +256,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,
@@ -221,7 +264,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: {},
       })),
     },
     {
@@ -296,6 +362,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.",
@@ -350,4 +449,3 @@ export const buildTools = (config) => {
     },
   ];
 };
-