@m2canvas/connect 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# @m2canvas/connect
+
+Connect the agent clients on your machine to [M2 Canvas](https://m2ui.ai) in one command.
+
+```bash
+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.
+
+| Client | How it is set up | Sign-in |
+|---|---|---|
+| Claude Code | `claude mcp add --transport http --scope user m2 …` | `claude mcp login m2` |
+| Codex (CLI or the desktop app's bundled CLI) | `codex mcp add m2 --url …` | `codex mcp login m2` |
+| Cursor | merges `m2` into `~/.cursor/mcp.json`, then `cursor-agent mcp enable m2` | `cursor-agent mcp login m2` |
+| OpenCode | merges `m2` into `~/.config/opencode/opencode.json`, keeping the file's existing format | `opencode mcp auth m2` |
+| Qoder (CLI + desktop app) | `qodercli mcp add -s user -t http m2 …` | in Qoder: Extensions → Connectors → m2 → Authorize |
+
+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.
+
+After setup, restart each client so it loads the new server.

package/dist/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// npx @m2canvas/connect —— 探测本机 agent 客户端，把 M2 MCP 写入各自配置并逐个走浏览器授权。
+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]
+
+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.
+
+  -y, --yes      skip the confirmation prompt
+  --dry-run      only show what would change
+  -h, --help     show this help`;
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer === '' || answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+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`);
+        }
+        else if (plan.blocked) {
+            console.log(`  ! ${plan.label}: can't set up automatically — ${plan.blocked}`);
+        }
+        else {
+            console.log(`  ✓ ${plan.label}`);
+            for (const action of plan.actions)
+                console.log(`      ${action}`);
+        }
+    }
+    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();
+}
+async function main() {
+    const args = new Set(process.argv.slice(2));
+    if (args.has('-h') || args.has('--help')) {
+        console.log(HELP);
+        return 0;
+    }
+    const plans = detectClients();
+    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'))
+        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 (!(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;
+        try {
+            outcome = plan.apply();
+        }
+        catch (error) {
+            outcome = { ok: false, note: error instanceof Error ? error.message : String(error) };
+        }
+        results.push([plan, outcome]);
+    }
+    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}`);
+    }
+    return results.every(([, outcome]) => outcome.ok) ? 0 : 1;
+}
+main().then((code) => process.exit(code), (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/clients.js

@@ -0,0 +1,144 @@
+// 各客户端的探测 / 写入 / 登录。每家的命令与坑位都经本机逐一实测，见 README。
+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';
+}
+function jsonExisting(path, find) {
+    const read = readJson(path);
+    return read.kind === 'ok' ? find(read.value) : null;
+}
+function claudeCode() {
+    const bin = firstRunnable([which('claude')]);
+    if (!bin)
+        return null;
+    return {
+        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)'],
+        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]) };
+        },
+    };
+}
+function codex() {
+    // Codex 桌面端（ChatGPT.app）自带 CLI，与独立安装的 codex 共用 ~/.codex。
+    const bin = firstRunnable([which('codex'), '/Applications/ChatGPT.app/Contents/Resources/codex']);
+    if (!bin)
+        return null;
+    const codexHome = process.env.CODEX_HOME ?? join(home, '.codex');
+    const toml = readText(join(codexHome, 'config.toml'));
+    return {
+        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]) };
+        },
+    };
+}
+function qoder() {
+    // CLI 写 ~/.qoder/settings.json，Qoder 桌面端读同一份，一次覆盖两端。
+    const bin = firstRunnable([which('qodercli'), join(home, '.local', 'bin', 'qodercli')]);
+    if (!bin)
+        return null;
+    return {
+        label: 'Qoder',
+        existing: jsonExisting(join(home, '.qoder', 'settings.json'), findInQoderSettings),
+        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).',
+            };
+        },
+    };
+}
+function opencode() {
+    const bin = which('opencode') ?? firstExecutable(['/Applications/OpenCode.app/Contents/Resources/opencode-cli']);
+    if (!bin)
+        return null;
+    const dir = join(process.env.XDG_CONFIG_HOME ?? join(home, '.config'), 'opencode');
+    const path = join(dir, 'opencode.json');
+    const base = {
+        label: 'OpenCode',
+        existing: null,
+        blocked: null,
+        actions: [`add "${SERVER_NAME}" to ${path}`, 'sign in (browser)'],
+        restart: 'Restart OpenCode.',
+        apply: () => ({ ok: false }),
+    };
+    // jsonc 允许注释，按 JSON 回写会抹掉用户注释 —— 不碰，交给用户手动加。
+    if (existsSync(join(dir, 'opencode.jsonc'))) {
+        return { ...base, blocked: `uses opencode.jsonc; add "${SERVER_NAME}": { "type": "remote", "url": "${M2_MCP_URL}" } under "mcp" by hand.` };
+    }
+    const read = readJson(path);
+    if (read.kind === 'invalid')
+        return { ...base, blocked: `${path} is not valid JSON (${read.error}).` };
+    const merged = mergeOpencodeConfig(read.kind === 'ok' ? read.value : {});
+    return {
+        ...base,
+        existing: merged.existing,
+        apply() {
+            writeJsonWithBackup(path, merged.config);
+            return { ok: true, signIn: signInWith(bin, ['mcp', 'auth', SERVER_NAME]) };
+        },
+    };
+}
+function cursor() {
+    const bin = which('cursor-agent');
+    const dir = join(home, '.cursor');
+    if (!bin && !existsSync(dir))
+        return null;
+    const path = join(dir, 'mcp.json');
+    const read = readJson(path);
+    const base = {
+        label: 'Cursor',
+        existing: null,
+        blocked: null,
+        actions: [`add "${SERVER_NAME}" to ${path}`, ...(bin ? ['cursor-agent mcp enable m2', 'sign in (browser)'] : [])],
+        restart: 'Restart Cursor if it is running.',
+        apply: () => ({ 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);
+    return {
+        ...base,
+        existing: merged.existing,
+        apply() {
+            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 也加载不到它。
+            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]) };
+        },
+    };
+}
+export function detectClients() {
+    return [claudeCode(), codex(), cursor(), opencode(), qoder()].filter((plan) => plan !== null);
+}

package/dist/config-files.js

@@ -0,0 +1,90 @@
+// 各客户端配置文件的纯函数读写：查已有 m2 入口、按原格式合并。全部不碰磁盘，便于单测。
+export const M2_MCP_URL = 'https://mcp.m2ui.ai/mcp';
+export const SERVER_NAME = 'm2';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 按 host 判定是不是 M2 的 MCP —— 老入口可能带尾斜杠、query 或别的 path。 */
+export function isM2Url(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        return new URL(value).host === new URL(M2_MCP_URL).host;
+    }
+    catch {
+        return false;
+    }
+}
+/** 在 `{ name: { url } }` 形状的 server 表里找指向 M2 的入口名（任意命名都算）。 */
+export function findM2Entry(servers) {
+    if (!isObject(servers))
+        return null;
+    for (const [name, entry] of Object.entries(servers)) {
+        if (isObject(entry) && (isM2Url(entry.url) || isM2Url(entry.serverUrl)))
+            return name;
+    }
+    return null;
+}
+/** Claude Code `~/.claude.json` 顶层 mcpServers = user scope。 */
+export function findInClaudeConfig(config) {
+    return isObject(config) ? findM2Entry(config.mcpServers) : null;
+}
+/** Qoder `~/.qoder/settings.json`，CLI 与桌面端共用。 */
+export function findInQoderSettings(config) {
+    return isObject(config) ? findM2Entry(config.mcpServers) : null;
+}
+/**
+ * Codex `~/.codex/config.toml`：不引 TOML 解析器，只按行跟踪 `[mcp_servers.<name>]` 段，
+ * 段内出现 M2 url 即命中。只用于「是否已配置」的判断，不做写入。
+ */
+export function findInCodexToml(toml) {
+    let section = null;
+    for (const raw of toml.split(/\r?\n/)) {
+        const line = raw.trim();
+        const header = /^\[mcp_servers\.("?)([^\]"]+)\1\]$/.exec(line);
+        if (header) {
+            section = header[2];
+            continue;
+        }
+        if (line.startsWith('[')) {
+            section = null;
+            continue;
+        }
+        const url = /^url\s*=\s*["']([^"']+)["']/.exec(line);
+        if (section && url && isM2Url(url[1]))
+            return section;
+    }
+    return null;
+}
+/** Cursor `~/.cursor/mcp.json`：合并 `{ url }`，保留其余 server。 */
+export function mergeCursorConfig(config) {
+    const base = isObject(config) ? config : {};
+    const existing = findM2Entry(base.mcpServers);
+    if (existing)
+        return { existing, config: base };
+    const servers = isObject(base.mcpServers) ? base.mcpServers : {};
+    return {
+        existing: null,
+        config: { ...base, mcpServers: { ...servers, [SERVER_NAME]: { url: M2_MCP_URL } } },
+    };
+}
+/**
+ * OpenCode `opencode.json`：`mcp` 有两种形状 —— V1 扁平 `mcp.<name>` 与 V2 嵌套
+ * `mcp.servers.<name>`。实测 `opencode mcp add` 恒写 V2，而文件已有 V1 扁平入口时，
+ * 新入口会被当成名为 "servers" 的 server，auth 报 "MCP server not found"。
+ * 所以跟随文件已有形状：只有纯 V2 文件写嵌套，其余（含空文件、混合）写扁平 —— V2 也读扁平。
+ */
+export function mergeOpencodeConfig(config) {
+    const base = isObject(config) ? config : {};
+    const mcp = isObject(base.mcp) ? base.mcp : {};
+    const nested = isObject(mcp.servers) ? mcp.servers : null;
+    const flatEntries = Object.fromEntries(Object.entries(mcp).filter(([key]) => key !== 'servers'));
+    const existing = findM2Entry(flatEntries) ?? findM2Entry(nested);
+    if (existing)
+        return { existing, config: base };
+    const useNested = nested !== null && Object.keys(flatEntries).length === 0;
+    const nextMcp = useNested
+        ? { ...mcp, servers: { ...nested, [SERVER_NAME]: { type: 'remote', url: M2_MCP_URL } } }
+        : { ...mcp, [SERVER_NAME]: { type: 'remote', url: M2_MCP_URL, enabled: true } };
+    return { existing: null, config: { ...base, mcp: nextMcp } };
+}

package/dist/system.js

@@ -0,0 +1,81 @@
+// 本机探测与文件 / 子进程 IO。只放副作用，逻辑判断留在 config-files.ts。
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+export const home = homedir();
+/** 在 PATH 里找可执行文件；不 spawn `which`，Windows 下补 PATHEXT 后缀。 */
+export function which(command) {
+    const exts = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD').split(';') : [''];
+    for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = join(dir, command + ext);
+            if (isExecutable(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function firstExecutable(paths) {
+    return paths.find(isExecutable) ?? null;
+}
+/**
+ * 候选里第一个真能跑起来的（`--version` 退出码 0）。PATH 上的 shim 可能是坏的 ——
+ * 实测 Homebrew/npm 装的 `codex` 指向已删除的 vendor 二进制，spawn 直接 ENOENT，
+ * 而 Codex 桌面端自带的 CLI 是好的；只看「存在且可执行」会挑中坏的那个。
+ */
+export function firstRunnable(candidates) {
+    for (const candidate of candidates) {
+        if (candidate && isExecutable(candidate) && run(candidate, ['--version']).status === 0)
+            return candidate;
+    }
+    return null;
+}
+export { existsSync };
+export function readJson(path) {
+    if (!existsSync(path))
+        return { kind: 'missing' };
+    try {
+        return { kind: 'ok', value: JSON.parse(readFileSync(path, 'utf8')) };
+    }
+    catch (error) {
+        return { kind: 'invalid', error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function readText(path) {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+}
+/** 覆写前先备份到同目录 `<file>.bak-m2canvas`，返回备份路径（新建文件时为 null）。 */
+export function writeJsonWithBackup(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    let backup = null;
+    if (existsSync(path)) {
+        backup = `${path}.bak-m2canvas`;
+        copyFileSync(path, backup);
+    }
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+    return backup;
+}
+/**
+ * 跑子进程。`interactive` 时继承当前终端 —— login / auth 要开浏览器并等回调，
+ * Claude Code 的 `mcp login` 还硬性要求 TTY（stdin 不是终端时直接失败），所以必须 inherit。
+ */
+export function run(command, args, interactive = false) {
+    const result = spawnSync(command, args, {
+        stdio: interactive ? 'inherit' : 'pipe',
+        encoding: 'utf8',
+    });
+    const output = interactive ? '' : `${result.stdout ?? ''}${result.stderr ?? ''}`.trim();
+    return { status: result.error ? null : result.status, output: result.error ? result.error.message : output };
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@m2canvas/connect",
+  "version": "0.1.0",
+  "description": "Connect your local agent clients (Claude Code, Codex, Cursor, OpenCode, Qoder) to M2 Canvas over MCP in one command.",
+  "type": "module",
+  "bin": {
+    "m2canvas-connect": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "homepage": "https://m2ui.ai/mcp",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}