@m2canvas/connect 0.1.0 → 0.3.0

package/README.md

@@ -8,7 +8,9 @@ npx @m2canvas/connect
 
 It finds the supported clients you have installed, shows what it will change, and after you confirm, adds the M2 MCP server (`https://mcp.m2ui.ai/mcp`) to each one and opens its browser sign-in. No API key is needed.
 
-Run it in a regular terminal. Some clients' sign-in (Claude Code's in particular) requires an interactive terminal, so it won't work from inside an agent session.
+**In a terminal**, it asks before changing anything and opens each client's browser sign-in, so one command finishes the whole setup.
+
+**Run by an agent** (no interactive terminal, e.g. pasted from M2's "Copy to agent"), the agent passes `--client <id>` (`claude-code`, `codex`, `cursor`, `opencode`, `qoder`) so only its own client is touched. It adds the server without asking, skips the sign-ins it can't run there, and prints the remaining steps: a command to run (Codex, Cursor, OpenCode) or a place to click in the app (Claude Code, Qoder). The agent can run the commands or pass the steps on to you. Running it again lists the sign-in steps for clients that were already added.
 
 | Client | How it is set up | Sign-in |
 |---|---|---|
@@ -20,6 +22,6 @@ Run it in a regular terminal. Some clients' sign-in (Claude Code's in particular
 
 Clients that already have an entry pointing at `mcp.m2ui.ai`, under any name, are skipped. Before a config file is edited, the original is copied to `<file>.bak-m2canvas`.
 
-Options: `--dry-run` shows the plan without changing anything; `--yes` skips the confirmation.
+Options: `--client <id>` sets up only that client; `--dry-run` shows the plan without changing anything; `--yes` skips the confirmation.
 
 After setup, restart each client so it loads the new server.

package/dist/cli.js

@@ -1,13 +1,26 @@
 #!/usr/bin/env node
-// npx @m2canvas/connect —— 探测本机 agent 客户端，把 M2 MCP 写入各自配置并逐个走浏览器授权。
+// npx @m2canvas/connect —— 探测本机 agent 客户端，把 M2 MCP 写入各自配置并完成浏览器授权。
+//
+// 两种运行方式：
+//   · 真终端（TTY）：预览 → 确认 → 写入 → 逐个跑 login，一条命令走完。
+//   · agent 代跑（非 TTY）：Copy to agent 起手式让 agent 执行本命令。agent 的 shell 没有 TTY，
+//     无法确认也跑不了 Claude Code 的 login，且 login 要阻塞等浏览器回调（OpenCode 还会超时），
+//     所以只写入配置，把剩余授权步骤打印成 agent 可以照做 / 转述给用户的清单。
 import { createInterface } from 'node:readline/promises';
-import { M2_MCP_URL } from './config-files.js';
-import { detectClients } from './clients.js';
-const HELP = `Usage: npx @m2canvas/connect [--yes] [--dry-run]
+import { M2_MCP_URL, SERVER_NAME } from './config-files.js';
+import { CLIENTS, detectClients, isClientId } from './clients.js';
+import { run } from './system.js';
+const CLIENT_IDS = Object.keys(CLIENTS).join(', ');
+const HELP = `Usage: npx @m2canvas/connect [--client <id>] [--yes] [--dry-run]
 
 Adds M2 Canvas (${M2_MCP_URL}) to every agent client found on this machine
-(Claude Code, Codex, Cursor, OpenCode, Qoder), then opens each client's browser sign-in.
+(Claude Code, Codex, Cursor, OpenCode, Qoder), then signs each one in.
 
+In a terminal it asks before changing anything and opens each sign-in in your browser.
+When run by an agent (no terminal), it only adds the server and prints the remaining
+sign-in steps.
+
+  --client <id>  only set up this client (${CLIENT_IDS})
   -y, --yes      skip the confirmation prompt
   --dry-run      only show what would change
   -h, --help     show this help`;
@@ -21,14 +34,17 @@ async function confirm(question) {
         rl.close();
     }
 }
+function shellQuote(value) {
+    return /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
 function printPlan(plans) {
     console.log(`\nM2 Canvas MCP: ${M2_MCP_URL}\n`);
     for (const plan of plans) {
         if (plan.existing) {
-            console.log(`  • ${plan.label}: already connected as "${plan.existing}" — skipping`);
+            console.log(`  • ${plan.label}: already has M2 as "${plan.existing}", skipping`);
         }
         else if (plan.blocked) {
-            console.log(`  ! ${plan.label}: can't set up automatically — ${plan.blocked}`);
+            console.log(`  ! ${plan.label}: can't set up automatically. ${plan.blocked}`);
         }
         else {
             console.log(`  ✓ ${plan.label}`);
@@ -38,61 +54,102 @@ function printPlan(plans) {
     }
     console.log('');
 }
