@supercollab/cli 0.4.4 → 0.4.6

package/README.md

@@ -133,6 +133,34 @@ Print MCP config:
 supercollab mcp print-config --client codex
 ```
 
+For Claude Desktop on macOS, generate the config from the project directory you
+want the agent to use:
+
+```bash
+cd /path/to/project
+supercollab mcp print-config --client claude
+```
+
+The Claude config uses absolute Node and CLI paths plus an explicit `PATH` so it
+does not depend on Homebrew, nvm, zsh, or GUI app shell startup behavior. Before
+opening Claude, verify the local MCP handshake:
+
+```bash
+supercollab mcp smoke
+```
+
+For Claude Code, install the MCP server from the project directory:
+
+```bash
+cd /path/to/project
+supercollab mcp install --client claude-code
+```
+
+The installer first runs the MCP smoke check, then calls Claude Code's own
+`claude mcp add` with absolute Node and CLI paths plus explicit `HOME`, `PATH`,
+and `SUPERCOLLAB_WORKDIR` values. This avoids Homebrew, nvm, shell startup, and
+GUI path differences.
+
 Default server: `https://hyper.polynode.dev`.
 
 Local config is stored at `~/.supercollab/config.json` with mode `0600`; the

package/bin/supercollab.js

@@ -3,11 +3,13 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import * as readlineCore from 'node:readline';
 import { stdin as input, stdout as output } from 'node:process';
 
-const VERSION = '0.4.4';
+const VERSION = '0.4.6';
+const CLI_ENTRY = fileURLToPath(import.meta.url);
 const DEFAULT_SERVER = process.env.SUPERCOLLAB_URL || 'https://hyper.polynode.dev';
 const DEFAULT_CONFIG = process.env.SUPERCOLLAB_CONFIG || path.join(os.homedir(), '.supercollab', 'config.json');
 const SESSION_TTL_SKEW = 60;
@@ -59,7 +61,9 @@ Usage:
   supercollab embeddings status
   supercollab embeddings warmup
   supercollab mcp stdio
+  supercollab mcp install --client claude-code [--scope local] [--cwd PATH]
   supercollab mcp print-config --client codex
+  supercollab mcp smoke [--timeout 5000]
   supercollab config path
 
 Options:
@@ -1169,9 +1173,96 @@ async function runMcp(opts) {
   }
 }
 
+function encodeMcpMessage(msg) {
+  const raw = Buffer.from(JSON.stringify(msg));
+  return Buffer.concat([Buffer.from(`Content-Length: ${raw.length}\r\n\r\n`), raw]);
+}
+
+function parseMcpMessages(state) {
+  const messages = [];
+  while (true) {
+    const headerEnd = state.buffer.indexOf('\r\n\r\n');
+    if (headerEnd < 0) break;
+    const header = state.buffer.subarray(0, headerEnd).toString();
+    const match = header.match(/content-length:\s*(\d+)/i);
+    if (!match) {
+      state.parseError = `missing content-length in MCP output: ${header.slice(0, 200)}`;
+      break;
+    }
+    const length = Number(match[1]);
+    const total = headerEnd + 4 + length;
+    if (state.buffer.length < total) break;
+    const body = state.buffer.subarray(headerEnd + 4, total).toString();
+    state.buffer = state.buffer.subarray(total);
+    try {
+      messages.push(JSON.parse(body));
+    } catch (err) {
+      state.parseError = err.message || String(err);
+      break;
+    }
+  }
+  return messages;
+}
+
+async function runMcpSmoke(opts) {
+  const file = configPath(opts);
+  const timeoutMs = Math.max(1000, Math.min(Number(opts.timeout || 5000), 30000));
+  const args = [CLI_ENTRY, 'mcp', 'stdio', '--config', file];
+  return await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        PATH: defaultPathEnv(),
+        SUPERCOLLAB_CONFIG: file,
+      },
+    });
+    const state = { buffer: Buffer.alloc(0), parseError: null };
+    const responses = [];
+    let stderr = '';
+    let settled = false;
+    const finish = (err, result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child.kill('SIGTERM'); } catch {}
+      if (err) reject(err);
+      else resolve(result);
+    };
+    const timer = setTimeout(() => {
+      finish(new Error(`MCP smoke timed out after ${timeoutMs}ms. stderr: ${stderr.slice(0, 1000)}`));
+    }, timeoutMs);
+    child.on('error', (err) => finish(err));
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+    child.stdout.on('data', (chunk) => {
+      state.buffer = Buffer.concat([state.buffer, chunk]);
+      for (const msg of parseMcpMessages(state)) responses.push(msg);
+      if (state.parseError) {
+        finish(new Error(state.parseError));
+        return;
+      }
+      if (responses.some((msg) => msg.id === 1) && responses.some((msg) => msg.id === 2)) {
+        const init = responses.find((msg) => msg.id === 1);
+        const tools = responses.find((msg) => msg.id === 2);
+        finish(null, {
+          ok: Boolean(init?.result?.serverInfo && Array.isArray(tools?.result?.tools)),
+          command: process.execPath,
+          args,
+          config: file,
+          server_info: init?.result?.serverInfo || null,
+          tools: (tools?.result?.tools || []).map((tool) => tool.name),
+          stderr: stderr.trim() || null,
+        });
+      }
+    });
+    child.stdin.write(encodeMcpMessage({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }));
+    child.stdin.write(encodeMcpMessage({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }));
+  });
+}
+
 function printCodexConfig(opts) {
   const file = configPath(opts);
-  console.log(mcpConfigText(String(opts.client || 'codex'), file));
+  console.log(mcpConfigText(String(opts.client || 'codex'), file, opts));
 }
 
 async function embeddingStatus() {
@@ -1670,14 +1761,35 @@ async function runSetupSmoke(config, file, roomId, prompts) {
   };
 }
 
