@commonlyai/mcp 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/mcp",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/client.js

@@ -2,7 +2,7 @@
  * HTTP client for the Commonly MCP server.
  *
  * Per ADR-010 §Auth contract:
- *   - One token per process. `COMMONLY_AGENT_TOKEN` and `COMMONLY_API_URL` are
+ *   - One token per process. The runtime credential and `COMMONLY_API_URL` are
  *     read once at module load. Restart the host runtime to rotate.
  *   - User-Agent must NOT be the default Node `fetch` UA — Cloudflare blocks
  *     anonymous-looking clients (1010). The Python SDK hit this; same fix.
@@ -13,6 +13,8 @@
  * `HttpError`. No global state beyond the env-derived config object.
  */
 
+import { readFileSync } from 'fs';
+
 const USER_AGENT = 'commonly-mcp/0.1.9';
 
 export class HttpError extends Error {
@@ -24,6 +26,52 @@ export class HttpError extends Error {
   }
 }
 
+/**
+ * Read the runtime credential.
+ *
+ * TWO CHANNELS, in this order (TASK-078, ruled 2026-09-19 — "take the token out
+ * of the environment"):
+ *
+ *   1. `COMMONLY_TOKEN_FD` names an inherited pipe holding the credential. This
+ *      is the channel the daemon now uses: the token is never in this process's
+ *      environment, so a same-user reader cannot get it from
+ *      `/proc/<pid>/environ` or `ps eww <pid>` — which is exactly how the old
+ *      channel leaked it.
+ *   2. `COMMONLY_AGENT_TOKEN` in the environment. Kept because the channel is a
+ *      property of the PARENT, not of this package: an older daemon, another
+ *      driver, or a hand-run server still passes it this way, and refusing the
+ *      old channel would turn a security fix into an outage.
+ *
+ * The declared fd is authoritative when present. A read that fails does NOT
+ * fall back to the environment: silently using the weaker channel after being
+ * told to use the stronger one is the class of bug this exists to remove.
+ *
+ * The fd is read to EOF and deliberately never closed — on macOS a `closeSync`
+ * after a failed read aborts the process (`kqueue.c`), and the descriptor goes
+ * away with the process anyway.
+ */
+export const readToken = (env = process.env, { readImpl = readFileSync } = {}) => {
+  const declaredFd = env.COMMONLY_TOKEN_FD;
+  if (declaredFd === undefined || String(declaredFd).trim() === '') {
+    return env.COMMONLY_AGENT_TOKEN;
+  }
+  const fd = Number.parseInt(String(declaredFd).trim(), 10);
+  if (!Number.isInteger(fd) || fd < 0 || String(fd) !== String(declaredFd).trim()) {
+    throw new Error(`COMMONLY_TOKEN_FD must be a file descriptor number, got '${declaredFd}'`);
+  }
+  let raw;
+  try {
+    raw = readImpl(fd, 'utf8');
+  } catch (err) {
+    throw new Error(`COMMONLY_TOKEN_FD=${fd} was declared but the credential could not be read from it: ${err.message}`);
+  }
+  const token = String(raw ?? '').trim();
+  if (!token) {
+    throw new Error(`COMMONLY_TOKEN_FD=${fd} carried an empty credential`);
+  }
+  return token;
+};
+
 /**
  * Build the per-process config from env. Returned object is a frozen handle
  * passed to `request` so the env is read exactly once and tests can inject a
@@ -32,17 +80,17 @@ export class HttpError extends Error {
  * Throws on missing required env vars — better than emitting silent 401s
  * later.
  */
-export const loadConfig = (env = process.env) => {
+export const loadConfig = (env = process.env, opts = {}) => {
   const baseUrl = env.COMMONLY_API_URL;
-  const token = env.COMMONLY_AGENT_TOKEN;
+  const token = readToken(env, opts);
   if (!baseUrl) {
     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)');
+    throw new Error('No runtime token: either COMMONLY_AGENT_TOKEN must be set, or COMMONLY_TOKEN_FD must name a pipe carrying one (cm_agent_* runtime token)');
   }
   if (!token.startsWith('cm_agent_')) {
-    throw new Error('COMMONLY_AGENT_TOKEN must be a cm_agent_* runtime token');
+    throw new Error('The runtime token must be a cm_agent_* token, whichever channel delivered it');
   }
   return Object.freeze({
     baseUrl: baseUrl.replace(/\/$/, ''),

package/src/tools.js

@@ -239,6 +239,27 @@ export const buildTools = (config) => {
         path: `/api/agents/runtime/pods/${encodeURIComponent(podId)}/files`,
       })),
     },
+    {
+      name: 'commonly_list_artifacts',
+      description: 'List every file and page shared in the pods you belong to — newest first, metadata only. `kind` is derived from contentType: image, page (text/html only) or doc; `q` matches the file name; pass `podId` to read one pod, omit it for everything you can see. Page with `after` from the previous result\'s `nextCursor`. Read one with commonly_read_file (podId + fileName).',
+      inputSchema: required({
+        podId: STRING,
+        kind: { type: 'string', enum: ['image', 'page', 'doc'] },
+        q: STRING,
+        limit: INT,
+        after: STRING,
+      }),
+      call: wrap(async ({ podId, kind, q, limit, after } = {}) => {
+        const params = new URLSearchParams();
+        if (podId) params.set('podId', podId);
+        if (kind) params.set('kind', kind);
+        if (q) params.set('q', q);
+        if (limit) params.set('limit', String(limit));
+        if (after) params.set('after', after);
+        const query = params.toString();
+        return request(config, { method: 'GET', path: `/api/artifacts${query ? `?${query}` : ''}` });
+      }),
+    },
     {
       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.',