@matterailab/orbcode 0.2.2 → 0.2.3

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,

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);
+    });
+}