-function mcpConfigText(client, file) {
+function defaultPathEnv() {
+  const parts = [
+    path.dirname(process.execPath),
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+    '/usr/bin',
+    '/bin',
+    '/usr/sbin',
+    '/sbin',
+    process.env.PATH || '',
+  ].flatMap((part) => String(part || '').split(path.delimiter)).filter(Boolean);
+  return Array.from(new Set(parts)).join(path.delimiter);
+}
+
+function mcpConfigText(client, file, opts = {}) {
+  const absoluteFile = path.resolve(file);
   const escaped = file.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
   if (client === 'claude') {
+    const cwd = path.resolve(String(opts.cwd || process.env.SUPERCOLLAB_WORKDIR || process.cwd()));
     return JSON.stringify({
       mcpServers: {
         supercollab: {
-          command: 'supercollab',
-          args: ['mcp', 'stdio', '--config', file],
+          type: 'stdio',
+          command: process.execPath,
+          args: [CLI_ENTRY, 'mcp', 'stdio', '--config', absoluteFile],
+          env: {
+            PATH: defaultPathEnv(),
+            SUPERCOLLAB_WORKDIR: cwd,
+          },
         },
       },
     }, null, 2);
@@ -1685,9 +1797,120 @@ function mcpConfigText(client, file) {
   if (client === 'codex') {
     return `[mcp_servers.supercollab]\ncommand = "supercollab"\nargs = ["mcp", "stdio", "--config", "${escaped}"]`;
   }
+  if (client === 'claude-code') {
+    const install = claudeCodeInstallPlan(file, opts);
+    return shellCommand(install.command, install.args);
+  }
   return `supercollab mcp stdio --config "${escaped}"`;
 }
 
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:=@%+-]+$/.test(text)) return text;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+function shellCommand(command, args = []) {
+  return [command, ...args].map(shellQuote).join(' ');
+}
+
+function claudeCodeMcpEnv(opts = {}) {
+  const cwd = path.resolve(String(opts.cwd || process.env.SUPERCOLLAB_WORKDIR || process.cwd()));
+  return {
+    HOME: os.homedir(),
+    PATH: defaultPathEnv(),
+    SUPERCOLLAB_WORKDIR: cwd,
+  };
+}
+
+function claudeCodeInstallPlan(file, opts = {}) {
+  const scope = String(opts.scope || 'local');
+  const claude = String(opts.claude || 'claude');
+  const env = claudeCodeMcpEnv(opts);
+  const args = [
+    'mcp', 'add',
+    '--scope', scope,
+    '--transport', 'stdio',
+    '--env', `HOME=${env.HOME}`,
+    '--env', `PATH=${env.PATH}`,
+    '--env', `SUPERCOLLAB_WORKDIR=${env.SUPERCOLLAB_WORKDIR}`,
+    'supercollab',
+    '--',
+    process.execPath,
+    CLI_ENTRY,
+    'mcp',
+    'stdio',
+    '--config',
+    path.resolve(file),
+  ];
+  return { command: claude, args, env, scope, cwd: env.SUPERCOLLAB_WORKDIR };
+}
+
+function runProcess(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...options,
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    signal: result.signal,
+    stdout: String(result.stdout || '').trim(),
+    stderr: String(result.stderr || '').trim(),
+    error: result.error?.message || null,
+  };
+}
+
+async function installClaudeCodeMcp(config, file, opts = {}) {
+  const client = String(opts.client || 'claude-code');
+  if (!['claude-code', 'claude'].includes(client)) throw new Error(`unsupported mcp install client: ${client}`);
+  const plan = claudeCodeInstallPlan(file, opts);
+  const dryRun = Boolean(opts['dry-run'] || opts.dryRun);
+  const smoke = await runMcpSmoke({ ...opts, config: file, timeout: opts.timeout || 5000 });
+  const removeArgs = ['mcp', 'remove', 'supercollab', '--scope', plan.scope];
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dry_run: true,
+      client: 'claude-code',
+      smoke,
+      remove_command: shellCommand(plan.command, removeArgs),
+      install_command: shellCommand(plan.command, plan.args),
+      scope: plan.scope,
+      cwd: plan.cwd,
+      config: path.resolve(file),
+    };
+  }
+
+  const probe = runProcess(plan.command, ['--version'], { cwd: plan.cwd });
+  if (!probe.ok) {
+    throw new Error(`Claude Code CLI not found or not runnable as ${plan.command}. Install Claude Code first, or pass --claude /absolute/path/to/claude. ${probe.stderr || probe.error || ''}`.trim());
+  }
+
+  runProcess(plan.command, removeArgs, { cwd: plan.cwd });
+  const add = runProcess(plan.command, plan.args, { cwd: plan.cwd });
+  if (!add.ok) {
+    throw new Error(`claude mcp add failed: ${add.stderr || add.stdout || add.error || `exit ${add.status}`}`);
+  }
+  const list = runProcess(plan.command, ['mcp', 'list'], { cwd: plan.cwd });
+  const get = runProcess(plan.command, ['mcp', 'get', 'supercollab'], { cwd: plan.cwd });
+  return {
+    ok: true,
+    client: 'claude-code',
+    scope: plan.scope,
+    cwd: plan.cwd,
+    config: path.resolve(file),
+    smoke,
+    install_command: shellCommand(plan.command, plan.args),
+    claude_add: { stdout: add.stdout, stderr: add.stderr },
+    claude_list: { ok: list.ok, stdout: list.stdout, stderr: list.stderr },
+    claude_get: { ok: get.ok, stdout: get.stdout, stderr: get.stderr },
+    next: 'Start Claude Code in this project, or run /mcp inside Claude Code and confirm supercollab is connected.',
+  };
+}
+
 async function promptSystemCheck(config, file, prompts) {
   const spin = prompts.spinner();
   spin.start('Checking this machine and warming the local BGE model');
@@ -1989,6 +2212,7 @@ async function promptMcpConfig(config, file, prompts) {
   const client = await prompts.select({
     message: 'MCP client config',
     options: [
+      { value: 'claude-code', label: 'Claude Code', hint: 'one-command installer' },
       { value: 'codex', label: 'Codex', hint: 'TOML config snippet' },
       { value: 'claude', label: 'Claude', hint: 'JSON config snippet' },
       { value: 'manual', label: 'Manual', hint: 'stdio command' },
@@ -1999,6 +2223,42 @@ async function promptMcpConfig(config, file, prompts) {
   prompts.note(mcpConfigText(client, file), `${client} MCP config`);
 }
 
+async function promptInstallClaudeCode(config, file, prompts) {
+  const cwd = await prompts.text({
+    message: 'Claude Code project directory',
+    defaultValue: process.cwd(),
+    placeholder: process.cwd(),
+    validate: (value) => fs.existsSync(path.resolve(String(value || ''))) ? undefined : 'Directory does not exist',
+  });
+  if (prompts.isCancel(cwd)) throw new Error('cancelled');
+  const scope = await prompts.select({
+    message: 'Claude Code MCP scope',
+    options: [
+      { value: 'local', label: 'Local project', hint: 'recommended; private to this project' },
+      { value: 'user', label: 'User', hint: 'available across your projects' },
+    ],
+  });
+  if (prompts.isCancel(scope)) throw new Error('cancelled');
+  const spin = prompts.spinner();
+  spin.start('Installing SuperCollab into Claude Code');
+  try {
+    const result = await installClaudeCodeMcp(config, file, { client: 'claude-code', cwd: String(cwd), scope });
+    spin.stop('Claude Code MCP installed');
+    prompts.note([
+      `Scope: ${result.scope}`,
+      `Project: ${result.cwd}`,
+      `Smoke: ${result.smoke?.ok ? 'ok' : 'failed'}`,
+      result.claude_list?.stdout || '',
+      '',
+      result.next,
+    ].filter(Boolean).join('\n'), 'Claude Code');
+    return result;
+  } catch (err) {
+    spin.stop('Claude Code install failed');
+    throw err;
+  }
+}
+
 function sessionsFromResponse(data) {
   if (Array.isArray(data)) return data;
   if (Array.isArray(data?.sessions)) return data.sessions;
@@ -2147,6 +2407,7 @@ async function runSettingsMenu(config, file, prompts) {
       options: [
         { value: 'doctor', label: 'System check / install BGE model' },
         { value: 'account', label: 'Account and config status' },
+        { value: 'install_claude_code', label: 'Install Claude Code MCP' },
         { value: 'mcp', label: 'Show MCP config' },
         { value: 'sessions', label: 'Manage sessions' },
         { value: 'server', label: 'Set server URL' },
@@ -2157,6 +2418,7 @@ async function runSettingsMenu(config, file, prompts) {
     try {
       if (action === 'doctor') await promptSystemCheck(config, file, prompts);
       if (action === 'account') await promptAccountStatus(config, file, prompts);
+      if (action === 'install_claude_code') await promptInstallClaudeCode(config, file, prompts);
       if (action === 'mcp') await promptMcpConfig(config, file, prompts);
       if (action === 'sessions') await promptManageSessions(config, prompts);
       if (action === 'server') await promptSetServerUrl(config, file, prompts);
@@ -2233,6 +2495,7 @@ async function runSetupWizard(config, file, opts = {}) {
     const client = await prompts.select({
       message: 'MCP client config',
       options: [
+        { value: 'claude-code', label: 'Claude Code', hint: 'one-command installer' },
         { value: 'codex', label: 'Codex', hint: 'TOML config snippet' },
         { value: 'claude', label: 'Claude', hint: 'JSON config snippet' },
         { value: 'manual', label: 'Manual', hint: 'stdio command' },
@@ -2321,6 +2584,8 @@ async function main() {
     if (sub === 'warmup') return console.log(JSON.stringify(await embeddingWarmup(), null, 2));
   }
   if (cmd === 'mcp' && sub === 'stdio') return runMcp(opts);
+  if (cmd === 'mcp' && sub === 'install') return console.log(JSON.stringify(await installClaudeCodeMcp(config, file, opts), null, 2));
+  if (cmd === 'mcp' && sub === 'smoke') return console.log(JSON.stringify(await runMcpSmoke(opts), null, 2));
   if (cmd === 'mcp' && sub === 'print-config') return printCodexConfig(opts);
   throw new Error(`unknown command: ${positionals.join(' ')}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supercollab/cli",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "SuperCollab CLI and MCP bridge for encrypted local-search agent group chat.",
   "type": "module",
   "bin": {