@fitchmultz/pi-mcp-adapter 5.0.0 → 6.0.0

package/dist/index.js

@@ -1,30 +1,29 @@
 import { Type } from "typebox";
 import { showStatus, showTools, showPrompts, reconnectServer, reconnectServers, authenticateServer, logoutServer, openMcpAuthPanel, openMcpPanel, openMcpSetup } from "./commands.js";
 import { cloneMcpConfig, isPathInsideProject, loadMcpConfig, writeProjectServerDisabledOverride } from "./config.js";
-import { buildProxyDescription, createDirectToolExecutor, getMissingConfiguredDirectToolServers, resolveDirectTools } from "./direct-tools.js";
-import { flushMetadataCache, initializeMcp, updateStatusBar } from "./init.js";
-import { getMetadataCachePath, loadMetadataCache } from "./metadata-cache.js";
+import { buildProxyDescription, directToolSelection, getMissingConfiguredDirectToolServers } from "./direct-tools.js";
+import { flushMetadataCache, initializeMcp, lazyConnect, updateStatusBar } from "./init.js";
+import { getMetadataCachePath, isServerCacheValid, loadMetadataCache, reconstructToolMetadata } from "./metadata-cache.js";
 import { createPromptCommand, resolveCachedPrompts } from "./prompts.js";
 import { logger } from "./logger.js";
 import { executeAuthComplete, executeAuthStart, executeCall, executeConnect, executeDescribe, executeInstructions, executeList, executeSearch, executeStatus, executeUiMessages } from "./proxy-modes.js";
-import { formatTerminalError, normalizeDirectToolInputSchema, truncateAtWord } from "./utils.js";
+import { formatTerminalError } from "./utils.js";
 import { createOAuthRuntime, shutdownOAuth } from "./mcp-auth-flow.js";
-import { createMcpDirectToolCallRenderer, renderMcpProxyToolCall, renderMcpToolResult } from "./tool-result-renderer.js";
+import { renderMcpProxyToolCall, renderMcpToolResult } from "./tool-result-renderer.js";
 import { toolErrorOverride } from "./error-signal.js";
 import { createMcpRuntimeOwner, createOwnedUi, isAbortError } from "./runtime-owner.js";
 import { publishMcpStatusShutdown } from "./mcp-status.js";
 import { DEFAULT_MCP_SCRIPT_TIMEOUT_MS, runMcpScript } from "./mcp-code.js";
-import { MAX_PAGE_SIZE, MAX_TOOL_NAME_LENGTH } from "./search-ranking.js";
+import { MAX_PAGE_SIZE, paginate, rankToolMatches } from "./search-ranking.js";
+import { createToolLoader, supportsNativeAsync } from "./tool-loader.js";
+import { gatewayParameters, prepareGatewayArguments } from "./gateway-arguments.js";
+import { executeResourceList, executeResourceRead } from "./resource-tools.js";
+import { guardMcpOutput, guardedMcpDetails, readMcpResult, resolveMcpOutputGuardOptions } from "./mcp-output-guard.js";
 import { abortable } from "./abort.js";
 import { onSessionCheckpoint, prepareMcpCheckpoint } from "./checkpoint.js";
 export { MCP_STATUS_EVENT, MCP_STATUS_SNAPSHOT_VERSION, } from "./types.js";
 const INIT_WAIT_TIMEOUT_MS = 30_000;
 const INIT_WAIT_TIMED_OUT = Symbol("init-wait-timed-out");
