@matterailab/orbcode 0.2.1 → 0.2.3

package/dist/commands/mcp.js

@@ -0,0 +1,266 @@
+import { addMcpServer, configPathForScope, loadMcpConfig, removeMcpServerAnyScope, } from "../mcp/config.js";
+/**
+ * `orbcode mcp` subcommand — manage MCP servers from the command line, like
+ * Claude Code's `claude mcp add/remove/list`.
+ *
+ * Usage:
+ *   orbcode mcp add <name> <command> [args...]                    stdio (default)
+ *   orbcode mcp add --transport http <name> <url>                  http
+ *   orbcode mcp add --transport sse <name> <url>                   sse
+ *   orbcode mcp add -s <scope> -e KEY=value ... <name> ...         with scope/env
+ *   orbcode mcp add --header KEY=value ... <name> <url>            http/sse headers
+ *   orbcode mcp remove <name>                                      remove from any scope
+ *   orbcode mcp list                                               list all servers
+ *
+ * Flags:
+ *   -s, --scope <user|project|local>   config scope (default: project)
+ *   -t, --transport <stdio|http|sse>   transport type (default: stdio)
+ *   -e, --env KEY=value                environment variable (repeatable, stdio)
+ *       --header KEY=value             HTTP header (repeatable, http/sse)
+ *       --oauth                        enable OAuth for http/sse
+ *       --oauth-scope <scope>          OAuth scope (implies --oauth)
+ */
+const VALID_SCOPES = ["user", "project", "local"];
+const VALID_TRANSPORTS = ["stdio", "http", "sse"];
+/** Parse a KEY=value pair from a flag argument. */
+function parseKeyValue(arg) {
+    const idx = arg.indexOf("=");
+    if (idx === -1)
+        throw new Error(`Expected KEY=value, got "${arg}"`);
+    return [arg.slice(0, idx), arg.slice(idx + 1)];
+}
+/** Print usage and exit. */
+function printMcpHelp() {
+    console.log(`orbcode mcp — manage MCP servers
+
+Usage:
+  orbcode mcp add [options] <name> <command> [args...]    add a stdio server
+  orbcode mcp add [options] --transport http <name> <url>  add an http server
+  orbcode mcp add [options] --transport sse <name> <url>   add an sse server
+  orbcode mcp remove <name>                                remove a server
+  orbcode mcp list                                         list all servers
+
+Options:
+  -s, --scope <user|project|local>   config scope (default: project)
+  -t, --transport <stdio|http|sse>   transport type (default: stdio)
+  -e, --env KEY=value                environment variable (repeatable, stdio)
+      --header KEY=value             HTTP header (repeatable, http/sse)
+      --oauth                        enable OAuth for http/sse
+      --oauth-scope <scope>          OAuth scope (implies --oauth)
+
+Scopes:
+  project   .mcp.json in the current directory (shared, checked into git)
+  user      ~/.orbcode/settings.json (applies to all projects on this machine)
+  local     .orbcode/settings.json (per-project, per-machine, not checked in)`);
+}
+/** Handle `orbcode mcp ...`. Returns the process exit code. */
+export async function runMcpCommand(args) {
+    const [subcommand, ...rest] = args;
+    switch (subcommand) {
+        case "add":
+            return runAdd(rest);
+        case "remove":
+        case "rm":
+            return runRemove(rest);
+        case "list":
+        case "ls":
+            return runList(rest);
+        case "help":
+        case "--help":
+        case "-h":
+            printMcpHelp();
+            return 0;
+        default:
+            console.error(`Unknown mcp subcommand: "${subcommand ?? ""}". Try: orbcode mcp help`);
+            return 1;
+    }
+}
+/** Parse the flags shared by add (scope, transport, env, headers, oauth). */
+function parseAddFlags(args) {
+    let scope = "project";
+    let transport = "stdio";
+    const env = {};
+    const headers = {};
+    let oauth = false;
+    const positional = [];
+    // Flags must come before the server name. Once we hit the first positional
+    // (the server name), everything after it — including args that look like
+    // flags (-y, -f, --foo) — becomes the server's command/args. This matches
+    // Claude Code and lets stdio servers take their own flags.
+    let sawPositional = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (sawPositional) {
+            // A "--" immediately after the server name is the separator between
+            // orbcode's flags and the server's command (e.g. `add name -- npx`),
+            // matching Claude Code's `claude mcp add <name> -- <command>`. Consume
+            // it so it isn't mistaken for the command. A later "--" is kept as a
+            // literal arg for the server command.
+            if (arg === "--" && positional.length === 1)
+                continue;
+            positional.push(arg);
+            continue;
+        }
+        if (arg === "-s" || arg === "--scope") {
+            const value = args[++i];
+            if (!value || !VALID_SCOPES.includes(value)) {
+                throw new Error(`Invalid scope "${value ?? ""}". Valid: ${VALID_SCOPES.join(", ")}`);
+            }
+            scope = value;
+        }
+        else if (arg === "-t" || arg === "--transport") {
+            const value = args[++i];
+            if (!value || !VALID_TRANSPORTS.includes(value)) {
+                throw new Error(`Invalid transport "${value ?? ""}". Valid: ${VALID_TRANSPORTS.join(", ")}`);
+            }
+            transport = value;
+        }
+        else if (arg === "-e" || arg === "--env") {
+            const value = args[++i];
+            if (!value)
+                throw new Error("Missing value for --env");
+            const [k, v] = parseKeyValue(value);
+            env[k] = v;
+        }
+        else if (arg === "--header") {
+            const value = args[++i];
+            if (!value)
+                throw new Error("Missing value for --header");
+            const [k, v] = parseKeyValue(value);
+            headers[k] = v;
+        }
+        else if (arg === "--oauth") {
+            oauth = true;
+        }
+        else if (arg === "--oauth-scope") {
+            const value = args[++i];
+            if (!value)
+                throw new Error("Missing value for --oauth-scope");
+            oauth = { scope: value };
+        }
+        else if (arg === "--") {
+            // Explicit separator: everything after is positional.
+            sawPositional = true;
+        }
+        else if (arg.startsWith("-") && arg.length > 1) {
+            throw new Error(`Unknown flag: ${arg}. Put flags before the server name, or use -- to separate.`);
+        }
+        else {
+            positional.push(arg);
+            sawPositional = true;
+        }
+    }
+    return { scope, transport, env, headers, oauth, positional };
+}
+/** `orbcode mcp add` — build a server config from flags and write it. */
+function runAdd(args) {
+    let parsed;
+    try {
+        parsed = parseAddFlags(args);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const { scope, transport, env, headers, oauth, positional } = parsed;
+    if (positional.length === 0) {
+        console.error("Missing server name. Usage: orbcode mcp add <name> <command> [args...]");
+        return 1;
+    }
+    const [name, ...rest] = positional;
+    let config;
+    if (transport === "http" || transport === "sse") {
+        if (rest.length === 0) {
+            console.error(`Missing URL for ${transport} transport. Usage: orbcode mcp add -t ${transport} <name> <url>`);
+            return 1;
+        }
+        const url = rest[0];
+        const cfg = { type: transport, url };
+        if (Object.keys(headers).length > 0)
+            cfg.headers = headers;
+        if (oauth !== false)
+            cfg.oauth = oauth;
+        config = cfg;
+    }
+    else {
+        // stdio
+        if (rest.length === 0) {
+            console.error("Missing command for stdio transport. Usage: orbcode mcp add <name> <command> [args...]");
+            return 1;
+        }
+        const [command, ...cmdArgs] = rest;
+        const cfg = { type: "stdio", command: command };
+        if (cmdArgs.length > 0)
+            cfg.args = cmdArgs;
+        if (Object.keys(env).length > 0)
+            cfg.env = env;
+        config = cfg;
+    }
+    let detail;
+    if (transport === "http" || transport === "sse") {
+        const cfg = config;
+        detail = `${transport} ${cfg.url}`;
+    }
+    else {
+        const cfg = config;
+        detail = `stdio ${cfg.command}${cfg.args?.length ? " " + cfg.args.join(" ") : ""}`;
+    }
+    try {
+        addMcpServer(process.cwd(), name, config, scope);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const filePath = configPathForScope(process.cwd(), scope);
+    console.log(`Added ${transport === "http" || transport === "sse" ? transport.toUpperCase() : "stdio"} MCP server ${name}`);
+    if (transport === "http" || transport === "sse") {
+        console.log(`  URL: ${config.url}`);
+    }
+    console.log(`  Scope: ${scope}`);
+    console.log(`  File modified: ${filePath}`);
+    return 0;
+}
+/** `orbcode mcp remove <name>` — remove from whichever scope it's in. */
+function runRemove(args) {
+    if (args.length === 0) {
+        console.error("Missing server name. Usage: orbcode mcp remove <name>");
+        return 1;
+    }
+    const name = args[0];
+    const scope = removeMcpServerAnyScope(process.cwd(), name);
+    if (!scope) {
+        console.error(`MCP server "${name}" not found in any scope.`);
+        return 1;
+    }
+    const filePath = configPathForScope(process.cwd(), scope);
+    console.log(`Removed MCP server "${name}" from ${scope} scope.`);
+    console.log(`  File modified: ${filePath}`);
+    return 0;
+}
+/** `orbcode mcp list` — print all configured servers with their scope + status. */
+function runList(_args) {
+    const { servers } = loadMcpConfig(process.cwd());
+    const names = Object.keys(servers).sort();
+    if (names.length === 0) {
+        console.log("No MCP servers configured.");
+        console.log("Add one with: orbcode mcp add <name> <command> [args...]");
+        return 0;
+    }
+    for (const name of names) {
+        const cfg = servers[name];
+        const scope = cfg.scope;
+        let detail;
+        if (cfg.type === "http" || cfg.type === "sse") {
+            detail = `${cfg.type} ${cfg.url}`;
+        }
+        else {
+            // stdio (type undefined or "stdio")
+            const cmd = cfg.command;
+            const args = cfg.args ?? [];
+            detail = `stdio ${cmd}${args.length ? " " + args.join(" ") : ""}`;
+        }
+        console.log(`  ${name.padEnd(20)} ${scope.padEnd(8)} ${detail}`);
+    }
+    return 0;
+}

package/dist/config/settings.js

@@ -18,6 +18,8 @@ const SETTINGS_KEYS = [
     "baseUrl",
     "apiKey",
     "env",
+    "enabledMcpServers",
+    "disabledMcpServers",
 ];
 export function getConfigDir() {
     return process.env.MATTERAI_CONFIG_DIR || path.join(os.homedir(), ".orbcode");
@@ -150,6 +152,12 @@ export function loadSettings() {
         if (Array.isArray(fileSettings.customModels)) {
             customModels.push(...fileSettings.customModels);
         }
+        // MCP servers: merge across scopes (local overrides project overrides
+        // user on name collisions). The MCP config layer also reads .mcp.json;
+        // settings.json mcpServers are the per-user/per-machine override path.
+        if (fileSettings.mcpServers && typeof fileSettings.mcpServers === "object") {
+            settings.mcpServers = { ...(settings.mcpServers ?? {}), ...fileSettings.mcpServers };
+        }
     }
     if (customModels.length > 0) {
         settings.customModels = customModels;
@@ -210,3 +218,22 @@ export function saveSettings(settings) {
     };
     fs.writeFileSync(getConfigPath(), JSON.stringify(toPersist, null, "\t") + "\n", { mode: 0o600 });
 }
+/**
+ * Persist the enabled/disabled MCP server lists to the local project
+ * settings.json (`.orbcode/settings.json`). These are per-project approval
+ * decisions, so they live in the local scope, not in config.json.
+ */
+export function saveMcpApproval(cwd, enabled, disabled) {
+    const settingsPath = path.join(cwd, ".orbcode", "settings.json");
+    let existing = {};
+    try {
+        existing = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        // file may not exist yet
+    }
+    existing.enabledMcpServers = [...new Set(enabled)];
+    existing.disabledMcpServers = [...new Set(disabled)];
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(existing, null, "\t") + "\n", { mode: 0o600 });
+}

package/dist/core/agent.js

@@ -9,6 +9,8 @@ import { walkFiles } from "../tools/executors/listFiles.js";
 import { previewFileChange } from "../tools/executors/files.js";
 import { getSessionFilePath, saveSession } from "./sessions.js";
 import { HookRunner } from "./hooks.js";
+import { loadMemoryFiles } from "../memory/loader.js";
+import { loadSkills } from "../skills/loader.js";
 const MAX_STEPS_PER_TURN = 50;
 const RESULT_PREVIEW_LINES = 6;
 function detectRepo(cwd) {
@@ -77,6 +79,8 @@ export class Agent {
     title = "";
     createdAt = new Date().toISOString();
     hooks;
+    /** MCP server manager (may be undefined when MCP is disabled). */
+    mcp;
     /** SessionStart fires once, lazily, before the first turn of this instance. */
     sessionStarted = false;
     /** carries SessionStart additionalContext into the first user message */
@@ -107,7 +111,13 @@ export class Agent {
             this.firstMessageSent = this.messages.length > 0;
         }
         this.sessionApproveEdits = options.autoApproveEdits;
-        this.systemPrompt = buildSystemPrompt(options.cwd);
+        this.mcp = options.mcp;
+        // Build the system prompt with AGENTS.md memory files and the skills
+        // catalog injected, so the model sees project/user instructions and
+        // knows which skills it can invoke.
+        const memoryFiles = loadMemoryFiles(options.cwd);
+        const skills = loadSkills(options.cwd);
+        this.systemPrompt = buildSystemPrompt(options.cwd, { memoryFiles, skills });
         this.client = createLLMClient({
             token: options.token,
             modelId: options.modelId,
@@ -353,15 +363,26 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
     async endSession(reason) {
         // Let in-flight Notification hooks settle before the final SessionEnd.
         await this.awaitBackground(3000);
-        if (!this.hooks.hasHooks("SessionEnd"))
-            return;
+        if (this.hooks.hasHooks("SessionEnd")) {
+            try {
+                await this.hooks.run("SessionEnd", { reason });
+            }
+            catch {
+                // a SessionEnd hook must never prevent the app from exiting
+            }
+        }
+        // Tear down MCP server connections so child processes / sockets don't leak.
         try {
-            await this.hooks.run("SessionEnd", { reason });
+            await this.mcp?.stop();
         }
         catch {
-            // a SessionEnd hook must never prevent the app from exiting
+            // best-effort
         }
     }
+    /** The MCP manager (for the TUI's /mcp command and approval flow). */
+    get mcpManager() {
+        return this.mcp;
+    }
     /** Summarize the conversation so far and replace history with the summary. */
     async compact() {
         const { onEvent } = this.options.callbacks;
@@ -452,7 +473,7 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
         let reasoningDetails;
         const toolCallsByIndex = new Map();
         let nextSyntheticIndex = 10000;
-        const stream = this.client.createMessage(this.systemPrompt, this.outgoingMessages(), getActiveTools(), signal);
+        const stream = this.client.createMessage(this.systemPrompt, this.outgoingMessages(), getActiveTools(this.mcp), signal);
         for await (const chunk of stream) {
             if (signal.aborted)
                 throw new DOMException("aborted", "AbortError");
@@ -663,7 +684,7 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                     this.sessionApproveCommands = true;
             }
         }
-        const result = await executeTool(toolCall.name, args, this.toolContext());
+        const result = await executeTool(toolCall.name, args, this.toolContext(), this.mcp);
         // PostToolUse can feed extra context (or a block reason) back to the
         // model. PreToolUse additionalContext is delivered here too.
         let resultText = result.text;

package/dist/headless.js

@@ -1,6 +1,7 @@
 import { getModel, isValidAxonModel, usesAiSdk } from "./api/models.js";
 import { getAuthToken, getPendingProjectHooks, loadSettings } from "./config/settings.js";
 import { Agent } from "./core/agent.js";
+import { McpManager } from "./mcp/manager.js";
 /** Non-interactive `orbcode -p "prompt"` mode: prints the final response to stdout. */
 export async function runHeadless(prompt, yolo) {
     const settings = loadSettings();
@@ -28,6 +29,21 @@ export async function runHeadless(prompt, yolo) {
         process.stderr.write(`note: ${pendingHooks.commands.length} project hook(s) in .orbcode/settings.json are untrusted and were skipped. ` +
             `Trust them in an interactive session, or set MATTERAI_TRUST_PROJECT_HOOKS=1.\n`);
     }
+    // Start MCP servers. In headless mode there's no interactive approval, so
+    // project-scope servers are only connected if they were previously approved
+    // (persisted in .orbcode/settings.json). Unapproved project servers are
+    // skipped with a note, matching the project-hooks behavior.
+    const mcp = new McpManager(process.cwd(), settings.disabledMcpServers ?? [], settings.enabledMcpServers ?? []);
+    const mcpSnapshot = await mcp.start();
+    const pendingMcp = mcp.getPendingApproval();
+    if (pendingMcp.length > 0) {
+        process.stderr.write(`note: ${pendingMcp.length} project MCP server(s) in .mcp.json are unapproved and were skipped. ` +
+            `Approve them in an interactive session with /mcp.\n`);
+    }
+    const connectedMcp = mcpSnapshot.servers.filter((s) => s.status === "connected").length;
+    if (connectedMcp > 0) {
+        process.stderr.write(`MCP: ${connectedMcp}/${mcpSnapshot.servers.length} server(s) connected.\n`);
+    }
     let exitCode = 0;
     // Only the final content is printed: either the attempt_completion result
     // or, failing that, the last assistant text. Intermediate text and tool
@@ -46,6 +62,7 @@ export async function runHeadless(prompt, yolo) {
         autoApproveEdits: yolo,
         autoApproveSafeCommands: yolo,
         hooks: settings.hooks,
+        mcp,
         callbacks: {
             onEvent: (event) => {
                 switch (event.type) {
@@ -84,6 +101,7 @@ export async function runHeadless(prompt, yolo) {
     });
     await agent.runTurn(prompt);
     await agent.endSession("other");
+    await mcp.stop().catch(() => { });
     const finalContent = completionResult || lastText || textBuffer;
     if (finalContent) {
         process.stdout.write(finalContent.trimEnd() + "\n");

package/dist/index.js

@@ -3,6 +3,7 @@ import { render } from "ink";
 import { PRODUCT_NAME, VERSION } from "./branding.js";
 import { App } from "./ui/App.js";
 import { runHeadless } from "./headless.js";
+import { runMcpCommand } from "./commands/mcp.js";
 import { loadSessionById } from "./core/sessions.js";
 import { clearUpdateCache, compareVersions, fetchLatestNpmVersion, getGlobalInstallRoot, getUpdateInfo, isGlobalInstall, runNpmUpdate, } from "./utils/updateCheck.js";
 const PACKAGE_NAME = "@matterailab/orbcode";
@@ -15,6 +16,9 @@ Usage:
   orbcode login           sign in to MatterAI
   orbcode update          install the latest version from npm
   orbcode update --force  force a global install even if this CLI doesn't look global
+  orbcode mcp add ...     add an MCP server (see: orbcode mcp help)
+  orbcode mcp remove ...  remove an MCP server
+  orbcode mcp list        list configured MCP servers
   orbcode -p "<prompt>"   run a single prompt non-interactively (prints only the final response)
   orbcode -p "…" --yolo   non-interactive with auto-approved edits/commands
   orbcode --model <id>    use a specific model for this run
@@ -86,6 +90,11 @@ async function main() {
         const code = await runUpdate(force);
         process.exit(code);
     }
+    // `orbcode mcp ...` — manage MCP servers from the command line (add/remove/list).
+    if (args[0] === "mcp") {
+        const code = await runMcpCommand(args.slice(1));
+        process.exit(code);
+    }
     const model = takeFlagValue(args, "model") ?? takeFlagValue(args, "m");
     if (model) {
         // loadSettings() treats MATTERAI_MODEL as the highest-precedence override,