onto-mcp 0.3.2 → 0.4.1

package/dist/core-runtime/onboard/cli-host.js

@@ -0,0 +1,174 @@
+import { execFileSync } from "node:child_process";
+import { isCommandOnPath } from "./path-scan.js";
+export const defaultCommandRunner = {
+    exists: (command) => isCommandOnPath(command),
+    run: (command, args, env) => {
+        try {
+            const stdout = execFileSync(command, args, {
+                encoding: "utf8",
+                ...(env ? { env: { ...process.env, ...env } } : {}),
+            });
+            return { status: 0, stdout, stderr: "" };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                status: typeof err.status === "number" ? err.status : 1,
+                stdout: typeof err.stdout === "string" ? err.stdout : "",
+                stderr: typeof err.stderr === "string"
+                    ? err.stderr
+                    : error instanceof Error
+                        ? error.message
+                        : String(error),
+            };
+        }
+    },
+};
+function probeRegistered(spec, runner, entry) {
+    const result = runner.run(spec.cli, spec.listArgs(), spec.commandEnv);
+    if (result.status !== 0)
+        return "unknown";
+    const haystack = `${result.stdout}\n${result.stderr}`;
+    // CLIs print one server name per line; a word-boundary match avoids
+    // false positives from substrings of other server names.
+    const pattern = new RegExp(`(^|[^\\w-])${escapeRegExp(entry.name)}([^\\w-]|$)`, "m");
+    return pattern.test(haystack) ? "present" : "absent";
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function createCliHost(spec, runner = defaultCommandRunner) {
+    const detect = () => (runner.exists(spec.cli) ? "cli" : "absent");
+    const withNote = (summary) => spec.targetNote ? `${summary} (${spec.targetNote})` : summary;
+    return {
+        id: spec.id,
+        displayName: spec.displayName,
+        detect,
+        plan(entry) {
+            const detection = detect();
+            if (detection === "absent") {
+                return {
+                    hostId: spec.id,
+                    displayName: spec.displayName,
+                    detection,
+                    method: "manual",
+                    summary: `${spec.cli} CLI not found — manual step required`,
+                    manualInstructions: spec.manualInstructions(entry),
+                };
+            }
+            const commandLine = `${spec.cli} ${spec.addArgs(entry).join(" ")}`;
+            return {
+                hostId: spec.id,
+                displayName: spec.displayName,
+                detection,
+                method: "cli",
+                summary: withNote(`Run: ${commandLine}`),
+                commandLine,
+            };
+        },
+        async apply(entry, options) {
+            const base = { hostId: spec.id, displayName: spec.displayName };
+            if (detect() === "absent") {
+                return { ...base, outcome: "manual", detail: spec.manualInstructions(entry) };
+            }
+            const before = probeRegistered(spec, runner, entry);
+            if (before === "present" && !options.force) {
+                return {
+                    ...base,
+                    outcome: "skipped",
+                    detail: `${entry.name} already registered (use --force to re-add)`,
+                };
+            }
+            if (before === "present" && options.force) {
+                runner.run(spec.cli, spec.removeArgs(entry), spec.commandEnv); // best effort
+            }
+            const result = runner.run(spec.cli, spec.addArgs(entry), spec.commandEnv);
+            if (result.status !== 0) {
+                return {
+                    ...base,
+                    outcome: "failed",
+                    detail: (result.stderr || result.stdout || "command failed").trim(),
+                };
+            }
+            // Verify the add actually took effect. A CLI that exits 0 without
+            // registering (aliased/wrapper `claude`, wrong profile) must not be
+            // reported as success.
+            const after = probeRegistered(spec, runner, entry);
+            const outcome = before === "present" ? "updated" : "registered";
+            if (after === "present") {
+                return { ...base, outcome, detail: `${spec.cli} ${spec.addArgs(entry).join(" ")}` };
+            }
+            if (after === "unknown") {
+                return {
+                    ...base,
+                    outcome,
+                    detail: `${spec.cli} ${spec.addArgs(entry).join(" ")} (could not verify via ${spec.cli} mcp list)`,
+                };
+            }
+            return {
+                ...base,
+                outcome: "failed",
+                detail: `${spec.cli} accepted the command but ${entry.name} is not listed afterward. ` +
+                    `The ${spec.cli} on PATH may be an alias/wrapper or target a different profile` +
+                    (spec.targetNote ? ` (${spec.targetNote})` : "") +
+                    `. Try registering against the real CLI/profile directly.`,
+            };
+        },
+    };
+}
+/**
+ * Claude Code — registers at user scope so it applies across all projects.
+ *
+ * Config-dir resolution: explicit `configDir` wins; otherwise an ambient
+ * `CLAUDE_CONFIG_DIR` is honored (and shown in the plan); otherwise the claude
+ * default (`~/.claude`) applies.
+ */
+export function createClaudeCodeHost(options = {}) {
+    const effectiveDir = options.configDir ?? process.env.CLAUDE_CONFIG_DIR;
+    const spec = {
+        id: "claude-code",
+        displayName: "Claude Code",
+        cli: "claude",
+        addArgs: (entry) => [
+            "mcp",
+            "add",
+            entry.name,
+            "-s",
+            "user",
+            "--",
+            entry.command,
+            ...entry.args,
+        ],
+        removeArgs: (entry) => ["mcp", "remove", entry.name, "-s", "user"],
+        listArgs: () => ["mcp", "list"],
+        manualInstructions: (entry) => `claude CLI not found. Install Claude Code, then run:\n` +
+            `  claude mcp add ${entry.name} -s user -- ${entry.command} ${entry.args.join(" ")}`,
+        ...(effectiveDir ? { commandEnv: { CLAUDE_CONFIG_DIR: effectiveDir } } : {}),
+        targetNote: effectiveDir ? `config dir: ${effectiveDir}` : "config dir: claude default (~/.claude)",
+    };
+    return createCliHost(spec, options.runner);
+}
+/** Codex CLI. */
+export function createCodexHost(runner) {
+    return createCliHost({
+        id: "codex",
+        displayName: "Codex CLI",
+        cli: "codex",
+        addArgs: (entry) => [
+            "mcp",
+            "add",
+            entry.name,
+            "--",
+            entry.command,
+            ...entry.args,
+        ],
+        removeArgs: (entry) => ["mcp", "remove", entry.name],
+        listArgs: () => ["mcp", "list"],
+        manualInstructions: (entry) => `codex CLI not found. Either install Codex and run:\n` +
+            `  codex mcp add ${entry.name} -- ${entry.command} ${entry.args.join(" ")}\n` +
+            `or add this block to ~/.codex/config.toml:\n` +
+            `  [mcp_servers.${entry.name}]\n` +
+            `  command = "${entry.command}"\n` +
+            `  args = [${entry.args.map((a) => `"${a}"`).join(", ")}]`,
+    }, runner);
+}

package/dist/core-runtime/onboard/host-target.js

@@ -0,0 +1,22 @@
+import { createClaudeCodeHost, createCodexHost } from "./cli-host.js";
+import { claudeDesktopConfigPath, createJsonConfigHost, cursorConfigPath, } from "./json-config-host.js";
+/**
+ * The four supported hosts in display order. CLI-backed hosts (Claude Code,
+ * Codex) come first; JSON-config hosts (Claude Desktop, Cursor) follow.
+ */
+export function getDefaultHostTargets(options = {}) {
+    return [
+        createClaudeCodeHost(options.claudeConfigDir ? { configDir: options.claudeConfigDir } : {}),
+        createCodexHost(),
+        createJsonConfigHost({
+            id: "claude-desktop",
+            displayName: "Claude Desktop",
+            resolvePath: () => claudeDesktopConfigPath(),
+        }),
+        createJsonConfigHost({
+            id: "cursor",
+            displayName: "Cursor",
+            resolvePath: () => cursorConfigPath(),
+        }),
+    ];
+}

package/dist/core-runtime/onboard/json-config-host.js

@@ -0,0 +1,122 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { entryMatches, } from "./types.js";
+/**
+ * Pure reconciliation: given the previously-parsed config (or undefined when the
+ * file is absent/empty), return the new config object and what changed. Our own
+ * `<name>` key is always brought to the desired value; sibling servers and other
+ * top-level keys are preserved.
+ */
+export function reconcileMcpServers(existing, entry) {
+    const root = existing && typeof existing === "object" && !Array.isArray(existing)
+        ? { ...existing }
+        : {};
+    const priorServers = root.mcpServers && typeof root.mcpServers === "object" && !Array.isArray(root.mcpServers)
+        ? root.mcpServers
+        : {};
+    const servers = { ...priorServers };
+    const prior = servers[entry.name];
+    if (entryMatches(prior, entry)) {
+        return { config: root, outcome: "skipped" };
+    }
+    servers[entry.name] = { command: entry.command, args: [...entry.args] };
+    root.mcpServers = servers;
+    return {
+        config: root,
+        outcome: prior === undefined ? "registered" : "updated",
+    };
+}
+function defaultDetect(configPath) {
+    if (fsSync.existsSync(configPath))
+        return "config";
+    if (fsSync.existsSync(path.dirname(configPath)))
+        return "config";
+    return "absent";
+}
+async function readJsonIfPresent(filePath) {
+    let text;
+    try {
+        text = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    if (text.trim().length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`Existing config at ${filePath} is not valid JSON: ${error instanceof Error ? error.message : String(error)}. Fix or remove it, then re-run.`);
+    }
+}
+export function createJsonConfigHost(spec) {
+    const detect = spec.detect ?? (() => defaultDetect(spec.resolvePath()));
+    return {
+        id: spec.id,
+        displayName: spec.displayName,
+        detect,
+        plan(entry) {
+            const targetPath = spec.resolvePath();
+            return {
+                hostId: spec.id,
+                displayName: spec.displayName,
+                detection: detect(),
+                method: "config",
+                summary: `Set mcpServers.${entry.name} → ${entry.command} ${entry.args.join(" ")}`.trim(),
+                targetPath,
+            };
+        },
+        async apply(entry, _options) {
+            const targetPath = spec.resolvePath();
+            try {
+                const existing = await readJsonIfPresent(targetPath);
+                const { config, outcome } = reconcileMcpServers(existing, entry);
+                if (outcome === "skipped") {
+                    return {
+                        hostId: spec.id,
+                        displayName: spec.displayName,
+                        outcome: "skipped",
+                        detail: `${entry.name} already registered in ${targetPath}`,
+                    };
+                }
+                await fs.mkdir(path.dirname(targetPath), { recursive: true });
+                await fs.writeFile(targetPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+                return {
+                    hostId: spec.id,
+                    displayName: spec.displayName,
+                    outcome,
+                    detail: `${outcome === "registered" ? "Added" : "Updated"} ${entry.name} in ${targetPath}`,
+                };
+            }
+            catch (error) {
+                return {
+                    hostId: spec.id,
+                    displayName: spec.displayName,
+                    outcome: "failed",
+                    detail: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}
+/**
+ * Claude Desktop config path. macOS and Windows use app-data locations; other
+ * platforms fall back to a Linux-style XDG path (best effort).
+ */
+export function claudeDesktopConfigPath(homedir = os.homedir(), platform = process.platform) {
+    if (platform === "darwin") {
+        return path.join(homedir, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32") {
+        const appData = process.env.APPDATA ?? path.join(homedir, "AppData", "Roaming");
+        return path.join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return path.join(homedir, ".config", "Claude", "claude_desktop_config.json");
+}
+/** Cursor global MCP config path. */
+export function cursorConfigPath(homedir = os.homedir()) {
+    return path.join(homedir, ".cursor", "mcp.json");
+}

package/dist/core-runtime/onboard/path-scan.js

@@ -0,0 +1,26 @@
+import fsSync from "node:fs";
+import path from "node:path";
+/**
+ * True when `command` resolves to an executable on PATH.
+ *
+ * Mirrors the PATH-scan strategy in
+ * `src/core-runtime/discovery/host-detection.ts` (`detectCodexBinaryAvailable`),
+ * but is generic and does not require any auth file. On Windows it also probes
+ * the common executable extensions.
+ */
+export function isCommandOnPath(command, env = process.env) {
+    const pathEnv = env.PATH ?? env.Path ?? "";
+    const isWindows = process.platform === "win32";
+    const candidates = isWindows
+        ? [command, `${command}.cmd`, `${command}.exe`, `${command}.bat`]
+        : [command];
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        for (const candidate of candidates) {
+            if (fsSync.existsSync(path.join(dir, candidate)))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/core-runtime/onboard/prompt.js

@@ -0,0 +1,51 @@
+import readline from "node:readline";
+function createInterface() {
+    return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+function ask(rl, question) {
+    return new Promise((resolve) => rl.question(question, resolve));
+}
+/**
+ * Numbered multi-select. The user enters comma/space-separated numbers; empty
+ * input accepts `defaultSelectedIds`. Returns the chosen choice ids in list order.
+ */
+export async function promptMultiSelect(title, choices, defaultSelectedIds) {
+    const rl = createInterface();
+    try {
+        console.log(title);
+        choices.forEach((choice, index) => {
+            const mark = defaultSelectedIds.includes(choice.id) ? "*" : " ";
+            const detail = choice.detail ? `  — ${choice.detail}` : "";
+            console.log(`  [${mark}] ${index + 1}) ${choice.label}${detail}`);
+        });
+        const answer = (await ask(rl, "Select numbers (comma/space separated, blank = starred defaults): ")).trim();
+        if (answer.length === 0) {
+            return choices.filter((c) => defaultSelectedIds.includes(c.id)).map((c) => c.id);
+        }
+        const picked = new Set();
+        for (const token of answer.split(/[\s,]+/).filter(Boolean)) {
+            const index = Number.parseInt(token, 10) - 1;
+            if (Number.isInteger(index) && index >= 0 && index < choices.length) {
+                picked.add(choices[index].id);
+            }
+        }
+        return choices.filter((c) => picked.has(c.id)).map((c) => c.id);
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Yes/no confirmation. Empty input returns `defaultYes`. */
+export async function promptYesNo(question, defaultYes) {
+    const rl = createInterface();
+    try {
+        const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+        const answer = (await ask(rl, `${question} ${suffix} `)).trim().toLowerCase();
+        if (answer.length === 0)
+            return defaultYes;
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/core-runtime/onboard/register.js

@@ -0,0 +1,214 @@
+import { ALL_HOST_IDS, } from "./types.js";
+import { getDefaultHostTargets } from "./host-target.js";
+import { promptMultiSelect, promptYesNo } from "./prompt.js";
+const USAGE = [
+    "Usage: onto register [options]",
+    "",
+    "Register the onto MCP server into supported hosts so they launch `onto mcp`.",
+    "Interactive when run in a terminal with no --hosts/--all; flag-driven otherwise.",
+    "",
+    "Hosts: claude-code, codex, claude-desktop, cursor",
+    "",
+    "Options:",
+    "  --hosts <a,b,...>  Comma-separated host ids to register",
+    "  --all              Register all supported hosts",
+    "  --list             Show host detection status and exit",
+    "  --dry-run          Show intended changes without writing",
+    "  --yes, -y          Skip the confirmation prompt (required in non-TTY)",
+    "  --force            Re-register CLI hosts even if already present",
+    "  --name <id>        MCP server name (default: onto)",
+    "  --command <cmd>    Executable the host launches (default: onto)",
+    "  --claude-config-dir <path>  Target a Claude Code profile (sets",
+    "                     CLAUDE_CONFIG_DIR; default: ambient env or ~/.claude)",
+    "  --help, -h         Show this help",
+].join("\n");
+export function parseRegisterArgs(argv) {
+    const parsed = {
+        hosts: undefined,
+        yes: false,
+        dryRun: false,
+        force: false,
+        list: false,
+        help: false,
+        name: "onto",
+        command: "onto",
+        claudeConfigDir: undefined,
+        unknownFlags: [],
+        invalidHosts: [],
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--all":
+                parsed.hosts = "all";
+                break;
+            case "--yes":
+            case "-y":
+                parsed.yes = true;
+                break;
+            case "--dry-run":
+                parsed.dryRun = true;
+                break;
+            case "--force":
+                parsed.force = true;
+                break;
+            case "--list":
+                parsed.list = true;
+                break;
+            case "--help":
+            case "-h":
+                parsed.help = true;
+                break;
+            case "--hosts": {
+                const value = argv[++i] ?? "";
+                const ids = [];
+                for (const raw of value.split(",").map((s) => s.trim()).filter(Boolean)) {
+                    if (ALL_HOST_IDS.includes(raw)) {
+                        ids.push(raw);
+                    }
+                    else {
+                        parsed.invalidHosts.push(raw);
+                    }
+                }
+                parsed.hosts = parsed.hosts === "all" ? "all" : ids;
+                break;
+            }
+            case "--name":
+                parsed.name = argv[++i] ?? parsed.name;
+                break;
+            case "--command":
+                parsed.command = argv[++i] ?? parsed.command;
+                break;
+            case "--claude-config-dir":
+                parsed.claudeConfigDir = argv[++i] ?? parsed.claudeConfigDir;
+                break;
+            default:
+                parsed.unknownFlags.push(arg);
+                break;
+        }
+    }
+    return parsed;
+}
+function resolveSelection(parsed, targets) {
+    if (parsed.hosts === "all")
+        return targets.map((t) => t.id);
+    if (Array.isArray(parsed.hosts)) {
+        const requested = new Set(parsed.hosts);
+        return targets.map((t) => t.id).filter((id) => requested.has(id));
+    }
+    return [];
+}
+function detectionLabel(status) {
+    if (status === "cli")
+        return "detected (CLI)";
+    if (status === "config")
+        return "detected (config)";
+    return "not detected";
+}
+function printPlans(plans) {
+    console.log("\nPlanned changes:");
+    for (const plan of plans) {
+        console.log(`  • ${plan.displayName} [${detectionLabel(plan.detection)}]`);
+        console.log(`      ${plan.summary}`);
+        if (plan.method === "manual" && plan.manualInstructions) {
+            for (const line of plan.manualInstructions.split("\n")) {
+                console.log(`      ${line}`);
+            }
+        }
+    }
+}
+function printResults(results) {
+    console.log("\nResults:");
+    for (const result of results) {
+        console.log(`  • ${result.displayName}: ${result.outcome} — ${result.detail}`);
+    }
+}
+export async function runRegister(argv, deps = {}) {
+    const parsed = parseRegisterArgs(argv);
+    if (parsed.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (parsed.unknownFlags.length > 0) {
+        console.error(`[onto register] Unknown option(s): ${parsed.unknownFlags.join(", ")}`);
+        console.error(USAGE);
+        return 1;
+    }
+    if (parsed.invalidHosts.length > 0) {
+        console.error(`[onto register] Unknown host(s): ${parsed.invalidHosts.join(", ")}. ` +
+            `Valid: ${ALL_HOST_IDS.join(", ")}`);
+        return 1;
+    }
+    const targets = deps.targets ??
+        getDefaultHostTargets(parsed.claudeConfigDir ? { claudeConfigDir: parsed.claudeConfigDir } : {});
+    const isTty = deps.isTty ?? Boolean(process.stdin.isTTY);
+    if (parsed.list) {
+        console.log("Host detection:");
+        for (const target of targets) {
+            console.log(`  • ${target.displayName}: ${detectionLabel(target.detect())}`);
+        }
+        return 0;
+    }
+    const entry = {
+        name: parsed.name,
+        command: parsed.command,
+        args: ["mcp"],
+    };
+    // Determine which hosts to register.
+    let selected = resolveSelection(parsed, targets);
+    const selectionGivenByFlag = parsed.hosts !== undefined;
+    if (!selectionGivenByFlag) {
+        if (!isTty) {
+            console.error("[onto register] No hosts specified. Use --hosts <ids> or --all " +
+                "(interactive selection requires a terminal).");
+            return 1;
+        }
+        const defaults = targets.filter((t) => t.detect() !== "absent").map((t) => t.id);
+        const chosen = await promptMultiSelect("Select hosts to register onto with:", targets.map((t) => ({
+            id: t.id,
+            label: t.displayName,
+            detail: detectionLabel(t.detect()),
+        })), defaults.length > 0 ? defaults : targets.map((t) => t.id));
+        selected = targets.map((t) => t.id).filter((id) => chosen.includes(id));
+    }
+    if (selected.length === 0) {
+        console.error("[onto register] No hosts selected. Nothing to do.");
+        return 1;
+    }
+    const selectedTargets = targets.filter((t) => selected.includes(t.id));
+    const options = { force: parsed.force, dryRun: parsed.dryRun };
+    const plans = selectedTargets.map((t) => t.plan(entry, options));
+    printPlans(plans);
+    if (parsed.dryRun) {
+        console.log("\n(dry-run) No changes were written.");
+        return 0;
+    }
+    // Confirmation gate (write-before-confirm governance, product-locality §5.3 spirit).
+    if (!parsed.yes) {
+        if (!isTty) {
+            console.error("\n[onto register] Refusing to write without confirmation. Re-run with --yes.");
+            return 1;
+        }
+        const proceed = await promptYesNo("\nApply these changes?", true);
+        if (!proceed) {
+            console.log("Aborted. No changes written.");
+            return 0;
+        }
+    }
+    const results = [];
+    for (const target of selectedTargets) {
+        results.push(await target.apply(entry, options));
+    }
+    printResults(results);
+    const failed = results.filter((r) => r.outcome === "failed");
+    const manual = results.filter((r) => r.outcome === "manual");
+    if (manual.length > 0) {
+        console.log(`\nNote: ${manual.length} host(s) need a manual step (CLI not found) — see above.`);
+    }
+    if (failed.length > 0) {
+        console.error(`\n${failed.length} host(s) failed to register.`);
+        return 1;
+    }
+    console.log("\nDone. Restart the host app(s) to pick up the onto MCP server.");
+    return 0;
+}

package/dist/core-runtime/onboard/types.js

@@ -0,0 +1,27 @@
+/**
+ * Host MCP registration types.
+ *
+ * `onto register` writes the onto MCP server into each supported host's own
+ * configuration so the host launches `onto mcp` as a stdio MCP server. This is
+ * onboarding/integration, not onto runtime data: targets write to host-owned
+ * config (user home), never to `{product}/.onto/`.
+ */
+export const ALL_HOST_IDS = [
+    "claude-code",
+    "codex",
+    "claude-desktop",
+    "cursor",
+];
+/** True when `command` and `args` of an existing host entry already match. */
+export function entryMatches(existing, entry) {
+    if (!existing || typeof existing !== "object")
+        return false;
+    if (existing.command !== entry.command)
+        return false;
+    const existingArgs = existing.args;
+    if (!Array.isArray(existingArgs))
+        return entry.args.length === 0;
+    if (existingArgs.length !== entry.args.length)
+        return false;
+    return existingArgs.every((value, index) => value === entry.args[index]);
+}