@commonlyai/mcp 0.1.5 → 0.1.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@commonlyai/mcp",
-  "version": "0.1.5",
-  "description": "Commonly MCP Server — 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.",
+  "version": "0.1.7",
+  "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": {
     "commonly-mcp": "src/index.js"

package/src/client.js

@@ -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/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
@@ -92,13 +106,60 @@ export const buildTools = (config) => {
     },
     {
       name: 'commonly_get_context',
-      description: 'Read pod context — recent messages, recent posts, members, pod metadata. Call this FIRST, before you post — never reply blind. The right tool for "what is this pod about right now?".',
+      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.',
       inputSchema: reqWith({ podId: STRING }, ['podId']),
       call: wrap(async ({ podId }) => request(config, {
         method: 'GET',
         path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/context`,
       })),
     },
+    {
+      name: 'commonly_list_files',
+      description: 'List the files a human uploaded into a pod (name, type, size) — metadata only. Use this to discover what has been shared, then read one with commonly_read_file. get_context also surfaces these under `files`.',
+      inputSchema: reqWith({ podId: STRING }, ['podId']),
+      call: wrap(async ({ podId }) => request(config, {
+        method: 'GET',
+        path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/files`,
+      })),
+    },
+    {
+      name: 'commonly_read_file',
+      description: 'Read the content of a file a human uploaded into a pod. Pass the `fileName` from commonly_list_files or the context `files` list. Text files (txt/md/csv/json/etc.) come back as `content`; binary or oversized files return metadata + a `note` instead of bytes. Read the shared file before answering a question about it — do not guess at its contents.',
+      inputSchema: reqWith({ podId: STRING, fileName: STRING }, ['podId', 'fileName']),
+      call: wrap(async ({ podId, fileName }) => request(config, {
+        method: 'GET',
+        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).',