min-agent 0.2.0 → 0.3.0

package/dist/mcp.js

@@ -2,59 +2,112 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { UnauthorizedError, auth as mcpAuth, } from "@modelcontextprotocol/sdk/client/auth.js";
 import { tool, jsonSchema } from "ai";
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from "fs";
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
 import path from "path";
+import { createServer } from "http";
+import { spawn } from "child_process";
+import { Writable } from "stream";
+import { randomUUID } from "crypto";
 import { truncateToolOutput } from "./tool-output.js";
 import { getConfigDir } from "./config.js";
+import { log } from "./logger.js";
+const STRUCTURED_STRING_MAX = 8000;
+const STRUCTURED_ARRAY_MAX = 500;
+/** Bound the size of MCP `structuredContent` while keeping its JSON shape (outputSchema validation). */
+function truncateStructured(value) {
+    if (typeof value === "string") {
+        return value.length > STRUCTURED_STRING_MAX ? value.slice(0, STRUCTURED_STRING_MAX) + "… [truncated]" : value;
+    }
+    if (Array.isArray(value)) {
+        const sliced = value.slice(0, STRUCTURED_ARRAY_MAX);
+        return sliced.map(truncateStructured);
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = truncateStructured(v);
+        return out;
+    }
+    return value;
+}
 const DEFAULT_TIMEOUT = 30000;
