@matterailab/orbcode 0.2.1 → 0.2.3

package/dist/mcp/auth.js

@@ -0,0 +1,289 @@
+import * as http from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import open from "open";
+import { ClientCredentialsProvider, PrivateKeyJwtProvider, } from "@modelcontextprotocol/sdk/client/auth-extensions.js";
+import { auth, } from "@modelcontextprotocol/sdk/client/auth.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { getConfigDir } from "../config/settings.js";
+/**
+ * MCP OAuth support.
+ *
+ * Remote MCP servers (http/sse) often require OAuth. The SDK ships a full
+ * OAuth client (RFC 9728 discovery + RFC 8414 metadata + PKCE + dynamic client
+ * registration + token refresh), gated behind an `OAuthClientProvider` that
+ * persists per-server state. This module provides:
+ *
+ *   - `FileOAuthProvider`: a filesystem-backed provider that stores tokens,
+ *     client info, code verifiers, and discovery state per server under
+ *     `~/.orbcode/mcp-auth/<server>.json`.
+ *   - `startCallbackServer`: a one-shot loopback HTTP server that receives the
+ *     OAuth redirect and resolves with the authorization code.
+ *   - `buildAuthProvider`: turns an `McpOAuthConfig` into an `OAuthClientProvider`
+ *     (interactive auth-code flow, or M2M client_credentials / private_key_jwt).
+ *   - `connectWithAuth`: wraps the transport connect + auth retry loop.
+ */
+const CLIENT_METADATA = {
+    client_name: "OrbCode CLI",
+    redirect_uris: [], // filled in per-callback-port at runtime
+    grant_types: ["authorization_code", "refresh_token"],
+    token_endpoint_auth_method: "none",
+    scope: "",
+};
+/** Directory holding per-server OAuth state files. */
+function authDir() {
+    return path.join(getConfigDir(), "mcp-auth");
+}
+/** Path to a server's persistent OAuth store. */
+function authFilePath(serverName) {
+    return path.join(authDir(), `${serverName}.json`);
+}
+/** Read a server's OAuth store (or undefined if none). */
+function readAuthStore(serverName) {
+    try {
+        return JSON.parse(fs.readFileSync(authFilePath(serverName), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write a server's OAuth store (best-effort). */
+function writeAuthStore(serverName, store) {
+    try {
+        fs.mkdirSync(authDir(), { recursive: true });
+        fs.writeFileSync(authFilePath(serverName), JSON.stringify(store, null, "\t") + "\n", {
+            mode: 0o600,
+        });
+    }
+    catch {
+        // best-effort; auth will just re-prompt next time
+    }
+}
+/** A filesystem-backed OAuthClientProvider for one MCP server. */
+class FileOAuthProvider {
+    serverName;
+    callbackPort;
+    scope;
+    store;
+    /** The authorization URL captured from the last redirectToAuthorization call. */
+    authUrl;
+    /** Resolved by redirectToAuthorization; awaited by the connect loop. */
+    codeResolve;
+    constructor(serverName, callbackPort, scope) {
+        this.serverName = serverName;
+        this.callbackPort = callbackPort;
+        this.scope = scope;
+        this.store = readAuthStore(serverName) ?? {};
+    }
+    get redirectUrl() {
+        return `http://localhost:${this.callbackPort}/callback`;
+    }
+    get clientMetadata() {
+        return { ...CLIENT_METADATA, redirect_uris: [this.redirectUrl], scope: this.scope ?? "" };
+    }
+    clientInformation() {
+        return this.store.clientInformation;
+    }
+    saveClientInformation(info) {
+        this.store.clientInformation = info;
+        writeAuthStore(this.serverName, this.store);
+    }
+    tokens() {
+        return this.store.tokens;
+    }
+    saveTokens(tokens) {
+        this.store.tokens = tokens;
+        writeAuthStore(this.serverName, this.store);
+    }
+    saveCodeVerifier(verifier) {
+        this.store.codeVerifier = verifier;
+        writeAuthStore(this.serverName, this.store);
+    }
+    codeVerifier() {
+        if (!this.store.codeVerifier)
+            throw new Error("No PKCE code verifier stored.");
+        return this.store.codeVerifier;
+    }
+    saveDiscoveryState(state) {
+        this.store.discoveryState = state;
+        writeAuthStore(this.serverName, this.store);
+    }
+    discoveryState() {
+        return this.store.discoveryState;
+    }
+    invalidateCredentials(scope) {
+        if (scope === "all")
+            this.store = {};
+        else if (scope === "client")
+            delete this.store.clientInformation;
+        else if (scope === "tokens")
+            delete this.store.tokens;
+        else if (scope === "verifier")
+            delete this.store.codeVerifier;
+        else if (scope === "discovery")
+            delete this.store.discoveryState;
+        writeAuthStore(this.serverName, this.store);
+    }
+    /** Open the user's browser to the authorization URL and capture it so the
+     *  caller can surface it in the TUI (with copy + paste fallback). */
+    redirectToAuthorization(authorizationUrl) {
+        this.authUrl = authorizationUrl.toString();
+        void open(this.authUrl).catch(() => {
+            // best-effort; the user can copy the URL from the TUI
+        });
+    }
+    /** The authorization URL captured from the last redirect (for TUI display). */
+    getAuthUrl() {
+        return this.authUrl;
+    }
+    /** Called by the callback server when the OAuth redirect lands. */
+    resolveCode(code) {
+        this.codeResolve?.(code);
+    }
+    /** Await the authorization code from the browser redirect or a manual paste. */
+    waitForCode() {
+        return new Promise((resolve) => {
+            this.codeResolve = resolve;
+        });
+    }
+}
+/** Start a one-shot loopback HTTP server to receive the OAuth redirect. */
+function startCallbackServer(port, onCode) {
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+        if (url.pathname !== "/callback") {
+            res.writeHead(404).end("not found");
+            return;
+        }
+        const code = url.searchParams.get("code");
+        const error = url.searchParams.get("error");
+        if (code) {
+            onCode(code);
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end("<h1>Authorized</h1><p>You can close this tab and return to OrbCode.</p>");
+        }
+        else if (error) {
+            res.writeHead(400, { "Content-Type": "text/html" });
+            res.end(`<h1>Authorization failed</h1><p>${error}</p>`);
+        }
+        else {
+            res.writeHead(400, { "Content-Type": "text/html" });
+            res.end("<h1>Missing code</h1>");
+        }
+        // Close after responding so the port is freed immediately.
+        server.close();
+    });
+    server.listen(port, "127.0.0.1");
+    return server;
+}
+/** Pick an ephemeral loopback port for the callback server. */
+function ephemeralPort() {
+    // Bind to port 0 and read back the assigned port, then close immediately.
+    const probe = http.createServer().listen(0, "127.0.0.1");
+    const addr = probe.address();
+    probe.close();
+    return typeof addr === "object" && addr ? addr.port : 8765;
+}
+/** Build an OAuthClientProvider from an McpOAuthConfig. Returns the provider
+ *  plus a callback-port hint (for the interactive flow). */
+export function buildAuthProvider(serverName, oauth) {
+    // M2M: client_credentials grant (no browser).
+    if (typeof oauth === "object" && "grantType" in oauth && oauth.grantType === "client_credentials") {
+        return {
+            provider: new ClientCredentialsProvider({
+                clientId: oauth.clientId,
+                clientSecret: oauth.clientSecret,
+                scope: oauth.scope,
+                clientName: "OrbCode CLI",
+            }),
+        };
+    }
+    // M2M: private_key_jwt assertion (no browser).
+    if (typeof oauth === "object" && "grantType" in oauth && oauth.grantType === "private_key_jwt") {
+        return {
+            provider: new PrivateKeyJwtProvider({
+                clientId: oauth.clientId,
+                privateKey: oauth.privateKey,
+                algorithm: oauth.algorithm,
+                scope: oauth.scope,
+                clientName: "OrbCode CLI",
+            }),
+        };
+    }
+    // Interactive authorization-code flow (browser redirect).
+    const scope = typeof oauth === "object" ? oauth.scope : undefined;
+    const port = ephemeralPort();
+    return { provider: new FileOAuthProvider(serverName, port, scope), callbackPort: port };
+}
+/** True if the config requests OAuth (vs. static headers). */
+export function hasOAuth(config) {
+    return config.oauth !== undefined && config.oauth !== false;
+}
+/** True if a server config is http/sse with OAuth enabled. */
+export function isOAuthConfig(config) {
+    return (config.type === "http" || config.type === "sse") && hasOAuth(config);
+}
+/** True if this server has persisted OAuth tokens (i.e. already authenticated). */
+export function hasStoredAuth(serverName) {
+    const store = readAuthStore(serverName);
+    return Boolean(store && store.tokens && store.tokens.access_token);
+}
+/** Create an http/sse transport with an auth provider. The `authenticate()`
+ *  function uses the standalone `auth()` orchestrator to obtain tokens BEFORE
+ *  the transport is started (by client.connect()). This avoids the
+ *  "StreamableHTTPClientTransport already started" error that occurs when
+ *  transport.start() is called both by authenticate() and by client.connect().
+ *
+ *  When `intercept` is provided, the caller controls how the auth URL is shown
+ *  and how the code is obtained (TUI with copy + paste fallback). When omitted,
+ *  the flow auto-waits for the loopback callback server (headless mode). */
+export function createAuthTransport(serverName, url, kind, oauth, requestInit, intercept) {
+    const { provider, callbackPort } = buildAuthProvider(serverName, oauth);
+    const fileProvider = provider instanceof FileOAuthProvider ? provider : undefined;
+    const transport = kind === "http"
+        ? new StreamableHTTPClientTransport(url, { authProvider: provider, requestInit })
+        : new SSEClientTransport(url, { authProvider: provider, requestInit });
+    const authenticate = async () => {
+        // M2M providers (ClientCredentialsProvider, PrivateKeyJwtProvider) don't
+        // need a browser — the auth() call handles token acquisition directly.
+        if (!fileProvider) {
+            const result = await auth(provider, { serverUrl: url });
+            if (result === "REDIRECT") {
+                throw new Error("M2M provider requested a browser redirect — unexpected.");
+            }
+            return;
+        }
+        // Interactive flow: use the standalone auth() orchestrator.
+        // If we already have valid tokens, auth() returns AUTHORIZED immediately.
+        // If not, it returns REDIRECT (after calling redirectToAuthorization,
+        // which opens the browser and captures the URL).
+        const serverUrlStr = url.toString();
+        const result = await auth(provider, { serverUrl: serverUrlStr });
+        if (result === "AUTHORIZED")
+            return; // tokens are valid
+        // REDIRECT: the provider's redirectToAuthorization was called, which
+        // captured the auth URL and opened the browser. Surface it to the TUI.
+        const authUrl = fileProvider.getAuthUrl();
+        if (intercept && authUrl)
+            intercept.onAuthUrl(authUrl);
+        // Start the callback server (the browser redirect may arrive here).
+        const callbackServer = startCallbackServer(callbackPort, (code) => fileProvider.resolveCode(code));
+        try {
+            let code;
+            if (intercept) {
+                // Interactive: race the callback against a manual paste.
+                code = await Promise.race([intercept.getCode(), fileProvider.waitForCode()]);
+            }
+            else {
+                code = await fileProvider.waitForCode();
+            }
+            // Exchange the code for tokens via the standalone auth() call.
+            await auth(provider, { serverUrl: serverUrlStr, authorizationCode: code });
+        }
+        finally {
+            callbackServer.close();
+        }
+    };
+    return { transport, authenticate, provider: fileProvider };
+}

package/dist/mcp/client.js

@@ -0,0 +1,132 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { VERSION } from "../branding.js";
+import { createAuthTransport, hasOAuth } from "./auth.js";
+/** Build the SDK transport for a server config. For http/sse servers with an
+ *  `oauth` block, returns an auth-aware transport whose `authenticate()` runs
+ *  the OAuth flow (browser redirect or M2M) before `start()`. */
+function buildTransport(name, config, intercept) {
+    if (config.type === "sse") {
+        if (hasOAuth(config)) {
+            const auth = createAuthTransport(name, new URL(config.url), "sse", config.oauth, {
+                headers: config.headers ?? {},
+            }, intercept);
+            return { transport: auth.transport, authenticate: auth.authenticate };
+        }
+        return {
+            transport: new SSEClientTransport(new URL(config.url), {
+                requestInit: { headers: config.headers ?? {} },
+            }),
+        };
+    }
+    if (config.type === "http") {
+        if (hasOAuth(config)) {
+            const auth = createAuthTransport(name, new URL(config.url), "http", config.oauth, {
+                headers: config.headers ?? {},
+            }, intercept);
+            return { transport: auth.transport, authenticate: auth.authenticate };
+        }
+        return {
+            transport: new StreamableHTTPClientTransport(new URL(config.url), {
+                requestInit: { headers: config.headers ?? {} },
+            }),
+        };
+    }
+    // stdio (default)
+    return {
+        transport: new StdioClientTransport({
+            command: config.command,
+            args: config.args ?? [],
+            env: config.env,
+            cwd: config.cwd,
+            stderr: "pipe",
+        }),
+    };
+}
+const CONNECT_TIMEOUT_MS = 30_000;
+const CLIENT_INFO = { name: "orbcode", version: VERSION };
+/** Connect to one MCP server and enumerate its tools. The optional
+ *  `authIntercept` lets the caller surface the OAuth URL in the TUI and
+ *  provide the auth code (from the callback or a manual paste). */
+export async function connectMcpServer(name, config, authIntercept) {
+    const { transport, authenticate } = buildTransport(name, config, authIntercept);
+    const client = new Client(CLIENT_INFO, { capabilities: {} });
+    // For OAuth servers, run the auth flow (browser redirect or M2M) before
+    // connecting. This may open a browser and block until the user authorizes.
+    if (authenticate) {
+        await withTimeout(authenticate(), CONNECT_TIMEOUT_MS, `MCP server "${name}" auth timed out`);
+    }
+    // Wrap connect in a timeout so a hung server doesn't block startup.
+    await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `MCP server "${name}" timed out`);
+    const tools = await listServerTools(name, client);
+    return {
+        client,
+        tools,
+        close: async () => {
+            try {
+                await transport.close();
+            }
+            catch {
+                // best-effort
+            }
+            try {
+                await client.close();
+            }
+            catch {
+                // best-effort
+            }
+        },
+    };
+}
+/** Enumerate tools from a connected client, namespaced as mcp__<server>__<tool>. */
+export async function listServerTools(server, client) {
+    const result = await client.listTools();
+    return (result.tools ?? []).map((tool) => ({
+        name: `mcp__${server}__${tool.name}`,
+        originalName: tool.name,
+        server,
+        description: tool.description,
+        inputSchema: tool.inputSchema ?? { type: "object", properties: {} },
+    }));
+}
+/** Call a tool on a connected client and return a text result for the model. */
+export async function callMcpTool(connection, originalName, args) {
+    const result = await connection.client.callTool({ name: originalName, arguments: args });
+    const content = (result.content ?? []);
+    const parts = [];
+    for (const block of content) {
+        const type = block.type;
+        if (type === "text" && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+        else if (type === "resource") {
+            const resource = block.resource;
+            if (resource && typeof resource.text === "string")
+                parts.push(resource.text);
+        }
+        else if (type === "image") {
+            parts.push(`[image: ${block.mimeType}]`);
+        }
+        else if (type === "audio") {
+            parts.push(`[audio: ${block.mimeType}]`);
+        }
+        else if (type === "resource_link" && typeof block.uri === "string") {
+            parts.push(`[resource: ${block.uri}]`);
+        }
+    }
+    const text = parts.join("\n") || "(empty MCP tool result)";
+    return { text, isError: Boolean(result.isError) };
+}
+function withTimeout(promise, ms, message) {
+    let timer;
+    const cap = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+        timer.unref?.();
+    });
+    return Promise.race([promise, cap]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}

package/dist/mcp/config.js

@@ -0,0 +1,270 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getConfigDir } from "../config/settings.js";
+/**
+ * MCP server configuration loader.
+ *
+ * Resolution order (lowest precedence first), mirroring Claude Code:
+ *   1. User scope: `~/.orbcode/settings.json` -> `mcpServers`
+ *   2. Project scope: `.mcp.json` in the cwd and every parent directory
+ *      (closer-to-cwd wins on name collisions)
+ *   3. Local scope: `.orbcode/settings.json` -> `mcpServers` (highest precedence)
+ *
+ * `.mcp.json` is the shared, check-into-git project file (Claude Code compatible).
+ * The `mcpServers` block in settings.json is the per-user/per-machine override.
+ */
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Expand ${VAR} and $VAR references in a string using process.env. */
+function expandEnv(value) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, braced, bare) => {
+        const name = braced ?? bare;
+        return process.env[name] ?? "";
+    });
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Normalize an `oauth` config value: boolean, or an object with grant/scope. */
+function normalizeOAuth(raw) {
+    if (raw === true)
+        return true;
+    if (typeof raw === "string" && raw === "true")
+        return true;
+    if (!isPlainObject(raw))
+        return undefined;
+    if (raw.grantType === "client_credentials") {
+        if (typeof raw.clientId !== "string" || typeof raw.clientSecret !== "string")
+            return undefined;
+        return {
+            grantType: "client_credentials",
+            clientId: String(raw.clientId),
+            clientSecret: String(raw.clientSecret),
+            scope: typeof raw.scope === "string" ? raw.scope : undefined,
+        };
+    }
+    if (raw.grantType === "private_key_jwt") {
+        if (typeof raw.clientId !== "string")
+            return undefined;
+        if (typeof raw.algorithm !== "string")
+            return undefined;
+        const privateKey = typeof raw.privateKey === "string" ? raw.privateKey : isPlainObject(raw.privateKey) ? raw.privateKey : undefined;
+        if (privateKey === undefined)
+            return undefined;
+        return {
+            grantType: "private_key_jwt",
+            clientId: String(raw.clientId),
+            privateKey,
+            algorithm: String(raw.algorithm),
+            scope: typeof raw.scope === "string" ? raw.scope : undefined,
+        };
+    }
+    // Plain object (no grantType) → interactive auth-code flow with optional scope.
+    return { scope: typeof raw.scope === "string" ? raw.scope : undefined };
+}
+/** Validate + normalize a single server config object from disk. */
+function normalizeServerConfig(raw) {
+    if (!isPlainObject(raw))
+        return undefined;
+    const type = typeof raw.type === "string" ? raw.type : "stdio";
+    if (type === "stdio") {
+        if (typeof raw.command !== "string" || !raw.command.trim())
+            return undefined;
+        const config = { type: "stdio", command: expandEnv(raw.command) };
+        if (Array.isArray(raw.args)) {
+            config.args = raw.args.map((a) => expandEnv(String(a)));
+        }
+        if (isPlainObject(raw.env)) {
+            const env = {};
+            for (const [k, v] of Object.entries(raw.env)) {
+                if (typeof v === "string")
+                    env[k] = expandEnv(v);
+            }
+            config.env = env;
+        }
+        if (typeof raw.cwd === "string")
+            config.cwd = expandEnv(raw.cwd);
+        return config;
+    }
+    if (type === "http" || type === "sse") {
+        if (typeof raw.url !== "string" || !raw.url.trim())
+            return undefined;
+        const config = {
+            type,
+            url: expandEnv(raw.url),
+        };
+        if (isPlainObject(raw.headers)) {
+            const headers = {};
+            for (const [k, v] of Object.entries(raw.headers)) {
+                if (typeof v === "string")
+                    headers[k] = expandEnv(v);
+            }
+            ;
+            config.headers = headers;
+        }
+        const oauth = normalizeOAuth(raw.oauth);
+        if (oauth !== undefined)
+            config.oauth = oauth;
+        return config;
+    }
+    return undefined;
+}
+/** Validate + normalize a whole `mcpServers` record. */
+function normalizeServers(raw) {
+    if (!isPlainObject(raw))
+        return {};
+    const servers = {};
+    for (const [name, cfg] of Object.entries(raw)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(name))
+            continue;
+        const normalized = normalizeServerConfig(cfg);
+        if (normalized)
+            servers[name] = normalized;
+    }
+    return servers;
+}
+/** Read `mcpServers` from a settings.json file (user or local scope). */
+function readSettingsServers(filePath) {
+    const json = readJson(filePath);
+    if (!json)
+        return {};
+    return normalizeServers(json.mcpServers);
+}
+/** Read a `.mcp.json` file (project scope). */
+function readMcpJson(filePath) {
+    const json = readJson(filePath);
+    if (!json || !isPlainObject(json.mcpServers))
+        return {};
+    return normalizeServers(json.mcpServers);
+}
+/** Walk from cwd up to the filesystem root, collecting directories (root last). */
+function ancestorDirs(cwd) {
+    const dirs = [];
+    let current = path.resolve(cwd);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        dirs.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+/**
+ * Load and merge MCP server configs from all scopes. Closer-to-cwd and
+ * higher-precedence scopes override earlier ones on name collisions.
+ */
+export function loadMcpConfig(cwd = process.cwd()) {
+    const servers = {};
+    // 1. User scope (~/.orbcode/settings.json -> mcpServers)
+    const userServers = readSettingsServers(path.join(getConfigDir(), "settings.json"));
+    for (const [name, cfg] of Object.entries(userServers)) {
+        servers[name] = { ...cfg, scope: "user" };
+    }
+    // 2. Project scope (.mcp.json, root -> cwd so cwd wins)
+    for (const dir of ancestorDirs(cwd).reverse()) {
+        const projectServers = readMcpJson(path.join(dir, ".mcp.json"));
+        for (const [name, cfg] of Object.entries(projectServers)) {
+            servers[name] = { ...cfg, scope: "project" };
+        }
+    }
+    // 3. Local scope (.orbcode/settings.json -> mcpServers) — highest precedence
+    const localServers = readSettingsServers(path.join(cwd, ".orbcode", "settings.json"));
+    for (const [name, cfg] of Object.entries(localServers)) {
+        servers[name] = { ...cfg, scope: "local" };
+    }
+    return { servers };
+}
+/** Write a `.mcp.json` file in the cwd (project scope). */
+export function writeProjectMcpJson(cwd, servers) {
+    const config = { mcpServers: servers };
+    fs.writeFileSync(path.join(cwd, ".mcp.json"), JSON.stringify(config, null, "\t") + "\n");
+}
+/** Read just the project-scope `.mcp.json` from the cwd (no parent walk). */
+export function readProjectMcpJson(cwd) {
+    return readMcpJson(path.join(cwd, ".mcp.json"));
+}
+/** Read a settings.json file, returning the full object (not just mcpServers). */
+function readFullSettings(filePath) {
+    return readJson(filePath) ?? {};
+}
+/** Write a settings.json file, preserving existing keys. */
+function writeFullSettings(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, "\t") + "\n", { mode: 0o600 });
+}
+/** Path to the settings file for a given scope. */
+function settingsPathForScope(cwd, scope) {
+    if (scope === "user")
+        return path.join(getConfigDir(), "settings.json");
+    return path.join(cwd, ".orbcode", "settings.json");
+}
+/** Path to the config file for a given scope (`.mcp.json` for project,
+ *  settings.json for user/local). */
+export function configPathForScope(cwd, scope) {
+    if (scope === "project")
+        return path.join(cwd, ".mcp.json");
+    return settingsPathForScope(cwd, scope);
+}
+/** Add (or overwrite) a server in the given scope's config file. */
+export function addMcpServer(cwd, name, config, scope) {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+        throw new Error(`Invalid server name "${name}". Use only letters, numbers, hyphens, and underscores.`);
+    }
+    if (scope === "project") {
+        const existing = readProjectMcpJson(cwd);
+        existing[name] = config;
+        writeProjectMcpJson(cwd, existing);
+    }
+    else {
+        const filePath = settingsPathForScope(cwd, scope);
+        const settings = readFullSettings(filePath);
+        const servers = normalizeServers(settings.mcpServers);
+        servers[name] = config;
+        settings.mcpServers = servers;
+        writeFullSettings(filePath, settings);
+    }
+}
+/** Remove a server from the given scope's config file. Returns true if it
+ *  existed and was removed, false if it wasn't found. */
+export function removeMcpServer(cwd, name, scope) {
+    if (scope === "project") {
+        const existing = readProjectMcpJson(cwd);
+        if (!(name in existing))
+            return false;
+        delete existing[name];
+        writeProjectMcpJson(cwd, existing);
+        return true;
+    }
+    const filePath = settingsPathForScope(cwd, scope);
+    const settings = readFullSettings(filePath);
+    const servers = normalizeServers(settings.mcpServers);
+    if (!(name in servers))
+        return false;
+    delete servers[name];
+    settings.mcpServers = servers;
+    writeFullSettings(filePath, settings);
+    return true;
+}
+/** Find which scope a server name lives in (highest-precedence scope wins).
+ *  Returns undefined if the name isn't configured anywhere. */
+export function findServerScope(cwd, name) {
+    const { servers } = loadMcpConfig(cwd);
+    return servers[name]?.scope;
+}
+/** Remove a server from whichever scope it's configured in. Returns the scope
+ *  it was removed from, or undefined if not found. */
+export function removeMcpServerAnyScope(cwd, name) {
+    const scope = findServerScope(cwd, name);
+    if (!scope)
+        return undefined;
+    removeMcpServer(cwd, name, scope);
+    return scope;
+}