-const inactiveDirectToolsKey = Symbol.for("fitch-mcp-adapter.inactive-direct-tools");
-const inactiveDirectToolsBySession = (() => {
-    const shared = globalThis;
-    return shared[inactiveDirectToolsKey] ??= new Map();
-})();
 async function awaitWithTimeout(promise, timeoutMs) {
     let timer;
     try {
@@ -93,52 +92,13 @@ function installMcpAdapter(pi, options) {
     const earlyCache = null;
     const envRaw = process.env.MCP_DIRECT_TOOLS;
     const envDirectToolOverride = envRaw?.split(",").map(s => s.trim()).filter(Boolean);
-    const registeredDirectTools = new Map();
+    const toolLoader = createToolLoader(pi, () => state, () => initPromise, beforeExecute);
     const deactivatedTools = new Set();
-    const preservedInactiveTools = new Set();
-    let activationKey = null;
+    let runtimeCwd;
+    let nativeAsyncSupported = false;
     let proxyToolRegistered = false;
     let proxyToolDescription = null;
     let directToolsFrozen = false;
-    function directToolFingerprint(spec) {
-        return JSON.stringify({
-            serverName: spec.serverName,
-            originalName: spec.originalName,
-            prefixedName: spec.prefixedName,
-            description: spec.description,
-            inputSchema: spec.inputSchema,
-            annotations: spec.annotations,
-            resourceUri: spec.resourceUri,
-            uiResourceUri: spec.uiResourceUri,
-            uiStreamMode: spec.uiStreamMode,
-        });
-    }
-    function registerDirectTool(spec) {
-        const execute = createDirectToolExecutor(() => state, () => initPromise, spec, beforeExecute);
-        pi.registerTool({
-            ...(beforeExecute ? { executionMode: "sequential" } : {}),
-            name: spec.prefixedName,
-            label: `MCP: ${spec.originalName}`,
-            description: spec.description || "(no description)",
-            promptSnippet: truncateAtWord(spec.description, 100) || `MCP tool from ${spec.serverName}`,
-            parameters: Type.Unsafe(normalizeDirectToolInputSchema(spec.inputSchema)),
-            execute,
-            renderCall: createMcpDirectToolCallRenderer(spec.prefixedName),
-            renderResult: renderMcpToolResult,
-        });
-        if (preservedInactiveTools.has(spec.prefixedName)) {
-            const activeTools = pi.getActiveTools();
-            if (activeTools.includes(spec.prefixedName)) {
-                pi.setActiveTools(activeTools.filter((name) => name !== spec.prefixedName));
-            }
-        }
-    }
-    function resolveCurrentDirectTools(config, cache) {
-        if (envRaw === "__none__")
-            return [];
-        const prefix = config.settings?.toolPrefix ?? "server";
-        return resolveDirectTools(config, cache, prefix, envDirectToolOverride);
-    }
     function deactivateTools(toolNames) {
         if (toolNames.length === 0)
             return;
@@ -153,36 +113,6 @@ function installMcpAdapter(pi, options) {
             pi.setActiveTools(nextActiveTools);
         }
     }
-    function syncDirectTools(config, cache) {
-        const specs = resolveCurrentDirectTools(config, cache);
-        const nextNames = new Set(specs.map((spec) => spec.prefixedName));
-        const added = [];
-        const updated = [];
-        const deactivated = [];
-        for (const spec of specs) {
-            const fingerprint = directToolFingerprint(spec);
-            const previous = registeredDirectTools.get(spec.prefixedName);
-            if (previous !== fingerprint) {
-                registerDirectTool(spec);
-                registeredDirectTools.set(spec.prefixedName, fingerprint);
-                if (deactivatedTools.delete(spec.prefixedName)) {
-                    const activeTools = pi.getActiveTools();
-                    if (!activeTools.includes(spec.prefixedName)) {
-                        pi.setActiveTools([...activeTools, spec.prefixedName]);
-                    }
-                }
-                (previous ? updated : added).push(spec.prefixedName);
-            }
-        }
-        for (const toolName of [...registeredDirectTools.keys()]) {
-            if (nextNames.has(toolName))
-                continue;
-            registeredDirectTools.delete(toolName);
-            deactivated.push(toolName);
-        }
-        deactivateTools(deactivated);
-        return { specs, added, updated, deactivated };
-    }
     function applyDirectToolConfigChanges(changes) {
         if (!state)
             return;
@@ -196,13 +126,10 @@ function installMcpAdapter(pi, options) {
     function syncToolSurface(ctx) {
         const config = state?.config ?? earlyConfig;
         const cache = loadMetadataCache(state?.metadataCacheEnabled ?? false);
-        const result = syncDirectTools(config, cache);
-        syncProxyTool(config, cache, result.specs);
-        syncScriptTool(config);
-        const changed = result.added.length + result.updated.length + result.deactivated.length;
-        if (changed > 0 && ctx?.hasUI) {
-            ctx.ui.notify(`MCP: direct tools refreshed (+${result.added.length}, ~${result.updated.length}, -${result.deactivated.length})`, "info");
-        }
+        toolLoader.sync(config, cache, envRaw === "__none__" ? null : envDirectToolOverride, nativeAsyncSupported, specs => {
+            syncProxyTool(config, cache, specs);
+            syncScriptTool(config);
+        });
     }
     const registeredPromptCommands = new Set();
     function registerPromptCommands(specs) {
@@ -255,13 +182,18 @@ function installMcpAdapter(pi, options) {
                 }
                 syncToolSurface(ctx);
             };
+            for (const server of toolLoader.selectedServers()) {
+                if (!nextState.toolMetadata.has(server) && nextState.config.mcpServers[server])
+                    await lazyConnect(nextState, server, owner.signal);
+            }
+            owner.throwIfInactive();
             syncPromptCommands();
             syncToolSurface(ctx);
             updateStatusBar(nextState);
             initPromise = null;
             if (nextState.config.settings?.freezeDirectTools === true) {
                 directToolsFrozen = true;
-                logger.info("MCP: direct tools frozen after initial sync — reconnects won't rebuild the system prompt; use mcp({ connect: \"server\" }) to rediscover");
+                logger.info("MCP: direct tools frozen after initial sync — reconnects won't rebuild the system prompt; use mcp({ action: \"connect\", server: \"server\" }) to rediscover");
             }
         }).catch(async (err) => {
             if (!owner.isActive() || generation !== lifecycleGeneration) {
@@ -285,7 +217,10 @@ function installMcpAdapter(pi, options) {
             }
         });
     }
-    pi.on("session_start", async (_event, ctx) => {
+    async function startSession(ctx) {
+        runtimeCwd = ctx.cwd;
+        nativeAsyncSupported = supportsNativeAsync(ctx);
+        directToolsFrozen = false;
         const generation = ++lifecycleGeneration;
         const previousState = state;
         const previousOwner = currentOwner;
@@ -327,16 +262,13 @@ function installMcpAdapter(pi, options) {
         }
         const metadataCacheEnabled = ctx.isProjectTrusted()
             || !isPathInsideProject(getMetadataCachePath(), ctx.cwd);
-        activationKey = `${ctx.cwd}\0${currentConfigPath ?? ""}`;
-        preservedInactiveTools.clear();
-        for (const toolName of inactiveDirectToolsBySession.get(activationKey) ?? []) {
-            preservedInactiveTools.add(toolName);
-        }
+        toolLoader.restore(ctx);
         registerPromptCommands(resolveCachedPrompts(runtimeConfig, metadataCacheEnabled));
         const runtimeCache = loadMetadataCache(metadataCacheEnabled);
-        const cachedDirectTools = syncDirectTools(runtimeConfig, runtimeCache).specs;
-        syncProxyTool(runtimeConfig, runtimeCache, cachedDirectTools);
-        syncScriptTool(runtimeConfig);
+        toolLoader.sync(runtimeConfig, runtimeCache, envRaw === "__none__" ? null : envDirectToolOverride, nativeAsyncSupported, specs => {
+            syncProxyTool(runtimeConfig, runtimeCache, specs);
+            syncScriptTool(runtimeConfig);
+        });
         const initialization = startInitialization(ctx, owner, oauthRuntime, runtimeConfig, generation);
         if (envRaw !== undefined && envRaw !== "__none__") {
             const missingEnvDirectTools = getMissingConfiguredDirectToolServers(runtimeConfig, runtimeCache, envDirectToolOverride);
@@ -344,6 +276,20 @@ function installMcpAdapter(pi, options) {
                 await initialization;
             }
         }
+    }
+    pi.on("session_start", (_event, ctx) => startSession(ctx));
+    pi.on("session_tree", (_event, ctx) => {
+        toolLoader.restore(ctx);
+        syncToolSurface(ctx);
+    });
+    pi.on("model_select", (_event, ctx) => {
+        nativeAsyncSupported = supportsNativeAsync(ctx);
+        if (state)
+            syncToolSurface(ctx);
+    });
+    pi.on("before_agent_start", async (_event, ctx) => {
+        if (ctx.cwd !== runtimeCwd)
+            await startSession(ctx);
     });
     onSessionCheckpoint(pi, async (event) => {
         if (initPromise)
@@ -353,14 +299,8 @@ function installMcpAdapter(pi, options) {
         return prepareMcpCheckpoint(state, event);
     });
     pi.on("session_shutdown", async () => {
-        if (activationKey) {
-            const activeTools = new Set(pi.getActiveTools());
-            const inactiveTools = new Set([...registeredDirectTools.keys()].filter((name) => !activeTools.has(name)));
-            if (inactiveTools.size > 0)
-                inactiveDirectToolsBySession.set(activationKey, inactiveTools);
-            else
-                inactiveDirectToolsBySession.delete(activationKey);
-        }
+        // Cached tool selections exist before background server initialization finishes.
+        toolLoader.persist();
         ++lifecycleGeneration;
         const currentState = state;
         const owner = currentOwner;
@@ -575,6 +515,74 @@ function installMcpAdapter(pi, options) {
             }
         },
     });
+    async function getToolState(signal) {
+        const owner = currentOwner;
+        if (!state && initPromise) {
+            try {
+                const initialized = await awaitWithTimeout(abortable(initPromise, signal), INIT_WAIT_TIMEOUT_MS);
+                if (initialized === INIT_WAIT_TIMED_OUT)
+                    return {
+                        content: [{ type: "text", text: "MCP initialization is still in progress. Try again shortly." }],
+                        details: { error: "init_timeout", timeoutMs: INIT_WAIT_TIMEOUT_MS },
+                    };
+                owner?.throwIfInactive();
+                state = initialized;
+            }
+            catch (error) {
+                if (signal?.aborted || (owner && isAbortError(error, owner.signal)))
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                return { content: [{ type: "text", text: `MCP initialization failed: ${message}` }], details: { error: "init_failed", message } };
+            }
+        }
+        owner?.throwIfInactive();
+        return state ?? { content: [{ type: "text", text: "MCP not initialized" }], details: { error: "not_initialized" } };
+    }
+    async function searchAndLoad(params, signal, ctx) {
+        const ready = await getToolState(signal);
+        if ("content" in ready)
+            return { ...ready, tools: [] };
+        if (params.server && !ready.toolMetadata.has(params.server)) {
+            const discovery = await executeConnect(ready, params.server, signal);
+            if (discovery.details.error)
+                return { ...discovery, tools: [] };
+        }
+        syncToolSurface(ctx);
+        const matches = params.query.trim() ? rankToolMatches(ready, params.query, params.server)
+            : params.server ? (ready.toolMetadata.get(params.server) ?? []).filter(tool => !tool.resourceUri).map(tool => ({ server: params.server, tool })).sort((a, b) => a.tool.name.localeCompare(b.tool.name)) : [];
+        const page = paginate(matches, params.offset ?? 0, params.limit ?? 5);
+        const tools = toolLoader.activate(page.items);
+        const result = executeSearch(ready, params.query, params.server, tools.length < page.items.length, params.limit ?? 5, params.offset);
+        const guarded = await guardMcpOutput([
+            ...result.content,
+            { type: "text", text: tools.length ? `Loaded for the next request: ${JSON.stringify(tools)}` : "No direct tools loaded. Use mcp action call or tools.call in mcp_script with the returned exact names." },
+        ], resolveMcpOutputGuardOptions(ready.config.settings, ready.outputDirectory));
+        return { content: guarded.content, details: { ...result.details, ...guardedMcpDetails(guarded), loaded: tools }, tools };
+    }
+    const searchDefinition = {
+        name: "mcp_search", label: "MCP Search",
+        description: "Discover MCP tools by name, description, and parameter guidance, and load matching tools with their complete schemas for the next request. Start with a specific task query. Specify server to discover an uncached server; an empty query with server browses it. Results report incomplete catalog coverage. Resources use mcp action resources/read-resource.",
+        parameters: Type.Object({
+            query: Type.String(),
+            server: Type.Optional(Type.String()),
+            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_PAGE_SIZE, description: "Tools to load (default 5)." })),
+            offset: Type.Optional(Type.Integer({ minimum: 0 })),
+        }),
+        renderResult: renderMcpToolResult,
+        async execute(toolCallId, params, signal, _onUpdate, ctx) {
+            if (beforeExecute) {
+                if (currentOwner)
+                    await currentOwner.runCallback("beforeExecute", () => beforeExecute(toolCallId, ctx));
+                else
+                    await beforeExecute(toolCallId, ctx);
+            }
+            return searchAndLoad(params, signal, ctx);
+        },
+    };
+    if (toolLoader.native)
+        pi.registerToolSearch(searchDefinition);
+    else
+        pi.registerTool(searchDefinition);
     let scriptToolRegistered = false;
     function registerScriptTool() {
         if (scriptToolRegistered)
@@ -583,7 +591,7 @@ function installMcpAdapter(pi, options) {
             ...(beforeExecute ? { executionMode: "sequential" } : {}),
             name: "mcp_script",
             label: "MCP Script",
-            description: "Run trusted JavaScript that makes multiple MCP tool calls in one request — loop, filter, chain, or fan out between calls. For a single MCP call, search, describe, status check, or auth action, use the mcp tool instead. Discover with await tools.search({ query }) — resolves to { items: [{ path, name, server, description? }], total, hasMore, nextOffset }, not an { ok, data } envelope. Inspect with await tools.describe({ path }) — resolves to the tool descriptor with inputTypeScript when representable, otherwise the original JSON inputSchema, or { path, error: { code, message, suggestions } }. Then call tools.call(path, args) — resolves to { ok: true, data } or { ok: false, error: { code, message } }; data is the raw MCP result: tool calls usually return { content, structuredContent? }, while resource reads return { contents }. The sandbox has no Node, filesystem, or network globals. Use direct flat calls when the name is already known; use emit(value) for user-visible output. Load the mcp-scripting skill for the full workflow guide.",
+            description: "Compose MCP calls with trusted JavaScript: await tools.search({query, server?}), tools.describe({path}), tools.call(path,args). Describe returns complete JSON schemas. Calls return {ok,data} with raw MCP results, or {ok:false,error,data?}. Resources: tools.resources({server}), tools.readResource({server,uri}). Saved results: tools.readResult({ref,path?,fields?,offset?,limit?}); never repeats a remote call. Use emit(value) to return selected data or content blocks. No Node, filesystem, or network globals. Prefer a direct tool for one call; use scripts for loops, filtering and chains.",
             promptSnippet: "Batch multiple MCP tool calls in one JavaScript request (loop, filter, chain)",
             parameters: Type.Object({
                 code: Type.String({ description: "Trusted JavaScript MCP script. Use tools.<prefixedToolName>(args) and emit(value)." }),
@@ -593,37 +601,10 @@ function installMcpAdapter(pi, options) {
             }),
             renderResult: renderMcpToolResult,
             async execute(toolCallId, params, signal, _onUpdate, ctx) {
-                const executeOwner = currentOwner;
-                if (!state && initPromise) {
-                    try {
-                        const initialized = await awaitWithTimeout(abortable(initPromise, signal), INIT_WAIT_TIMEOUT_MS);
-                        if (initialized === INIT_WAIT_TIMED_OUT) {
-                            return {
-                                content: [{ type: "text", text: "MCP initialization is still in progress. Try again shortly." }],
-                                details: { mode: "script", error: "init_timeout", timeoutMs: INIT_WAIT_TIMEOUT_MS },
-                            };
-                        }
-                        executeOwner?.throwIfInactive();
-                        state = initialized;
-                    }
-                    catch (error) {
-                        if (signal?.aborted || (executeOwner && isAbortError(error, executeOwner.signal)))
-                            throw error;
-                        const message = error instanceof Error ? error.message : String(error);
-                        return {
-                            content: [{ type: "text", text: `MCP initialization failed: ${message}` }],
-                            details: { mode: "script", error: "init_failed", message },
-                        };
-                    }
-                }
-                if (!state) {
-                    return {
-                        content: [{ type: "text", text: "MCP not initialized" }],
-                        details: { mode: "script", error: "not_initialized" },
-                    };
-                }
-                executeOwner?.throwIfInactive();
-                return runMcpScript(state, params.code, params.timeoutMs ?? options.defaultScriptTimeoutMs, getPiTools, signal, toolCallId, beforeExecute ? (callSignal, operation) => beforeExecute(toolCallId, { ...ctx, signal: callSignal }, operation) : undefined);
+                const ready = await getToolState(signal);
+                if ("content" in ready)
+                    return ready;
+                return runMcpScript(ready, params.code, params.timeoutMs ?? options.defaultScriptTimeoutMs, getPiTools, signal, toolCallId, beforeExecute ? (callSignal, operation) => beforeExecute(toolCallId, { ...ctx, signal: callSignal }, operation) : undefined);
             },
         });
         scriptToolRegistered = true;
@@ -644,147 +625,60 @@ function installMcpAdapter(pi, options) {
     function registerProxyTool(description) {
         pi.registerTool({
             ...(beforeExecute ? { executionMode: "sequential" } : {}),
-            name: "mcp",
-            label: "MCP",
-            description,
-            promptSnippet: "MCP gateway — status, search, describe, auth, and single MCP tool calls",
+            name: "mcp", label: "MCP", description,
+            promptSnippet: "MCP server operations, resources, saved result readback, and fallback tool calls",
             renderCall: renderMcpProxyToolCall,
-            parameters: Type.Object({
-                tool: Type.Optional(Type.String({ maxLength: MAX_TOOL_NAME_LENGTH, description: "Tool name to call (e.g., 'xcodebuild_list_sims')" })),
-                args: Type.Optional(Type.Union([
-                    Type.String({ description: "Arguments as a JSON string (e.g., '{\"key\": \"value\"}')" }),
-                    Type.Object({}, {
-                        additionalProperties: true,
-                        description: 'Arguments as a JSON object (e.g., { "key": "value" })',
-                    }),
-                ], { description: "Tool arguments as a JSON object, or as a JSON string encoding one" })),
-                connect: Type.Optional(Type.String({ description: "Server name to connect (lazy connect + metadata refresh)" })),
-                describe: Type.Optional(Type.String({ maxLength: MAX_TOOL_NAME_LENGTH, description: "Tool name to describe (shows parameters)" })),
-                instructions: Type.Optional(Type.String({ description: "Server name to show that server's usage instructions" })),
-                search: Type.Optional(Type.String({ description: "Search tools by name/description" })),
-                includeSchemas: Type.Optional(Type.Boolean({ description: "Include parameter schemas in search results (default: true)" })),
-                limit: Type.Optional(Type.Number({ minimum: 1, maximum: MAX_PAGE_SIZE, description: "Maximum search or server-list results to return (default: 12, max: 100)" })),
-                offset: Type.Optional(Type.Number({ minimum: 0, description: "Search or server-list result offset (default: 0)" })),
-                server: Type.Optional(Type.String({ description: "Filter to specific server (also disambiguates tool calls)" })),
-                action: Type.Optional(Type.String({ description: "Action: 'ui-messages', 'auth-start', or 'auth-complete'" })),
-            }),
+            parameters: gatewayParameters,
+            prepareArguments: prepareGatewayArguments,
             renderResult: renderMcpToolResult,
-            async execute(toolCallId, params, signal, _onUpdate, ctx) {
-                // Non-call modes have no resolved MCP operation; hosts keep their conservative policy.
-                if (!params.tool || params.action === "ui-messages" || params.action === "auth-start" || params.action === "auth-complete") {
-                    if (beforeExecute) {
-                        if (currentOwner)
-                            await currentOwner.runCallback("beforeExecute", () => beforeExecute(toolCallId, ctx));
-                        else
-                            await beforeExecute(toolCallId, ctx);
-                    }
-                }
-                const executeOwner = currentOwner;
-                let parsedArgs;
-                if (params.args !== undefined && params.args !== "") {
-                    let args;
-                    if (typeof params.args === "string") {
-                        try {
-                            args = JSON.parse(params.args);
-                        }
-                        catch (error) {
-                            if (error instanceof SyntaxError) {
-                                throw new Error(`Invalid args JSON: ${error.message}`, { cause: error });
-                            }
-                            throw error;
-                        }
-                    }
-                    else {
-                        args = params.args;
-                    }
-                    if (typeof args !== "object" || args === null || Array.isArray(args)) {
-                        const gotType = Array.isArray(args) ? "array" : args === null ? "null" : typeof args;
-                        throw new Error(`Invalid args: expected a JSON object, got ${gotType}`);
-                    }
-                    parsedArgs = args;
-                }
-                if (!state && initPromise) {
-                    try {
-                        const initialized = await awaitWithTimeout(abortable(initPromise, signal), INIT_WAIT_TIMEOUT_MS);
-                        if (initialized === INIT_WAIT_TIMED_OUT) {
-                            return {
-                                content: [{ type: "text", text: "MCP initialization is still in progress. Try again shortly." }],
-                                details: { error: "init_timeout", timeoutMs: INIT_WAIT_TIMEOUT_MS },
-                            };
-                        }
-                        executeOwner?.throwIfInactive();
-                        state = initialized;
-                    }
-                    catch (error) {
-                        if (signal?.aborted || (executeOwner && isAbortError(error, executeOwner.signal)))
-                            throw error;
-                        const message = error instanceof Error ? error.message : String(error);
-                        return {
-                            content: [{ type: "text", text: `MCP initialization failed: ${message}` }],
-                            details: { error: "init_failed", message },
-                        };
-                    }
-                }
-                if (!state) {
-                    return {
-                        content: [{ type: "text", text: "MCP not initialized" }],
-                        details: { error: "not_initialized" },
-                    };
-                }
-                executeOwner?.throwIfInactive();
-                if (params.action === "ui-messages") {
-                    return executeUiMessages(state);
+            async execute(toolCallId, rawParams, signal, _onUpdate, ctx) {
+                const params = prepareGatewayArguments(rawParams);
+                if (beforeExecute && params.action !== "call" && params.action !== "read-resource") {
+                    if (currentOwner)
+                        await currentOwner.runCallback("beforeExecute", () => beforeExecute(toolCallId, ctx));
+                    else
+                        await beforeExecute(toolCallId, ctx);
                 }
-                if (params.action === "auth-start") {
-                    if (!params.server) {
-                        return {
-                            content: [{ type: "text", text: "auth-start requires `server`. Example: mcp({ action: \"auth-start\", server: \"linear-server\" })" }],
-                            details: { mode: "auth-start", error: "missing_server" },
-                        };
-                    }
-                    return signal
-                        ? executeAuthStart(state, params.server, signal)
-                        : executeAuthStart(state, params.server);
+                const ready = await getToolState(signal);
+                if ("content" in ready)
+                    return ready;
+                const present = async (result) => {
+                    const guarded = await guardMcpOutput(result.content, resolveMcpOutputGuardOptions(ready.config.settings, ready.outputDirectory));
+                    return { content: guarded.content, details: { ...result.details, ...guardedMcpDetails(guarded) } };
+                };
+                const beforeDispatch = beforeExecute
+                    ? (callSignal, operation) => beforeExecute(toolCallId, { ...ctx, signal: callSignal }, operation)
+                    : undefined;
+                if (params.server && ["list", "search", "describe", "instructions"].includes(params.action) && !ready.toolMetadata.has(params.server)) {
+                    const discovery = await executeConnect(ready, params.server, signal);
+                    if (discovery.details.error)
+                        return discovery;
+                    syncToolSurface(ctx);
                 }
-                if (params.action === "auth-complete") {
-                    if (!params.server) {
-                        return {
-                            content: [{ type: "text", text: "auth-complete requires `server`." }],
-                            details: { mode: "auth-complete", error: "missing_server" },
-                        };
+                switch (params.action) {
+                    case "ui-messages": return executeUiMessages(ready);
+                    case "auth-start": return executeAuthStart(ready, params.server, signal);
+                    case "auth-complete": {
+                        const input = params.args?.redirectUrl ?? params.args?.code ?? params.args?.input;
+                        if (input !== undefined && (typeof input !== "string" || input.trim().length === 0))
+                            throw new Error("auth-complete requires a non-empty redirectUrl, code, or input");
+                        return executeAuthComplete(ready, params.server, input, signal);
                     }
-                    const input = parsedArgs?.redirectUrl ?? parsedArgs?.code ?? parsedArgs?.input;
-                    if (input !== undefined && (typeof input !== "string" || input.trim().length === 0)) {
-                        return {
-                            content: [{ type: "text", text: "auth-complete accepts a non-empty `redirectUrl`, `code`, or `input`, or no args to use the browser callback." }],
-                            details: { mode: "auth-complete", error: "missing_input" },
-                        };
+                    case "call": return executeCall(ready, params.tool, params.args, params.server, getPiTools, signal, { toolCallId }, beforeDispatch);
+                    case "connect": {
+                        const result = await executeConnect(ready, params.server, signal, params.limit, params.offset);
+                        syncToolSurface(ctx);
+                        return present(result);
                     }
-                    return signal
-                        ? executeAuthComplete(state, params.server, input, signal)
-                        : executeAuthComplete(state, params.server, input);
-                }
-                if (params.tool) {
-                    return executeCall(state, params.tool, parsedArgs, params.server, getPiTools, signal, undefined, { toolCallId }, beforeExecute ? (callSignal, operation) => beforeExecute(toolCallId, { ...ctx, signal: callSignal }, operation) : undefined);
-                }
-                if (params.connect) {
-                    const result = await executeConnect(state, params.connect, signal, params.limit, params.offset);
-                    syncToolSurface(ctx);
-                    return result;
+                    case "describe": return present(executeDescribe(ready, params.tool, params.server));
+                    case "instructions": return present(executeInstructions(ready, params.server));
+                    case "search": return present(executeSearch(ready, params.query, params.server, params.includeSchemas, params.limit, params.offset));
+                    case "list": return present(executeList(ready, params.server, params.limit, params.offset));
+                    case "resources": return present(await executeResourceList(ready, params.server, params.limit, params.offset, signal));
+                    case "read-resource": return executeResourceRead(ready, params.server, params.uri, signal, { toolCallId }, beforeDispatch);
+                    case "read-result": return readMcpResult({ ref: params.ref, ...(params.path !== undefined ? { path: params.path } : {}), ...(params.fields ? { fields: params.fields } : {}), ...(params.offset !== undefined ? { offset: params.offset } : {}), ...(params.limit !== undefined ? { limit: params.limit } : {}) }, resolveMcpOutputGuardOptions(ready.config.settings, ready.outputDirectory));
+                    case "status": return present(executeStatus(ready));
                 }
-                if (params.describe) {
-                    return executeDescribe(state, params.describe);
-                }
-                if (params.instructions) {
-                    return executeInstructions(state, params.instructions);
-                }
-                if (params.search !== undefined) {
-                    return executeSearch(state, params.search, params.server, params.includeSchemas, params.limit, params.offset);
-                }
-                if (params.server) {
-                    return executeList(state, params.server, params.limit, params.offset);
-                }
-                return executeStatus(state);
             },
         });
         proxyToolRegistered = true;
@@ -792,7 +686,19 @@ function installMcpAdapter(pi, options) {
     }
     function syncProxyTool(config, cache, directSpecs) {
         const missingConfiguredDirectToolServers = getMissingConfiguredDirectToolServers(config, cache, envRaw === undefined || envRaw === "__none__" ? undefined : envDirectToolOverride);
+        const hasPinnedResources = envRaw !== "__none__" && Object.entries(config.mcpServers).some(([server, definition]) => {
+            if (definition.disabled === true)
+                return false;
+            const selection = directToolSelection(config, server, envDirectToolOverride);
+            if (!selection)
+                return false;
+            const entry = cache?.servers[server];
+            const metadata = state?.toolMetadata.get(server) ?? (entry && isServerCacheValid(entry, definition)
+                ? reconstructToolMetadata(server, entry, config.settings?.toolPrefix ?? "server", definition) : []);
+            return metadata.some(tool => tool.resourceUri && (selection === true || selection.includes(tool.originalName)));
+        });
         const shouldRegisterProxyTool = config.settings?.disableProxyTool !== true
+            || hasPinnedResources
             || directSpecs.length === 0
             || missingConfiguredDirectToolServers.length > 0;
         if (shouldRegisterProxyTool) {
@@ -813,8 +719,7 @@ function installMcpAdapter(pi, options) {
     }
     // A transform needs the session context before any configured tool surface is registered.
     if (!options.transformConfig) {
-        const initialDirectTools = syncDirectTools(earlyConfig, earlyCache).specs;
-        syncProxyTool(earlyConfig, earlyCache, initialDirectTools);
+        syncProxyTool(earlyConfig, earlyCache, []);
         syncScriptTool(earlyConfig);
     }
 }

package/dist/init.js

@@ -1,5 +1,4 @@
 import { isServerDisabled } from "./types.js";
-import { existsSync } from "node:fs";
 import { cloneMcpConfig, isPathInsideProject, loadMcpConfig } from "./config.js";
 import { ConsentManager } from "./consent-manager.js";
 import { McpLifecycleManager } from "./lifecycle.js";
@@ -177,18 +176,7 @@ export async function initializeMcp(pi, ctx, owner = createMcpRuntimeOwner(), op
     }
     const idleSetting = typeof config.settings?.idleTimeout === "number" ? config.settings.idleTimeout : 10;
     lifecycle.setGlobalIdleTimeout(idleSetting);
-    const cachePath = getMetadataCachePath();
-    const cacheFileExists = metadataCacheEnabled && existsSync(cachePath);
-    let cache = loadMetadataCache(metadataCacheEnabled);
-    let bootstrapAll = false;
-    if (!cacheFileExists) {
-        bootstrapAll = true;
-        saveMetadataCache({ version: 1, servers: {} }, metadataCacheEnabled);
-    }
-    else if (!cache) {
-        cache = { version: 1, servers: {} };
-        saveMetadataCache(cache, metadataCacheEnabled);
-    }
+    const cache = loadMetadataCache(metadataCacheEnabled);
     const prefix = config.settings?.toolPrefix ?? "server";
     for (const [name, definition] of serverEntries) {
         const lifecycleMode = definition.lifecycle ?? "lazy";
@@ -213,12 +201,10 @@ export async function initializeMcp(pi, ctx, owner = createMcpRuntimeOwner(), op
             }
         }
     }
-    const startupServers = bootstrapAll
-        ? serverEntries
-        : serverEntries.filter(([, definition]) => {
-            const mode = definition.lifecycle ?? "lazy";
-            return mode === "keep-alive" || mode === "eager";
-        });
+    const startupServers = serverEntries.filter(([, definition]) => {
+        const mode = definition.lifecycle ?? "lazy";
+        return mode === "keep-alive" || mode === "eager";
+    });
     if (ui && startupServers.length > 0) {
         const status = formatMcpStatus(state.config, `connecting to ${startupServers.length} servers...`);
         ui.setStatus("mcp", status);
@@ -324,7 +310,7 @@ export async function initializeMcp(pi, ctx, owner = createMcpRuntimeOwner(), op
             const bootstrapped = bootstrapResults.filter(r => r.ok).map(r => r.name);
             owner.throwIfInactive();
             if (bootstrapped.length > 0 && ui) {
-                ui.notify(`MCP: direct tools for ${bootstrapped.join(", ")} will be available after restart`, "info");
+                ui.notify(`MCP: tools discovered for ${bootstrapped.join(", ")}`, "info");
             }
         }
     }