-function getMcpConfigPath() {
-    // Check project-local first, then global
-    const local = path.join(process.cwd(), ".min-agent", "mcp.json");
-    if (existsSync(local))
-        return local;
+const STDERD_KEEP_LINES = 20;
+const OAUTH_BROWSER_TIMEOUT_MS = 5 * 60 * 1000;
+function globalMcpConfigPath() {
     return path.join(getConfigDir(), "mcp.json");
 }
-function getMcpConfigWritePath() {
-    // Write to project-local if it exists, otherwise global
-    const local = path.join(process.cwd(), ".min-agent", "mcp.json");
-    if (existsSync(path.dirname(local)))
-        return local;
-    return path.join(getConfigDir(), "mcp.json");
+function projectMcpConfigPath() {
+    return path.join(process.cwd(), ".min-agent", "mcp.json");
+}
+export function mcpConfigPathFor(scope) {
+    return scope === "project" ? projectMcpConfigPath() : globalMcpConfigPath();
 }
 let connectedServers = {};
-export function loadMcpConfig() {
-    const globalPath = path.join(getConfigDir(), "mcp.json");
-    const localPath = path.join(process.cwd(), ".min-agent", "mcp.json");
-    let config = { mcpServers: {} };
-    // Load global first
-    if (existsSync(globalPath)) {
-        try {
-            const global = JSON.parse(readFileSync(globalPath, "utf-8"));
-            config.mcpServers = { ...config.mcpServers, ...global.mcpServers };
-        }
-        catch { }
+const mcpServerErrors = {};
+/** Cache of built tool wrappers; invalidated when MCP servers (re)connect. */
+let mcpToolsCache = null;
+const configCaches = new Map();
+function loadJsonConfig(filePath) {
+    const cache = configCaches.get(filePath);
+    try {
+        const st = statSync(filePath);
+        if (cache && cache.mtimeMs === st.mtimeMs && cache.size === st.size)
+            return cache;
+        const config = JSON.parse(readFileSync(filePath, "utf-8"));
+        const next = { mtimeMs: st.mtimeMs, size: st.size, config };
+        configCaches.set(filePath, next);
+        return next;
     }
-    // Local overrides global
-    if (existsSync(localPath) && localPath !== globalPath) {
-        try {
-            const local = JSON.parse(readFileSync(localPath, "utf-8"));
-            config.mcpServers = { ...config.mcpServers, ...local.mcpServers };
-        }
-        catch { }
+    catch {
+        return null;
     }
-    return config;
 }
-export function saveMcpConfig(config) {
-    const configPath = path.join(getConfigDir(), "mcp.json");
+/** Load a single scope's mcp.json (not merged). */
+export function loadMcpConfigFile(scope) {
+    const cached = loadJsonConfig(mcpConfigPathFor(scope));
+    return cached?.config ?? { mcpServers: {} };
+}
+/** Load merged config: project-level entries override global ones. */
+export function loadMcpConfig() {
+    return {
+        mcpServers: {
+            ...loadMcpConfigFile("global").mcpServers,
+            ...loadMcpConfigFile("project").mcpServers,
+        },
+    };
+}
+/** All configured servers with the scope each entry lives in (project wins over global). */
+export function loadMcpConfigEntries() {
+    const global = loadMcpConfigFile("global");
+    const project = loadMcpConfigFile("project");
+    return Object.entries({ ...global.mcpServers, ...project.mcpServers }).map(([name, config]) => ({
+        name,
+        config,
+        scope: project.mcpServers[name] !== undefined ? "project" : "global",
+    }));
+}
+export function saveMcpConfig(config, scope = "global") {
+    const configPath = mcpConfigPathFor(scope);
     const dir = path.dirname(configPath);
     mkdirSync(dir, { recursive: true });
     writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+    configCaches.delete(configPath);
 }
 export function isRemoteMcpConfig(config) {
     return typeof config.url === "string" && config.url.trim().length > 0;
 }
+/** Effective timeouts for one server entry. */
+export function resolveMcpTimeouts(config) {
+    return {
+        connectTimeout: config.connectTimeout ?? config.timeout ?? DEFAULT_TIMEOUT,
+        callTimeout: config.callTimeout ?? config.timeout ?? DEFAULT_TIMEOUT,
+    };
+}
+function configSignature(config) {
+    return JSON.stringify(config);
+}
 function buildRemoteRequestInit(config) {
     const headers = new Headers(config.headers ?? {});
     const token = config.token?.trim();
@@ -65,7 +118,40 @@ function buildRemoteRequestInit(config) {
         return undefined;
     return { headers };
 }
-async function openStdioMcpServer(name, config) {
+function createStderrSink(name) {
+    const lines = [];
+    let buffer = "";
+    const stream = new Writable({
+        write(chunk, _enc, cb) {
+            buffer += String(chunk);
+            let idx = -1;
+            while ((idx = buffer.indexOf("\n")) !== -1) {
+                const line = buffer.slice(0, idx).trim();
+                buffer = buffer.slice(idx + 1);
+                if (!line)
+                    continue;
+                lines.push(line);
+                if (lines.length > STDERD_KEEP_LINES)
+                    lines.shift();
+                log("warn", `mcp "${name}" stderr: ${line}`);
+            }
+            cb();
+        },
+    });
+    return { stream, lines };
+}
+/** List every tool, following pagination cursors. */
+async function listAllTools(client) {
+    const all = [];
+    let cursor;
+    do {
+        const result = await client.listTools(cursor ? { cursor } : undefined);
+        all.push(...result.tools);
+        cursor = result.nextCursor;
+    } while (cursor);
+    return all;
+}
+async function openStdioMcpServer(name, config, onTransport) {
     // Support both formats:
     // { command: ["uvx", "mcp-server-time"] }           — min-agent native
     // { command: "uvx", args: ["mcp-server-time"] }     — opencode/claude style
@@ -84,18 +170,244 @@ async function openStdioMcpServer(name, config) {
     if (!cmd) {
         throw new Error(`MCP "${name}" has empty command`);
     }
+    const stderrSink = createStderrSink(name);
     const transport = new StdioClientTransport({
         command: cmd,
         args,
         env: { ...process.env, ...(config.environment ?? {}) },
         stderr: "pipe",
     });
+    // Drain the child's stderr so a chatty server can never block on a full pipe buffer.
+    transport.stderr?.pipe(stderrSink.stream);
+    onTransport?.(transport);
     const client = new Client({ name: "min-agent", version: "0.1.0" });
-    await client.connect(transport);
-    const { tools } = await client.listTools();
-    return { client, transport, tools };
+    try {
+        await client.connect(transport);
+        const tools = await listAllTools(client);
+        return { client, transport, tools, callTimeout: resolveMcpTimeouts(config).callTimeout, signature: configSignature(config), stderrSink };
+    }
+    catch (err) {
+        await transport.close().catch(() => { });
+        const tail = stderrSink.lines.length ? `\nServer stderr (last ${stderrSink.lines.length} lines):\n${stderrSink.lines.map((l) => `  ${l}`).join("\n")}` : "";
+        throw new Error(`${err?.message ?? String(err)}${tail}`);
+    }
 }
-async function openRemoteMcpServer(name, config) {
+/**
+ * Persistent OAuth provider backed by `~/.min-agent/mcp-oauth/<name>.json`.
+ * Binds a localhost callback server on a random port so the browser can return
+ * the authorization code; the port is fixed per connection attempt so the
+ * registration metadata and the redirect stay consistent.
+ */
+class McpOAuthProvider {
+    name;
+    serverConfig;
+    tokensStore;
+    clientInfo;
+    discoveryStore;
+    verifier;
+    pendingState;
+    pendingCode;
+    pendingError;
+    resolveCode;
+    rejectCode;
+    callbackServer;
+    callbackBase = "http://127.0.0.1";
+    redirectUrl = "";
+    constructor(name, serverConfig, storeFile) {
+        this.name = name;
+        this.serverConfig = serverConfig;
+        this.loadStore(storeFile);
+    }
+    static async create(name, serverConfig) {
+        const storeFile = path.join(getConfigDir(), "mcp-oauth", `${sanitize(name)}-${djb2(name).toString(16)}.json`);
+        const provider = new McpOAuthProvider(name, serverConfig, storeFile);
+        await provider.bindCallbackServer();
+        return provider;
+    }
+    storeFile() {
+        return path.join(getConfigDir(), "mcp-oauth", `${sanitize(this.name)}-${djb2(this.name).toString(16)}.json`);
+    }
+    loadStore(file) {
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf-8"));
+            this.clientInfo = raw.clientInfo;
+            this.tokensStore = raw.tokens;
+            this.discoveryStore = raw.discovery;
+        }
+        catch { }
+    }
+    saveStore() {
+        const file = this.storeFile();
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify({
+            ...(this.clientInfo ? { clientInfo: this.clientInfo } : {}),
+            ...(this.tokensStore ? { tokens: this.tokensStore } : {}),
+            ...(this.discoveryStore ? { discovery: this.discoveryStore } : {}),
+        }, null, 2), "utf-8");
+    }
+    settleCode(code) {
+        this.pendingCode = code;
+        this.resolveCode?.(code);
+    }
+    failCode(err) {
+        this.pendingError = err;
+        this.rejectCode?.(err);
+    }
+    bindCallbackServer() {
+        return new Promise((resolve, reject) => {
+            const server = createServer((req, res) => {
+                const requestUrl = new URL(req.url ?? "/", this.callbackBase);
+                const code = requestUrl.searchParams.get("code");
+                const state = requestUrl.searchParams.get("state");
+                const error = requestUrl.searchParams.get("error");
+                const body = code
+                    ? "<html><body><h3>min-agent: authorization complete</h3><p>You can close this tab and return to the terminal.</p></body></html>"
+                    : "<html><body><h3>min-agent: authorization failed</h3><p>Check the terminal for details.</p></body></html>";
+                res.writeHead(code ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(body);
+                if (this.pendingState && state && state !== this.pendingState) {
+                    this.failCode(new Error("OAuth state mismatch — authorization attempt rejected"));
+                    return;
+                }
+                if (code) {
+                    this.settleCode(code);
+                }
+                else {
+                    this.failCode(new Error(error ? `OAuth authorization failed: ${error}` : "OAuth authorization failed: no code returned"));
+                }
+            });
+            server.on("error", (err) => {
+                this.failCode(new Error(`OAuth callback server failed: ${err.message}`));
+            });
+            server.listen(0, "127.0.0.1", () => {
+                const address = server.address();
+                if (!address || typeof address === "string") {
+                    reject(new Error("OAuth callback server could not bind a port"));
+                    return;
+                }
+                this.callbackServer = server;
+                this.callbackBase = `http://127.0.0.1:${address.port}`;
+                this.redirectUrl = `${this.callbackBase}/callback`;
+                resolve();
+            });
+        });
+    }
+    close() {
+        this.callbackServer?.close();
+        this.callbackServer = undefined;
+    }
+    /** Resolves once the browser callback delivers the authorization code. */
+    waitForCode() {
+        if (this.pendingCode)
+            return Promise.resolve(this.pendingCode);
+        if (this.pendingError)
+            return Promise.reject(this.pendingError);
+        return new Promise((resolve, reject) => {
+            this.resolveCode = resolve;
+            this.rejectCode = reject;
+        });
+    }
+    get clientMetadata() {
+        const oauth = this.serverConfig.oauth;
+        const meta = {
+            redirect_uris: [this.redirectUrl],
+            client_name: "min-agent",
+        };
+        if (typeof oauth === "object" && oauth) {
+            if (oauth.clientId)
+                meta.client_id = oauth.clientId;
+            if (oauth.clientSecret)
+                meta.client_secret = oauth.clientSecret;
+            if (oauth.scope)
+                meta.scope = oauth.scope;
+        }
+        return meta;
+    }
+    clientInformation() {
+        if (!this.clientInfo)
+            return undefined;
+        const uris = "redirect_uris" in this.clientInfo ? this.clientInfo.redirect_uris : [];
+        return uris.includes(this.redirectUrl) ? this.clientInfo : undefined;
+    }
+    saveClientInformation(clientInformation) {
+        this.clientInfo = clientInformation;
+        this.saveStore();
+    }
+    tokens() {
+        return this.tokensStore;
+    }
+    saveTokens(tokens) {
+        this.tokensStore = tokens;
+        this.saveStore();
+    }
+    saveDiscoveryState(state) {
+        this.discoveryStore = state;
+        this.saveStore();
+    }
+    discoveryState() {
+        return this.discoveryStore;
+    }
+    saveCodeVerifier(codeVerifier) {
+        this.verifier = codeVerifier;
+    }
+    codeVerifier() {
+        if (!this.verifier)
+            throw new Error("No PKCE code verifier for this session");
+        return this.verifier;
+    }
+    state() {
+        this.pendingState = randomUUID();
+        return this.pendingState;
+    }
+    redirectToAuthorization(authorizationUrl) {
+        openBrowser(authorizationUrl.href);
+    }
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    try {
+        if (platform === "darwin") {
+            spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
+        }
+        else if (platform === "win32") {
+            spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
+        }
+        else {
+            spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
+        }
+    }
+    catch (err) {
+        log("warn", `mcp oauth: failed to open browser: ${err.message}`);
+    }
+}
+/**
+ * Interactive OAuth flow for remote servers. Returns the provider to pass to
+ * the transport, or undefined when OAuth is not configured.
+ */
+async function runOAuthFlow(name, config, baseUrl) {
+    if (!config.oauth || config.token?.trim())
+        return undefined;
+    const provider = await McpOAuthProvider.create(name, config);
+    try {
+        const result = await mcpAuth(provider, { serverUrl: baseUrl.href });
+        if (result === "REDIRECT") {
+            console.log(`\x1b[90m  MCP "${name}" needs authorization — a browser tab was opened. Waiting for login…\x1b[0m`);
+            const code = await Promise.race([
+                provider.waitForCode(),
+                new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error("OAuth authorization timed out after 5 minutes")), OAUTH_BROWSER_TIMEOUT_MS);
+                }),
+            ]);
+            await mcpAuth(provider, { serverUrl: baseUrl.href, authorizationCode: code });
+        }
+        return provider;
+    }
+    catch (err) {
+        provider.close();
+        throw new Error(`MCP "${name}" OAuth failed: ${err?.message ?? String(err)}`);
+    }
+}
+async function openRemoteMcpServer(name, config, onTransport) {
     const rawUrl = config.url?.trim();
     if (!rawUrl) {
         throw new Error(`MCP "${name}" has empty url`);
@@ -112,19 +424,35 @@ async function openRemoteMcpServer(name, config) {
     }
     const requestInit = buildRemoteRequestInit(config);
     const mode = config.remoteTransport ?? "auto";
+    const oauthProvider = await runOAuthFlow(name, config, baseUrl);
+    const callTimeout = resolveMcpTimeouts(config).callTimeout;
     const connectStreamable = async () => {
         const client = new Client({ name: "min-agent", version: "0.1.0" });
-        const transport = new StreamableHTTPClientTransport(baseUrl, requestInit ? { requestInit } : undefined);
-        await client.connect(transport);
-        const { tools } = await client.listTools();
-        return { client, transport, tools };
+        const transport = new StreamableHTTPClientTransport(baseUrl, requestInit || oauthProvider ? { requestInit, authProvider: oauthProvider } : undefined);
+        onTransport?.(transport);
+        try {
+            await client.connect(transport);
+            const tools = await listAllTools(client);
+            return { client, transport, tools, callTimeout, signature: configSignature(config), oauthProvider };
+        }
+        catch (err) {
+            await transport.close().catch(() => { });
+            throw err;
+        }
     };
     const connectSse = async () => {
         const client = new Client({ name: "min-agent", version: "0.1.0" });
-        const transport = new SSEClientTransport(baseUrl, requestInit ? { requestInit } : undefined);
-        await client.connect(transport);
-        const { tools } = await client.listTools();
-        return { client, transport, tools };
+        const transport = new SSEClientTransport(baseUrl, requestInit || oauthProvider ? { requestInit, authProvider: oauthProvider } : undefined);
+        onTransport?.(transport);
+        try {
+            await client.connect(transport);
+            const tools = await listAllTools(client);
+            return { client, transport, tools, callTimeout, signature: configSignature(config), oauthProvider };
+        }
+        catch (err) {
+            await transport.close().catch(() => { });
+            throw err;
+        }
     };
     try {
         if (mode === "streamable-http")
@@ -145,22 +473,23 @@ async function openRemoteMcpServer(name, config) {
         }
     }
     catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
         // Handle OAuth/Unauthorized errors
-        if (err instanceof UnauthorizedError || err?.message?.includes("Unauthorized") || err?.message?.includes("401")) {
+        if (err instanceof UnauthorizedError || message.includes("Unauthorized") || message.includes("401")) {
             if (config.oauth === false) {
                 throw new Error(`MCP "${name}" requires authentication but OAuth is disabled in config`);
             }
             throw new Error(`MCP "${name}" requires authentication. Add a "token" field to the server config, or configure OAuth:\n` +
                 `  min-agent mcp add ${name} --url ${rawUrl} --token YOUR_TOKEN`);
         }
-        throw new Error(`MCP "${name}" remote connection failed: ${err?.message ?? String(err)}`);
+        throw new Error(`MCP "${name}" remote connection failed: ${message}`);
     }
 }
-async function openMcpServer(name, config) {
+async function openMcpServer(name, config, onTransport) {
     if (isRemoteMcpConfig(config)) {
-        return await openRemoteMcpServer(name, config);
+        return await openRemoteMcpServer(name, config, onTransport);
     }
-    return await openStdioMcpServer(name, config);
+    return await openStdioMcpServer(name, config, onTransport);
 }
 /** One-line summary for CLI / logs (no secrets). */
 export function formatMcpServerBinding(config) {
@@ -171,93 +500,204 @@ export function formatMcpServerBinding(config) {
     const cmd = Array.isArray(config.command) ? config.command.join(" ") : `${config.command ?? ""} ${(config.args ?? []).join(" ")}`.trim();
     return cmd || "(no command)";
 }
+async function openMcpServerWithTimeout(name, config) {
+    const timeout = resolveMcpTimeouts(config).connectTimeout;
+    let timer;
+    const transportHolder = { transport: null };
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`connection timed out after ${timeout}ms`)), timeout);
+    });
+    const connectPromise = openMcpServer(name, config, (t) => {
+        transportHolder.transport = t;
+    });
+    connectPromise.catch(() => { });
+    try {
+        const server = await Promise.race([connectPromise, timeoutPromise]);
+        return { server };
+    }
+    catch (error) {
+        await transportHolder.transport?.close().catch(() => { });
+        return { error };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 export async function connectMcpServer(name, config) {
     if (config.enabled === false)
         return null;
-    const timeout = config.timeout ?? DEFAULT_TIMEOUT;
-    try {
-        const server = await Promise.race([
-            openMcpServer(name, config),
-            new Promise((_, reject) => setTimeout(() => reject(new Error(`connection timed out after ${timeout}ms`)), timeout)),
-        ]);
+    const { server, error } = await openMcpServerWithTimeout(name, config);
+    if (server) {
+        delete mcpServerErrors[name];
         console.log(`\x1b[90m  MCP "${name}" connected (${server.tools.length} tools)\x1b[0m`);
+        log("info", `mcp "${name}" connected (${server.tools.length} tools)`);
         return server;
     }
-    catch (err) {
-        console.error(`\x1b[31m  MCP "${name}" failed: ${err.message}\x1b[0m`);
-        return null;
-    }
+    const message = error?.message ?? String(error);
+    mcpServerErrors[name] = message;
+    console.error(`\x1b[31m  MCP "${name}" failed: ${message}\x1b[0m`);
+    log("error", `mcp "${name}" failed: ${message}`);
+    return null;
 }
 export async function checkMcpServer(name, config) {
     if (config.enabled === false) {
         return { name, enabled: false, ok: true, toolCount: 0 };
     }
-    try {
-        const server = await openMcpServer(name, config);
-        const toolCount = server.tools.length;
-        try {
-            await server.client.close();
-        }
-        catch { }
-        return { name, enabled: true, ok: true, toolCount };
-    }
-    catch (err) {
+    const { server, error } = await openMcpServerWithTimeout(name, config);
+    if (!server) {
         return {
             name,
             enabled: true,
             ok: false,
             toolCount: 0,
-            error: err?.message ?? String(err),
+            error: error instanceof Error ? error.message : String(error),
         };
     }
+    const toolCount = server.tools.length;
+    try {
+        await server.client.close();
+    }
+    catch { }
+    return { name, enabled: true, ok: true, toolCount };
 }
 export async function checkAllMcpServers() {
-    const config = loadMcpConfig();
-    const results = [];
-    for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
-        results.push(await checkMcpServer(name, serverConfig));
-    }
-    return results;
+    const entries = loadMcpConfigEntries();
+    const settled = await Promise.allSettled(entries.map(({ name, config }) => checkMcpServer(name, config)));
+    return settled.map((r, i) => r.status === "fulfilled" ? r.value : { name: entries[i]?.name ?? "unknown", enabled: true, ok: false, toolCount: 0, error: String(r.reason) });
 }
-export async function initMcp() {
-    const config = loadMcpConfig();
-    for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
-        const server = await connectMcpServer(name, serverConfig);
-        if (server)
-            connectedServers[name] = server;
+async function closeConnectedServer(name, server) {
+    try {
+        await server.client.close();
     }
+    catch { }
+    server.oauthProvider?.close();
+    delete connectedServers[name];
+    delete mcpServerErrors[name];
 }
 export async function shutdownMcp() {
+    mcpToolsCache = null;
+    await Promise.all(Object.entries(connectedServers).map(([name, server]) => closeConnectedServer(name, server)));
+    connectedServers = {};
+}
+let syncQueue = Promise.resolve();
+/**
+ * Reconcile live connections with the current config: disconnect servers that
+ * were removed or changed, connect new/changed enabled ones. Safe to call
+ * repeatedly; used by `initMcp` and by `serve` after config mutations.
+ * Concurrent calls are serialized so parallel config writes cannot
+ * double-connect the same server.
+ */
+export function syncMcpConnections() {
+    const run = syncQueue.then(() => syncMcpConnectionsNow());
+    syncQueue = run.catch(() => { });
+    return run;
+}
+async function syncMcpConnectionsNow() {
+    mcpToolsCache = null;
+    const entries = loadMcpConfigEntries();
     for (const [name, server] of Object.entries(connectedServers)) {
-        try {
-            await server.client.close();
+        const entry = entries.find((e) => e.name === name);
+        if (!entry || entry.config.enabled === false || configSignature(entry.config) !== server.signature) {
+            await closeConnectedServer(name, server);
         }
-        catch { }
     }
-    connectedServers = {};
+    const pending = entries.filter(({ name, config }) => {
+        if (config.enabled === false)
+            return false;
+        const live = connectedServers[name];
+        if (!live)
+            return true;
+        return configSignature(config) !== live.signature;
+    });
+    const settled = await Promise.allSettled(pending.map(async ({ name, config }) => {
+        const server = await connectMcpServer(name, config);
+        if (server)
+            connectedServers[name] = server;
+    }));
+    const failedNames = new Set();
+    settled.forEach((r, i) => {
+        if (r.status === "rejected") {
+            const name = pending[i].name;
+            failedNames.add(name);
+            mcpServerErrors[name] = String(r.reason);
+            console.error(`\x1b[31m  MCP "${name}" failed: ${String(r.reason)}\x1b[0m`);
+            log("error", `mcp "${name}" failed: ${String(r.reason)}`);
+        }
+    });
+    return entries.map(({ name, config }) => {
+        const live = connectedServers[name];
+        if (config.enabled === false)
+            return { name, state: "disabled" };
+        if (live) {
+            const wasPending = pending.some((p) => p.name === name);
+            return { name, state: wasPending ? "connected" : "unchanged", tools: live.tools.length };
+        }
+        return {
+            name,
+            state: "failed",
+            ...(mcpServerErrors[name] ? { error: mcpServerErrors[name] } : {}),
+        };
+    });
+}
+export async function initMcp() {
+    mcpToolsCache = null;
+    await shutdownMcp();
+    await syncMcpConnections();
 }
 export function getMcpTools() {
+    if (mcpToolsCache)
+        return mcpToolsCache;
+    mcpToolsCache = buildMcpToolsMap(connectedServers);
+    return mcpToolsCache;
+}
+/**
+ * Build AI SDK tool wrappers for a set of connected MCP servers.
+ * Tool IDs are collision-safe (suffixed when sanitized names clash) and
+ * descriptions are prefixed with the owning server name.
+ */
+export function buildMcpToolsMap(servers) {
     const tools = {};
-    for (const [serverName, server] of Object.entries(connectedServers)) {
+    const used = new Set();
+    for (const [serverName, server] of Object.entries(servers)) {
         for (const mcpTool of server.tools) {
-            const toolId = `${sanitize(serverName)}_${sanitize(mcpTool.name)}`;
+            let toolId = `${sanitize(serverName)}_${sanitize(mcpTool.name)}`;
+            let n = 2;
+            while (used.has(toolId))
+                toolId = `${sanitize(serverName)}_${sanitize(mcpTool.name)}_${n++}`;
+            used.add(toolId);
+            const baseSchema = (mcpTool.inputSchema ?? {});
             const schema = {
-                ...mcpTool.inputSchema,
-                type: "object",
-                properties: (mcpTool.inputSchema?.properties ?? {}),
+                ...baseSchema,
+                ...(baseSchema.type ? {} : { type: "object" }),
+                ...(baseSchema.properties ? {} : { properties: {} }),
             };
+            const readOnly = mcpTool.annotations?.readOnlyHint === true;
+            const description = `[${serverName}] ${mcpTool.description ?? `MCP tool: ${mcpTool.name}`}` +
+                (readOnly ? " (read-only)" : "");
+            const outputSchema = mcpTool.outputSchema;
             tools[toolId] = tool({
-                description: mcpTool.description ?? `MCP tool: ${mcpTool.name}`,
+                description,
                 inputSchema: jsonSchema(schema),
-                execute: async (args) => {
+                ...(outputSchema && outputSchema.type === "object"
+                    ? { outputSchema: jsonSchema(outputSchema) }
+                    : {}),
+                execute: async (args, options) => {
                     try {
+                        const signals = [AbortSignal.timeout(server.callTimeout)];
+                        if (options?.abortSignal)
+                            signals.push(options.abortSignal);
+                        const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
                         const result = await server.client.callTool({
                             name: mcpTool.name,
-                            arguments: args,
-                        });
+                            arguments: (args ?? {}),
+                        }, undefined, { signal });
                         if (result.isError) {
                             return truncateToolOutput(`Error: ${JSON.stringify(result.content)}`, { direction: "head" }).content;
                         }
+                        if (result.structuredContent !== undefined) {
+                            return truncateStructured(result.structuredContent);
+                        }
                         const content = result.content;
                         const text = content
                             .filter((c) => c.type === "text")
@@ -276,12 +716,13 @@ export function getMcpTools() {
 }
 export function getMcpStatus() {
     const status = {};
-    const config = loadMcpConfig();
-    for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+    for (const { name, config } of loadMcpConfigEntries()) {
         const server = connectedServers[name];
         status[name] = {
             connected: !!server,
+            enabled: config.enabled !== false,
             tools: server?.tools.map((t) => t.name) ?? [],
+            ...(mcpServerErrors[name] ? { error: mcpServerErrors[name] } : {}),
         };
     }
     return status;
@@ -289,3 +730,9 @@ export function getMcpStatus() {
 function sanitize(s) {
     return s.replace(/[^a-zA-Z0-9_-]/g, "_");
 }
+function djb2(s) {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++)
+        h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+    return h;
+}