-function describe(outcome) {
-    if (!outcome.ok)
-        return `failed${outcome.note ? `: ${outcome.note}` : ''}`;
-    if (outcome.signIn === 'done')
-        return 'added and signed in';
-    if (outcome.signIn === 'failed')
-        return `added, but sign-in did not finish${outcome.note ? ` (${outcome.note})` : ''}`;
-    return `added. ${outcome.note ?? ''}`.trim();
+function describePending(step) {
+    if (step.login) {
+        return `run \`${[step.login.command, ...step.login.args].map(shellQuote).join(' ')}\` (opens the browser sign-in)`;
+    }
+    return step.manual ?? '';
 }
 async function main() {
-    const args = new Set(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    const args = new Set(argv);
     if (args.has('-h') || args.has('--help')) {
         console.log(HELP);
         return 0;
     }
-    const plans = detectClients();
+    const interactive = Boolean(process.stdin.isTTY);
+    // agent 代跑时由起手式带上自己的 --client：只处理这一家，其他客户端不动、不提 ——
+    // 用户只是在一个客户端里粘了一段话，不该顺带改掉、也不该被列出别的客户端。
+    const clientIndex = argv.indexOf('--client');
+    const requested = clientIndex >= 0 ? (argv[clientIndex + 1] ?? '') : null;
+    if (requested !== null && !isClientId(requested)) {
+        console.error(`Unknown --client "${requested}". Use one of: ${CLIENT_IDS}.`);
+        return 2;
+    }
+    const only = requested ?? undefined;
+    const plans = detectClients(only);
+    if (only && plans.length === 0) {
+        console.log(`Couldn't find a working ${only} CLI on this machine.\nAdd this MCP server by hand instead: ${M2_MCP_URL} (streamable HTTP, OAuth sign-in).`);
+        return 1;
+    }
     if (plans.length === 0) {
         console.log(`No supported agent client found.\nAdd this MCP server in your client by hand: ${M2_MCP_URL} (streamable HTTP, OAuth sign-in).`);
         return 1;
     }
     printPlan(plans);
     const todo = plans.filter((plan) => !plan.existing && !plan.blocked);
-    if (todo.length === 0 || args.has('--dry-run'))
+    if (args.has('--dry-run'))
         return 0;
-    if (!args.has('-y') && !args.has('--yes')) {
-        // 授权要在真终端里完成（Claude Code 的 login 硬性要求 TTY），非 TTY 下直接拒绝而不是跑一半。
-        if (!process.stdin.isTTY) {
-            console.error('Run this in an interactive terminal (browser sign-in needs one), or pass --yes.');
-            return 1;
-        }
+    if (todo.length === 0) {
+        printExistingSignIn(plans, interactive);
+        return 0;
+    }
+    // 非 TTY 下没人能回答确认提示 —— 执行本命令的 agent 就是替用户操作的一方。
+    if (interactive && !args.has('-y') && !args.has('--yes')) {
         if (!(await confirm(`Set up ${todo.map((plan) => plan.label).join(', ')}? (Y/n) `)))
             return 0;
     }
     const results = [];
     for (const plan of todo) {
-        console.log(`\n→ ${plan.label}: finish the sign-in in your browser if one opens.`);
-        let outcome;
+        let added;
         try {
-            outcome = plan.apply();
+            const outcome = plan.add();
+            added = { plan, added: outcome.ok, error: outcome.note, pending: outcome.ok ? plan.signIn(interactive, SERVER_NAME) : null };
         }
         catch (error) {
-            outcome = { ok: false, note: error instanceof Error ? error.message : String(error) };
+            added = { plan, added: false, error: error instanceof Error ? error.message : String(error), pending: null };
         }
-        results.push([plan, outcome]);
+        const login = added.pending?.login;
+        if (interactive && login) {
+            console.log(`\n→ ${plan.label}: finish the sign-in in your browser.`);
+            if (run(login.command, login.args, true).status === 0)
+                added.pending = null;
+        }
+        results.push(added);
+    }
+    console.log('\nResult');
+    for (const result of results) {
+        const state = !result.added ? `failed: ${result.error ?? 'unknown error'}` : result.pending ? 'added, sign-in pending' : 'added and signed in';
+        console.log(`  ${result.plan.label}: ${state}`);
     }
-    console.log('\nSummary');
-    for (const [plan, outcome] of results)
-        console.log(`  ${plan.label}: ${describe(outcome)}`);
-    const restarts = results.filter(([, outcome]) => outcome.ok).map(([plan]) => plan.restart);
-    if (restarts.length > 0) {
-        console.log('\nTo load M2 Canvas:');
-        for (const line of restarts)
-            console.log(`  - ${line}`);
+    const pending = results.filter((result) => result.added && result.pending);
+    if (pending.length > 0) {
+        console.log('\nTo finish signing in:');
+        for (const result of pending)
+            console.log(`  - ${result.plan.label}: ${describePending(result.pending)}`);
+    }
+    const loaded = results.filter((result) => result.added);
+    if (loaded.length > 0) {
+        console.log('\nThen, to load M2 Canvas:');
+        for (const result of loaded)
+            console.log(`  - ${result.plan.restart}`);
+    }
+    printExistingSignIn(plans, interactive);
+    return results.every((result) => result.added) ? 0 : 1;
+}
+/**
+ * 已有入口不代表已授权：agent 首轮写入配置后用户可能还没登录，重粘起手式时 agent 仍没有工具、
+ * 会再跑一次本命令。此时只报 "skipping" 就是死路，所以把这些入口的授权步骤也列出来。
+ * 安装器读不到授权态（token 在各客户端自己的存储里），只能写成「如果还没登录」。
+ */
+function printExistingSignIn(plans, interactive) {
+    const existing = plans.filter((plan) => plan.existing);
+    if (existing.length === 0)
+        return;
+    console.log('\nAlready added. If a client still shows M2 as not signed in:');
+    for (const plan of existing) {
+        console.log(`  - ${plan.label}: ${describePending(plan.signIn(interactive, plan.existing))}`);
     }
-    return results.every(([, outcome]) => outcome.ok) ? 0 : 1;
 }
 main().then((code) => process.exit(code), (error) => {
     console.error(error instanceof Error ? error.message : error);

package/dist/clients.js

@@ -1,14 +1,16 @@
 // 各客户端的探测 / 写入 / 登录。每家的命令与坑位都经本机逐一实测，见 README。
+import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { M2_MCP_URL, SERVER_NAME, findInClaudeConfig, findInCodexToml, findInQoderSettings, mergeCursorConfig, mergeOpencodeConfig, } from './config-files.js';
-import { existsSync, firstExecutable, firstRunnable, home, readJson, readText, run, which, writeJsonWithBackup, } from './system.js';
-function signInWith(command, args) {
-    return run(command, args, true).status === 0 ? 'done' : 'failed';
-}
+import { existsSync, firstExecutable, firstRunnable, home, readJson, readText, run, which, writeJsonWithBackup } from './system.js';
 function jsonExisting(path, find) {
     const read = readJson(path);
     return read.kind === 'ok' ? find(read.value) : null;
 }
+function addWith(command, args) {
+    const result = run(command, args);
+    return result.status === 0 ? { ok: true } : { ok: false, note: result.output };
+}
 function claudeCode() {
     const bin = firstRunnable([which('claude')]);
     if (!bin)
@@ -17,14 +19,13 @@ function claudeCode() {
         label: 'Claude Code',
         existing: jsonExisting(join(home, '.claude.json'), findInClaudeConfig),
         blocked: null,
-        actions: [`claude mcp add --transport http --scope user ${SERVER_NAME} ${M2_MCP_URL}`, 'sign in (browser)'],
+        actions: [`claude mcp add --transport http --scope user ${SERVER_NAME} ${M2_MCP_URL}`],
         restart: 'Restart Claude Code (claude --continue keeps your conversation).',
-        apply() {
-            const add = run(bin, ['mcp', 'add', '--transport', 'http', '--scope', 'user', SERVER_NAME, M2_MCP_URL]);
-            if (add.status !== 0)
-                return { ok: false, note: add.output };
-            return { ok: true, signIn: signInWith(bin, ['mcp', 'login', SERVER_NAME]) };
-        },
+        // `claude mcp login` 在非 TTY 下直接失败（实测 "stdin isn't a terminal"），agent 的 shell 就是这种。
+        signIn: (interactive, name) => interactive
+            ? { login: { command: bin, args: ['mcp', 'login', name] }, manual: null }
+            : { login: null, manual: `In Claude Code, type /mcp, pick ${name} and choose Authenticate.` },
+        add: () => addWith(bin, ['mcp', 'add', '--transport', 'http', '--scope', 'user', SERVER_NAME, M2_MCP_URL]),
     };
 }
 function codex() {
@@ -38,14 +39,14 @@ function codex() {
         label: 'Codex',
         existing: toml ? findInCodexToml(toml) : null,
         blocked: null,
-        actions: [`codex mcp add ${SERVER_NAME} --url ${M2_MCP_URL}`, 'sign in (browser)'],
-        // 顺序敏感：login 的本地回调端口挂在 login 子进程上，必须授权完成后再重启 Codex，所以重启提示放在最后。
-        restart: 'Fully quit and reopen Codex.',
-        apply() {
-            const add = run(bin, ['mcp', 'add', SERVER_NAME, '--url', M2_MCP_URL]);
-            if (add.status !== 0)
-                return { ok: false, note: add.output };
-            return { ok: true, signIn: signInWith(bin, ['mcp', 'login', SERVER_NAME]) };
+        actions: [`codex mcp add ${SERVER_NAME} --url ${M2_MCP_URL}`],
+        // 顺序敏感：login 的本地回调端口挂在 login 进程上，必须授权完成后再重启 Codex。
+        restart: 'Fully quit and reopen Codex (after signing in).',
+        signIn: (_interactive, name) => ({ login: { command: bin, args: ['mcp', 'login', name] }, manual: null }),
+        add() {
+            // codex 在 CODEX_HOME 目录不存在时直接报 "failed to load configuration"，不会自己建。
+            mkdirSync(codexHome, { recursive: true });
+            return addWith(bin, ['mcp', 'add', SERVER_NAME, '--url', M2_MCP_URL]);
         },
     };
 }
@@ -60,17 +61,12 @@ function qoder() {
         blocked: null,
         actions: [`qodercli mcp add -s user -t http ${SERVER_NAME} ${M2_MCP_URL}`],
         restart: 'Reopen Qoder if it is running.',
-        apply() {
-            const add = run(bin, ['mcp', 'add', '-s', 'user', '-t', 'http', SERVER_NAME, M2_MCP_URL]);
-            if (add.status !== 0)
-                return { ok: false, note: add.output };
-            // qodercli 没有 mcp login 子命令，授权只能在 UI 里点。
-            return {
-                ok: true,
-                signIn: 'manual',
-                note: 'Sign in: Qoder → Extensions → Connectors → m2 → Authorize (or run qodercli, then /mcp).',
-            };
-        },
+        // qodercli 没有 mcp login 子命令，授权只能在 UI 里点。
+        signIn: (_interactive, name) => ({
+            login: null,
+            manual: `In Qoder, open Extensions → Connectors → ${name} and click Authorize (or run qodercli, then /mcp).`,
+        }),
+        add: () => addWith(bin, ['mcp', 'add', '-s', 'user', '-t', 'http', SERVER_NAME, M2_MCP_URL]),
     };
 }
 function opencode() {
@@ -83,9 +79,11 @@ function opencode() {
         label: 'OpenCode',
         existing: null,
         blocked: null,
-        actions: [`add "${SERVER_NAME}" to ${path}`, 'sign in (browser)'],
+        actions: [`add "${SERVER_NAME}" to ${path}`],
         restart: 'Restart OpenCode.',
-        apply: () => ({ ok: false }),
+        // auth 不需要 TTY，但等浏览器回调有超时（实测 "Authentication expired"）。
+        signIn: (_interactive, name) => ({ login: { command: bin, args: ['mcp', 'auth', name] }, manual: null }),
+        add: () => ({ ok: false }),
     };
     // jsonc 允许注释，按 JSON 回写会抹掉用户注释 —— 不碰，交给用户手动加。
     if (existsSync(join(dir, 'opencode.jsonc'))) {
@@ -98,9 +96,9 @@ function opencode() {
     return {
         ...base,
         existing: merged.existing,
-        apply() {
+        add() {
             writeJsonWithBackup(path, merged.config);
-            return { ok: true, signIn: signInWith(bin, ['mcp', 'auth', SERVER_NAME]) };
+            return { ok: true };
         },
     };
 }
@@ -115,30 +113,41 @@ function cursor() {
         label: 'Cursor',
         existing: null,
         blocked: null,
-        actions: [`add "${SERVER_NAME}" to ${path}`, ...(bin ? ['cursor-agent mcp enable m2', 'sign in (browser)'] : [])],
+        actions: [`add "${SERVER_NAME}" to ${path}`, ...(bin ? [`cursor-agent mcp enable ${SERVER_NAME}`] : [])],
         restart: 'Restart Cursor if it is running.',
-        apply: () => ({ ok: false }),
+        signIn: (_interactive, name) => bin
+            ? { login: { command: bin, args: ['mcp', 'login', name] }, manual: null }
+            : { login: null, manual: `In Cursor, open Settings → MCP, enable ${name} and log in.` },
+        add: () => ({ ok: false }),
     };
     if (read.kind === 'invalid')
         return { ...base, blocked: `${path} is not valid JSON (${read.error}).` };
-    const current = read.kind === 'ok' ? read.value : {};
-    const merged = mergeCursorConfig(current);
+    const merged = mergeCursorConfig(read.kind === 'ok' ? read.value : {});
     return {
         ...base,
         existing: merged.existing,
-        apply() {
+        add() {
             writeJsonWithBackup(path, merged.config);
-            if (!bin) {
-                return { ok: true, signIn: 'manual', note: 'Sign in: Cursor Settings → MCP → enable m2 and log in.' };
-            }
-            // 不 enable 会停在 "needs approval"，login 也加载不到它。
+            if (!bin)
+                return { ok: true };
+            // 不 enable 会停在 "needs approval"，login 也加载不到它。enable 不需要 TTY。
             const enable = run(bin, ['mcp', 'enable', SERVER_NAME]);
-            if (enable.status !== 0)
-                return { ok: true, signIn: 'failed', note: enable.output };
-            return { ok: true, signIn: signInWith(bin, ['mcp', 'login', SERVER_NAME]) };
+            return enable.status === 0 ? { ok: true } : { ok: false, note: enable.output };
         },
     };
 }
-export function detectClients() {
-    return [claudeCode(), codex(), cursor(), opencode(), qoder()].filter((plan) => plan !== null);
+/** `--client` 的取值 → 探测函数。探测会真跑 `--version`，所以按需只跑被点名的那家。 */
+export const CLIENTS = {
+    'claude-code': claudeCode,
+    codex,
+    cursor,
+    opencode,
+    qoder,
+};
+export function isClientId(value) {
+    return Object.hasOwn(CLIENTS, value);
+}
+export function detectClients(only) {
+    const ids = only ? [only] : Object.keys(CLIENTS);
+    return ids.map((id) => CLIENTS[id]()).filter((plan) => plan !== null);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2canvas/connect",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Connect your local agent clients (Claude Code, Codex, Cursor, OpenCode, Qoder) to M2 Canvas over MCP in one command.",
   "type": "module",
   "bin": {