@commonlyai/cli 0.1.212 → 0.1.213

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.212",
+  "version": "0.1.213",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -16,6 +16,7 @@ import { createRuntimeReporter } from '../lib/runtime-observation.js';
  * heartbeat  — manually trigger an agent's heartbeat
  */
 
+import { refreshMcpTokenCopy, removeMcpTokenCopy } from '../lib/mcp-token.js';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, readdirSync } from 'fs';
 import { join, dirname, basename, resolve as pathResolve } from 'path';
 import { homedir, tmpdir } from 'os';
@@ -147,6 +148,12 @@ export const saveAgentToken = (name, record) => {
     JSON.stringify({ ...record, savedAt: new Date().toISOString() }, null, 2),
     { encoding: 'utf8', mode: 0o600 },
   );
+  // After the record is durable, so a failed refresh never loses a freshly minted token.
+  try {
+    refreshMcpTokenCopy(name, record?.runtimeToken);
+  } catch (err) {
+    console.warn(`Could not refresh the MCP token copy for '${name}': ${err.message}. Run: commonly mcp config --agent ${name}`);
+  }
 };
 
 export const loadAgentToken = (name) => {
@@ -162,6 +169,7 @@ export const loadAgentToken = (name) => {
 export const deleteAgentToken = (name) => {
   const file = tokenFile(name);
   if (existsSync(file)) rmSync(file);
+  removeMcpTokenCopy(name);
 };
 
 // ── env-var bootstrap for `agent run` (#913) ────────────────────────────────

package/src/commands/mcp.js

@@ -0,0 +1,55 @@
+/**
+ * commonly mcp config — print an MCP server config for a locally attached agent (TASK-666).
+ * The MCP server only accepts a cm_agent_* runtime token, so the config points
+ * COMMONLY_TOKEN_FILE at a 0600 copy of that token and never prints the token.
+ */
+import { listLocalAgents, loadAgentToken } from './agent.js';
+import { validMcpTokenName, writeMcpTokenCopy } from '../lib/mcp-token.js';
+
+const NO_AGENT_HINT = 'Attach one first: commonly agent attach <adapter> --pod <podId> --name <name>';
+
+export const buildMcpConfig = ({ agent } = {}) => {
+  let name = agent;
+  if (!name) {
+    const local = listLocalAgents();
+    if (local.length === 0) throw new Error(`No local agent has a runtime token on this computer. ${NO_AGENT_HINT}`);
+    if (local.length > 1) {
+      throw new Error(`More than one local agent (${local.map((a) => a.name).join(', ')}). Pick one with --agent <name>.`);
+    }
+    name = local[0].name;
+  }
+  if (!validMcpTokenName(name)) throw new Error(`Invalid agent name '${name}'`);
+  const record = loadAgentToken(name);
+  const token = String(record?.runtimeToken || '').trim();
+  if (!token) throw new Error(`No runtime token saved for agent '${name}'. ${NO_AGENT_HINT}`);
+  if (!token.startsWith('cm_agent_')) throw new Error(`The saved token for '${name}' is not a cm_agent_* runtime token. Re-attach it: commonly agent attach`);
+  if (!record.instanceUrl) throw new Error(`Agent '${name}' has no saved instance URL. Re-attach it.`);
+
+  const tokenPath = writeMcpTokenCopy(name, token);
+
+  return {
+    mcpServers: {
+      commonly: {
+        command: 'npx',
+        args: ['-y', '@commonlyai/mcp@latest'],
+        env: { COMMONLY_API_URL: record.instanceUrl, COMMONLY_TOKEN_FILE: tokenPath },
+      },
+    },
+  };
+};
+
+export const registerMcp = (program) => {
+  const mcp = program.command('mcp').description('Connect an MCP client (Claude Code, Codex, Cursor) to Commonly');
+  mcp
+    .command('config')
+    .description('Print an MCP server config for a locally attached agent; the token stays in a 0600 file')
+    .option('--agent <name>', 'Local agent to use (default: the only one)')
+    .action((opts) => {
+      try {
+        console.log(JSON.stringify(buildMcpConfig({ agent: opts.agent }), null, 2));
+      } catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+      }
+    });
+};

package/src/index.js

@@ -22,6 +22,7 @@ import { registerPod } from './commands/pod.js';
 import { registerDev } from './commands/dev.js';
 import { registerVerify } from './commands/verify.js';
 import { registerDoctor } from './commands/doctor.js';
+import { registerMcp } from './commands/mcp.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
@@ -57,6 +58,7 @@ registerVerify(program);
 
 // Install health: one line per check (TASK-660)
 registerDoctor(program);
+registerMcp(program);
 
 // Each subcommand owns its own `--instance <url>` flag; a program-level
 // duplicate shadowed the subcommand value on commander v12, causing

package/src/lib/mcp-token.js

@@ -0,0 +1,36 @@
+/**
+ * The 0600 copy of an agent's runtime token that `commonly mcp config` points
+ * COMMONLY_TOKEN_FILE at (TASK-666). It is a second live secret, so the agent
+ * token's lifecycle owns it: save refreshes it, delete removes it.
+ */
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const validMcpTokenName = (name) => typeof name === 'string' && /^[A-Za-z0-9._-]+$/.test(name) && !name.startsWith('.');
+
+export const mcpTokenPath = (name) => {
+  if (!validMcpTokenName(name)) throw new Error(`Invalid agent name '${name}'`);
+  return join(homedir(), '.commonly', 'mcp', `${name}.token`);
+};
+
+// Remove first, then create exclusively at 0600: no write into a looser-mode file or through a symlink.
+export const writeMcpTokenCopy = (name, token) => {
+  const dir = join(homedir(), '.commonly', 'mcp');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const path = mcpTokenPath(name);
+  rmSync(path, { force: true });
+  writeFileSync(path, `${token}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  return path;
+};
+
+// A bad name never has a copy, so remove and refresh are no-ops for it and cannot block detach or save.
+export const removeMcpTokenCopy = (name) => {
+  if (validMcpTokenName(name)) rmSync(mcpTokenPath(name), { force: true });
+};
+
+// Reattach mints a new token; a copy that already exists must follow it.
+export const refreshMcpTokenCopy = (name, token) => {
+  if (token && validMcpTokenName(name) && existsSync(mcpTokenPath(name))) writeMcpTokenCopy(name, token);
+};