@fitchmultz/pi-mcp-adapter 5.0.0 → 6.0.0

package/dist/proxy-modes.js

@@ -1,13 +1,12 @@
 import { DEFAULT_REQUEST_TIMEOUT_MSEC, UrlElicitationRequiredError } from "@modelcontextprotocol/client";
 import { getServerPrefix, isServerDisabled, isNonInteractiveOAuth, parseUiPromptHandoff, resolveToolPrefix } from "./types.js";
-import { lazyConnect, markKeepAliveAfterConnect, notifyToolMetadataUpdated, updateServerMetadata, updateMetadataCache, getFailureAgeSeconds, updateStatusBar, clearFailure, recordFailure } from "./init.js";
+import { lazyConnect, markKeepAliveAfterConnect, notifyToolMetadataUpdated, updateMetadataCache, getFailureAgeSeconds, updateStatusBar, clearFailure, recordFailure } from "./init.js";
 import { abortable, throwIfAborted } from "./abort.js";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
-import { buildToolMetadata, findToolByName, formatSchema } from "./tool-metadata.js";
-import { renderTsShape } from "./ts-shape.js";
+import { buildToolMetadata, catalogCoverage, findToolByName, formatSchema, toToolDescriptor } from "./tool-metadata.js";
 import { reconstructPromptMetadata } from "./metadata-cache.js";
-import { resolveMcpResultContent, transformMcpContent } from "./tool-registrar.js";
-import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.js";
+import { renderMcpResultContent } from "./tool-registrar.js";
+import { guardMcpOutput, guardedMcpDetails, retainMcpResult, resolveMcpOutputGuardOptions, formatMcpResultReference } from "./mcp-output-guard.js";
 import { maybeStartUiSession, summarizeUiSessionResult } from "./ui-session.js";
 import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.js";
 import { authenticate, completeAuthFromInput, startAuth, supportsOAuth } from "./mcp-auth-flow.js";
@@ -66,7 +65,7 @@ function formatManualAuthInstructions(serverName, authorizationUrl) {
         "If the browser cannot reach the callback, copy the full redirected localhost URL from your address bar and send it back with:",
         `mcp({ action: "auth-complete", server: "${serverName}", args: { redirectUrl: "PASTE_REDIRECT_URL_HERE" } })`,
         "",
-        'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`. JSON-string args remain supported.',
+        'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`.',
         portNote.trimEnd(),
     ].filter(Boolean).join("\n");
 }
@@ -204,7 +203,7 @@ export function executeStatus(state) {
         const disabled = isServerDisabled(definition);
         const connection = disabled ? undefined : state.manager.getConnection(name);
         const metadata = disabled ? undefined : state.toolMetadata.get(name);
-        const toolCount = metadata?.length ?? 0;
+        const toolCount = metadata?.filter(tool => !tool.resourceUri).length ?? 0;
         const failedAgo = disabled ? null : getFailureAgeSeconds(state, name);
         let status = disabled ? "disabled" : "not connected";
         if (!disabled && connection?.status === "connected") {
@@ -225,6 +224,7 @@ export function executeStatus(state) {
     const enabledServers = servers.filter(s => !s.disabled);
     const totalTools = enabledServers.reduce((sum, s) => sum + s.toolCount, 0);
     const connectedCount = enabledServers.filter(s => s.status === "connected").length;
+    const coverage = catalogCoverage(state);
     let text = `MCP: ${connectedCount}/${enabledServers.length} connected, ${totalTools} tools available (calls connect lazily)`;
     if (disabledCount > 0)
         text += ` (${disabledCount} disabled)`;
@@ -250,14 +250,16 @@ export function executeStatus(state) {
             text += `✗ ${server.name} (failed ${server.failedAgo ?? 0}s ago)\n`;
             continue;
         }
-        text += `○ ${server.name} (not connected)\n`;
+        text += `○ ${server.name} (not discovered)\n`;
     }
     if (servers.length > 0) {
-        text += `\nmcp({ server: "name" }) to browse tools, mcp({ search: "..." }) to search`;
+        text += `\nmcp_search({ query: "...", server: "name" }) to discover tools; mcp({ action: "resources", server: "name" }) for resources.`;
+        if (!coverage.complete)
+            text += `\nPartial catalog: ${coverage.unknownServers.length} undiscovered server(s).`;
     }
     return {
         content: [{ type: "text", text: text.trim() }],
-        details: { mode: "status", servers, totalTools, connectedCount, disabledCount },
+        details: { mode: "status", servers, totalTools, connectedCount, disabledCount, coverage },
     };
 }
 export async function executeAuthStart(state, serverName, signal) {
@@ -266,7 +268,7 @@ export async function executeAuthStart(state, serverName, signal) {
     const definition = state.config.mcpServers[serverName];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
             details: { mode: "auth-start", error: "not_found", server: serverName },
         };
     }
@@ -312,7 +314,7 @@ export async function executeAuthComplete(state, serverName, input, signal) {
     const definition = state.config.mcpServers[serverName];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
             details: { mode: "auth-complete", error: "not_found", server: serverName },
         };
     }
@@ -338,7 +340,7 @@ export async function executeAuthComplete(state, serverName, input, signal) {
         clearFailure(state, serverName);
         updateStatusBar(state);
         return {
-            content: [{ type: "text", text: `OAuth authentication successful for "${serverName}". Run mcp({ connect: "${serverName}" }) to connect with the new token.` }],
+            content: [{ type: "text", text: `OAuth authentication successful for "${serverName}". Run mcp({ action: "connect", server: "${serverName}" }) to connect with the new token.` }],
             details: { mode: "auth-complete", server: serverName, authenticated: true },
         };
     }
@@ -350,63 +352,44 @@ export async function executeAuthComplete(state, serverName, input, signal) {
         };
     }
 }
-export function executeDescribe(state, toolName) {
-    let serverName;
-    let toolMeta;
-    let disabledMatch;
-    for (const [server, metadata] of state.toolMetadata.entries()) {
-        const found = findToolByName(metadata, toolName);
-        if (!found)
-            continue;
-        if (isServerDisabled(state.config.mcpServers[server])) {
-            disabledMatch ??= server;
-            continue;
-        }
-        serverName = server;
-        toolMeta = found;
-        break;
-    }
-    if (!serverName || !toolMeta) {
-        if (disabledMatch)
-            return disabledResult("describe", disabledMatch);
-        const suggestions = rankSuggestions(state, toolName, 5);
+export function executeDescribe(state, toolName, serverFilter) {
+    if (serverFilter && isServerDisabled(state.config.mcpServers[serverFilter]))
+        return disabledResult("describe", serverFilter);
+    const catalog = [...state.toolMetadata].flatMap(([server, tools]) => (!serverFilter || serverFilter === server) && state.config.mcpServers[server] && !isServerDisabled(state.config.mcpServers[server])
+        ? tools.map(tool => ({ server, tool })) : []);
+    const originals = serverFilter ? catalog.filter(({ tool }) => tool.originalName === toolName) : [];
+    const exact = originals.length ? originals : catalog.filter(({ tool }) => tool.name === toolName);
+    const matches = exact.length ? exact : catalog.filter(({ tool }) => tool.name.replace(/-/g, "_") === toolName.replace(/-/g, "_"));
+    if (matches.length > 1)
+        return {
+            content: [{ type: "text", text: `Tool ${JSON.stringify(toolName)} is ambiguous. Specify server and original tool name: ${JSON.stringify(matches.map(({ server, tool }) => ({ server, tool: tool.originalName })))}` }],
+            details: { mode: "describe", error: "ambiguous_tool", requestedTool: toolName },
+        };
+    const match = matches[0];
+    if (!match) {
+        const disabled = [...state.toolMetadata].find(([server, tools]) => isServerDisabled(state.config.mcpServers[server]) && findToolByName(tools, toolName));
+        if (disabled)
+            return disabledResult("describe", disabled[0]);
+        const suggestions = rankSuggestions(state, toolName, 5, serverFilter);
         const hint = suggestions.length > 0
-            ? `Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ describe: "${suggestions[0]}" }).`
-            : `Use mcp({ search: "..." }) to search.`;
+            ? `Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ action: "describe", tool: "${suggestions[0]}" }).`
+            : `Use mcp_search({ query: "..." }) to search.`;
         return {
             content: [{ type: "text", text: `Tool "${toolName}" not found. ${hint}` }],
             details: { mode: "describe", error: "tool_not_found", requestedTool: toolName, suggestions },
         };
     }
-    const approvalMarker = isToolCallApprovalRequired(state.config, serverName, toolMeta)
-        ? " (requires approval)"
-        : "";
-    let text = `${toolMeta.name}${approvalMarker}\n`;
-    text += `Server: ${serverName}\n`;
-    if (toolMeta.resourceUri) {
-        text += `Type: Resource (reads from ${toolMeta.resourceUri})\n`;
-    }
-    text += `\n${toolMeta.description || "(no description)"}\n`;
-    if (toolMeta.annotations)
-        text += `\nAnnotations: ${JSON.stringify(toolMeta.annotations)}\n`;
-    if (toolMeta.inputSchema && !toolMeta.resourceUri) {
-        const shape = renderTsShape(toolMeta.inputSchema);
-        text += shape === null ? `\nParameters:\n${formatSchema(toolMeta.inputSchema)}` : `\nShape:\n${shape}`;
-    }
-    else if (toolMeta.resourceUri) {
-        text += `\nNo parameters required (resource tool).`;
-    }
-    else {
-        text += `\nNo parameters defined.`;
-    }
+    const { server: serverName, tool: toolMeta } = match;
+    const descriptor = toToolDescriptor(serverName, toolMeta);
+    const approvalRequired = isToolCallApprovalRequired(state.config, serverName, toolMeta);
     return {
-        content: [{ type: "text", text: text.trim() }],
+        content: [{ type: "text", text: JSON.stringify({ ...descriptor, ...(toolMeta.resourceUri ? { resourceUri: toolMeta.resourceUri, readWith: { action: "read-resource", server: serverName, uri: toolMeta.resourceUri } } : {}), ...(approvalRequired ? { approvalRequired: true } : {}) }, null, 2) }],
         details: { mode: "describe", tool: toolMeta, server: serverName },
     };
 }
 export function executeSearch(state, query, server, includeSchemas, limit = 12, offset = 0) {
     const showSchemas = includeSchemas !== false;
-    const searchCall = (nextOffset) => `mcp({ search: ${JSON.stringify(query)}${server ? `, server: ${JSON.stringify(server)}` : ""}${showSchemas ? "" : ", includeSchemas: false"}, limit: ${limit}, offset: ${nextOffset} })`;
+    const searchCall = (nextOffset) => `mcp({ action: "search", query: ${JSON.stringify(query)}${server ? `, server: ${JSON.stringify(server)}` : ""}${showSchemas ? "" : ", includeSchemas: false"}, limit: ${limit}, offset: ${nextOffset} })`;
     if (server && isServerDisabled(state.config.mcpServers[server]))
         return disabledResult("search", server);
     let matches;
@@ -417,7 +400,7 @@ export function executeSearch(state, query, server, includeSchemas, limit = 12,
                 details: { mode: "search", error: "empty_query" },
             };
         }
-        matches = (state.toolMetadata.get(server) ?? [])
+        matches = (state.toolMetadata.get(server) ?? []).filter(tool => !tool.resourceUri)
             .map(tool => ({ server, tool, score: 0 }))
             .sort((a, b) => a.tool.name.localeCompare(b.tool.name));
     }
@@ -425,11 +408,13 @@ export function executeSearch(state, query, server, includeSchemas, limit = 12,
         matches = rankToolMatches(state, query, server);
     }
     const page = paginate(matches, offset, limit);
+    const coverage = catalogCoverage(state, server);
+    const coverageNotice = coverage.complete ? "" : `\nCatalog is incomplete. Undiscovered servers: ${coverage.unknownServers.join(", ")}. Search with server to discover one.`;
     if (page.total === 0) {
         const msg = server ? `No tools matching "${query}" in "${server}"` : `No tools matching "${query}"`;
         return {
-            content: [{ type: "text", text: msg }],
-            details: { mode: "search", matches: [], count: 0, hasMore: false, nextOffset: null, query },
+            content: [{ type: "text", text: msg + coverageNotice }],
+            details: { mode: "search", matches: [], count: 0, hasMore: false, nextOffset: null, query, coverage },
         };
     }
     if (page.items.length === 0) {
@@ -445,18 +430,7 @@ export function executeSearch(state, query, server, includeSchemas, limit = 12,
             ? " (requires approval)"
             : "";
         if (showSchemas) {
-            text += `${match.tool.name}${approvalMarker}\n`;
-            text += `  ${match.tool.description || "(no description)"}\n`;
-            if (match.tool.inputSchema && !match.tool.resourceUri) {
-                const shape = renderTsShape(match.tool.inputSchema);
-                text += shape === null
-                    ? `\n  Parameters:\n${formatSchema(match.tool.inputSchema, "    ")}\n`
-                    : `\n  Shape:\n${shape.split("\n").map(line => `    ${line}`).join("\n")}\n`;
-            }
-            else if (match.tool.resourceUri) {
-                text += "  No parameters (resource tool).\n";
-            }
-            text += "\n";
+            text += `${JSON.stringify({ ...toToolDescriptor(match.server, match.tool), ...(approvalMarker ? { approvalRequired: true } : {}) }, null, 2)}\n\n`;
         }
         else {
             text += `- ${match.tool.name}${approvalMarker}`;
@@ -471,9 +445,10 @@ export function executeSearch(state, query, server, includeSchemas, limit = 12,
         ? `\n${first}-${first + page.items.length - 1} of ${page.total} — ${nextSearch} for more\n`
         : `\n${first}-${first + page.items.length - 1} of ${page.total} — end\n`;
     return {
-        content: [{ type: "text", text: text.trim() }],
+        content: [{ type: "text", text: text.trim() + coverageNotice }],
         details: {
             mode: "search",
+            coverage,
             matches: page.items.map(match => ({ server: match.server, tool: match.tool.name, score: match.score })),
             count: page.total,
             hasMore: page.hasMore,
@@ -486,13 +461,13 @@ export function executeList(state, server, limit = 12, offset = 0) {
     const definition = state.config.mcpServers[server];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({}) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers.` }],
             details: { mode: "list", server, tools: [], count: 0, error: "not_found" },
         };
     }
     if (isServerDisabled(definition))
         return disabledResult("list", server);
-    const metadata = state.toolMetadata.get(server);
+    const metadata = state.toolMetadata.get(server)?.filter(tool => !tool.resourceUri);
     const connection = state.manager.getConnection(server);
     const instructions = state.serverInstructions.get(server);
     let instructionsText = "";
@@ -500,7 +475,7 @@ export function executeList(state, server, limit = 12, offset = 0) {
         const preview = truncateAtWord(instructions, INSTRUCTIONS_PREVIEW_LENGTH);
         instructionsText = `\n\nServer instructions:\n${preview}`;
         if (preview !== instructions) {
-            instructionsText += `\nUse mcp({ instructions: "${server}" }) for the full text.`;
+            instructionsText += `\nUse mcp({ action: "instructions", server: "${server}" }) for the full text.`;
         }
     }
     if (!metadata?.length) {
@@ -517,14 +492,14 @@ export function executeList(state, server, limit = 12, offset = 0) {
             };
         }
         return {
-            content: [{ type: "text", text: `Server "${server}" is configured but not connected. Use mcp({ connect: "${server}" }) or /mcp reconnect ${server} to retry.${instructionsText}` }],
+            content: [{ type: "text", text: `Server "${server}" is configured but not connected. Use mcp({ action: "connect", server: "${server}" }) or /mcp reconnect ${server} to retry.${instructionsText}` }],
             details: { mode: "list", server, tools: [], count: 0, error: "not_connected", hasInstructions: Boolean(instructions) },
         };
     }
     const page = paginate(metadata, offset, limit);
     if (page.items.length === 0) {
         return {
-            content: [{ type: "text", text: `No tools at offset ${offset}; "${server}" has ${page.total} tools. Retry with mcp({ server: ${JSON.stringify(server)}, limit: ${limit}, offset: 0 }).` }],
+            content: [{ type: "text", text: `No tools at offset ${offset}; "${server}" has ${page.total} tools. Retry with mcp({ action: "list", server: ${JSON.stringify(server)}, limit: ${limit}, offset: 0 }).` }],
             details: { mode: "list", error: "offset_out_of_range", server, tools: [], count: page.total, hasMore: false, nextOffset: null, hasInstructions: Boolean(instructions) },
         };
     }
@@ -539,7 +514,7 @@ export function executeList(state, server, limit = 12, offset = 0) {
     }
     const first = (Number.isFinite(offset) ? Math.max(0, Math.trunc(offset)) : 0) + 1;
     text += page.hasMore
-        ? `\n${first}-${first + page.items.length - 1} of ${page.total} — mcp({ server: ${JSON.stringify(server)}, limit: ${limit}, offset: ${page.nextOffset} }) for more`
+        ? `\n${first}-${first + page.items.length - 1} of ${page.total} — mcp({ action: "list", server: ${JSON.stringify(server)}, limit: ${limit}, offset: ${page.nextOffset} }) for more`
         : `\n${first}-${first + page.items.length - 1} of ${page.total} — end`;
     text += instructionsText;
     return {
@@ -559,7 +534,7 @@ export function executeInstructions(state, server) {
     const definition = state.config.mcpServers[server];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({}) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${server}" not found. Use mcp({ action: "status" }) to see available servers.` }],
             details: { mode: "instructions", server, error: "not_found" },
         };
     }
@@ -580,7 +555,7 @@ export function executeInstructions(state, server) {
         };
     }
     return {
-        content: [{ type: "text", text: `No instructions cached for "${server}". Use mcp({ connect: "${server}" }) to connect and refresh.` }],
+        content: [{ type: "text", text: `No instructions cached for "${server}". Use mcp({ action: "connect", server: "${server}" }) to connect and refresh.` }],
         details: { mode: "instructions", server, error: "not_connected" },
     };
 }
@@ -590,7 +565,7 @@ export async function executeConnect(state, serverName, signal, limit, offset) {
     const definition = state.config.mcpServers[serverName];
     if (!definition) {
         return {
-            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
+            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }],
             details: { mode: "connect", error: "not_found", server: serverName },
         };
     }
@@ -627,6 +602,7 @@ export async function executeConnect(state, serverName, signal, limit, offset) {
         const prefix = state.config.settings?.toolPrefix ?? "server";
         const { metadata } = buildToolMetadata(connection.tools, connection.resources, definition, serverName, prefix);
         state.toolMetadata.set(serverName, metadata);
+        state.resourceCounts?.set(serverName, connection.resources.length);
         if (!connection.promptDiscoveryFailed) {
             state.promptMetadata?.set(serverName, reconstructPromptMetadata(serverName, connection.prompts ?? [], prefix, definition));
             state.promptMetadataLive?.add(serverName);
@@ -658,12 +634,11 @@ export async function executeConnect(state, serverName, signal, limit, offset) {
 /**
  * Executes an already-approved tool call against a connected server.
  *
- * Both the `mcp` proxy and direct tools reach this with a resolved target and a
- * live connection; everything before this point (name resolution, connect and
- * auth strategy, approval) differs between them and stays with the caller.
+ * Direct, gateway, resource and script calls share executeCall preparation.
+ * Raw scripts skip content rendering but retain protocol results and artifacts.
  */
 export async function runToolCall(state, serverName, target, args, options) {
-    const { detailsBase, signal, recoverAuthConnection, authRequiredMessage, autoAuthAttempted, onRawResult } = options;
+    const { detailsBase, signal, recoverAuthConnection, authRequiredMessage, autoAuthAttempted } = options;
     const configuredOptions = state.manager.getRequestOptions?.(serverName, options.ownedSignal);
     const callerSignal = combineAbortSignals(configuredOptions?.signal, options.ownedSignal);
     const outputGuardOptions = resolveMcpOutputGuardOptions(state.config.settings, state.outputDirectory);
@@ -705,8 +680,7 @@ export async function runToolCall(state, serverName, target, args, options) {
                 onNeedsAuth: recoverAuthConnection,
             })
             : null;
-        // Frozen direct-tool schemas may be older than the live catalog. Never use
-        // stale cached hints in preference to the connected server's annotations.
+        // UI preparation can replace the connection; use its current annotations.
         const liveTools = state.manager.getConnection(serverName)?.tools;
         const annotations = liveTools
             ? liveTools.find(tool => tool.name === target.originalName)?.annotations
@@ -744,46 +718,32 @@ export async function runToolCall(state, serverName, target, args, options) {
             await capture({ ...call, phase: "after", result });
             return result;
         };
-        if (target.resourceUri) {
-            const result = await dispatch(() => withSessionRecovery(recovery, serverName, (conn) => conn.client.readResource({ uri: target.resourceUri }, requestOptions)));
-            onRawResult?.(result);
-            const contents = (result.contents ?? []).map(c => ({
-                type: "text",
-                text: "text" in c ? c.text : ("blob" in c ? `[Binary data: ${c.mimeType ?? "unknown"}]` : JSON.stringify(c)),
-            }));
-            const guarded = await guardMcpOutput(contents.length > 0 ? contents : [{ type: "text", text: "(empty resource)" }], outputGuardOptions);
-            return { content: guarded.content, details: { ...detailsBase, ...guardedMcpDetails(guarded) } };
-        }
-        const result = await dispatch(() => withSessionRecovery({ ...recovery, retryOnTransportFailure: annotations?.readOnlyHint === true || annotations?.idempotentHint === true }, serverName, (conn) => abortable(conn.client.callTool({
-            name: target.originalName,
-            arguments: args ?? {},
-            _meta: uiSession?.requestMeta,
-        }, requestOptions), ownedSignal)));
-        uiSession?.sendToolResult(result);
-        if (result.isError) {
-            const content = transformMcpContent((result.content ?? []));
-            const guarded = await guardMcpOutput(content.length > 0 ? content : [{ type: "text", text: "(empty result)" }], { ...outputGuardOptions, prefix: "Error: ", suffix: schemaSuffix(), emptyTextFallback: "Tool execution failed", rawMcpResult: result });
-            return { content: guarded.content, details: { ...detailsBase, error: "tool_error", ...guardedMcpDetails(guarded) } };
-        }
-        onRawResult?.(result);
-        const content = resolveMcpResultContent(result);
-        const outputContent = content.length > 0 ? content : [{ type: "text", text: "(empty result)" }];
-        if (target.uiResourceUri) {
-            const uiSummary = summarizeUiSessionResult(uiSession);
-            const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, suffix: `\n\n${uiSummary.message}`, rawMcpResult: result });
-            return {
-                content: guarded.content,
-                details: {
-                    ...detailsBase,
-                    ...guardedMcpDetails(guarded),
-                    uiOpen: uiSummary.uiOpen,
-                    uiViewer: uiSummary.uiViewer,
-                    uiUrl: uiSummary.uiUrl,
-                },
-            };
-        }
-        const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, rawMcpResult: result });
-        return { content: guarded.content, details: { ...detailsBase, ...guardedMcpDetails(guarded) } };
+        const result = target.resourceUri
+            ? await dispatch(() => withSessionRecovery(recovery, serverName, conn => abortable(conn.client.readResource({ uri: target.resourceUri }, requestOptions), ownedSignal)))
+            : await dispatch(() => withSessionRecovery({ ...recovery, retryOnTransportFailure: annotations?.readOnlyHint === true || annotations?.idempotentHint === true }, serverName, conn => abortable(conn.client.callTool({ name: target.originalName, arguments: args ?? {}, _meta: uiSession?.requestMeta }, requestOptions), ownedSignal)));
+        if (!target.resourceUri)
+            uiSession?.sendToolResult(result);
+        const record = result;
+        const isError = record.isError === true;
+        const uiSummary = target.uiResourceUri ? summarizeUiSessionResult(uiSession) : undefined;
+        const details = {
+            ...detailsBase,
+            ...(isError ? { error: "tool_error" } : {}),
+            ...(uiSummary ? { uiOpen: uiSummary.uiOpen, uiViewer: uiSummary.uiViewer, uiUrl: uiSummary.uiUrl } : {}),
+        };
+        const retained = await retainMcpResult(result, outputGuardOptions, options.raw);
+        if (options.raw) {
+            const message = isError
+                ? (Array.isArray(record.content) ? record.content.filter(block => block.type === "text").map(block => block.text).join("\n") : "") || "Tool execution failed" : undefined;
+            return { content: [], details: { ...details, ...retained, ...(message ? { message } : {}) } };
+        }
+        const content = renderMcpResultContent(record, retained.payloadFiles);
+        const guarded = await guardMcpOutput(content.length ? content : [{ type: "text", text: target.resourceUri ? "(empty resource)" : "(empty result)" }], {
+            ...outputGuardOptions, retainedMcpResult: retained,
+            ...(isError ? { prefix: "Error: ", suffix: schemaSuffix(), emptyTextFallback: "Tool execution failed" }
+                : uiSummary ? { suffix: `\n\n${uiSummary.message}` } : {}),
+        });
+        return { content: guarded.content, details: { ...details, ...guardedMcpDetails(guarded) } };
     }
     catch (error) {
         // Direct/proxy host errors throw; scripts retain their failed-call envelope.
@@ -795,9 +755,11 @@ export async function runToolCall(state, serverName, target, args, options) {
                 ? "MCP call capture failed before dispatch; the tool did not run. Restore capture before continuing."
                 : "MCP outcome capture failed. Use the retained outcome to continue the original work; do not repeat a completed call or rerun the script.";
             uiSession?.sendToolCancelled(message);
+            const retained = "result" in captureFailure && captureFailure.result !== undefined
+                ? await retainMcpResult(captureFailure.result, { ...outputGuardOptions, enabled: true, detailsMaxBytes: 1 }) : {};
             return {
-                content: [{ type: "text", text: message }],
-                details: { ...detailsBase, error: isAbortError(error, callerSignal) ? "aborted" : "call_capture_failed", message, recovery: context },
+                content: [{ type: "text", text: message }, ...(retained.resultRef ? [{ type: "text", text: formatMcpResultReference(retained.resultRef) }] : [])],
+                details: { ...detailsBase, ...retained, error: isAbortError(error, callerSignal) ? "aborted" : "call_capture_failed", message, recovery: context },
             };
         }
         if (isToolTransportFailure(error)) {
@@ -848,388 +810,211 @@ export async function runToolCall(state, serverName, target, args, options) {
         state.manager.touch(serverName);
     }
 }
-export async function executeCall(state, toolName, args, serverOverride, getPiTools, signal, onRawResult, identity = {}, beforeDispatch) {
+/** Connect/auth once for calls and resource discovery. Recovery stays bounded by withSessionRecovery. */
+export async function prepareMcpConnection(state, serverName, signal) {
     const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
     throwIfAborted(ownedSignal);
-    let serverName = serverOverride;
-    let toolMeta;
     let autoAuthAttempted = false;
-    const prefixMode = state.config.settings?.toolPrefix ?? "server";
-    const disabledCallResult = (disabledServer, metadata) => {
-        if (!metadata) {
-            const message = `Server "${disabledServer}" is disabled. Run /mcp enable ${disabledServer} and /reload to enable it.`;
-            return {
-                content: [{ type: "text", text: message }],
-                details: { mode: "call", error: "server_disabled", server: disabledServer, requestedTool: toolName, message },
-            };
+    const recoverAuthConnection = async (_name, recoverySignal = ownedSignal, challenge) => {
+        throwIfAborted(recoverySignal);
+        const current = state.manager.getConnection(serverName);
+        if (current?.status === "connected" && current !== challenge?.connection)
+            return current;
+        if (!autoAuthAttempted) {
+            autoAuthAttempted = true;
+            const auth = await attemptAutoAuth(state, serverName, recoverySignal);
+            throwIfAborted(recoverySignal);
+            if (auth.status === "failed")
+                throw new SessionRecoveryAuthRequiredError(serverName, auth.message);
+            if (auth.status === "success" && current) {
+                clearFailure(state, serverName);
+                const definition = state.config.mcpServers[serverName];
+                if (!definition)
+                    return undefined;
+                state.ui?.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${serverName}...`));
+                await state.manager.reconnect(serverName, definition, current, recoverySignal);
+                if (await lazyConnect(state, serverName, recoverySignal)) {
+                    updateStatusBar(state);
+                    return state.manager.getConnection(serverName);
+                }
+            }
         }
-        const message = `Server "${disabledServer}" is disabled. Run /mcp enable ${disabledServer} and /reload to enable it.`;
-        const identity = metadata.resourceUri
-            ? { server: disabledServer, resourceUri: metadata.resourceUri }
-            : { server: disabledServer, tool: metadata.originalName };
-        return {
-            content: [{ type: "text", text: message }],
-            details: { mode: "call", error: "server_disabled", ...identity, message },
-        };
+        return challenge ? undefined : state.manager.getConnection(serverName);
     };
-    if (serverName && !state.config.mcpServers[serverName]) {
-        return {
-            content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({}) to see available servers.` }],
-            details: { mode: "call", error: "server_not_found", server: serverName, requestedTool: toolName },
-        };
-    }
-    if (serverName) {
-        toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
-        if (isServerDisabled(state.config.mcpServers[serverName])) {
-            return disabledCallResult(serverName, toolMeta);
+    const failure = (error, message) => ({
+        content: [{ type: "text", text: message }],
+        details: { mode: "call", error, server: serverName, message },
+    });
+    const definition = state.config.mcpServers[serverName];
+    if (!definition)
+        return { error: failure("server_not_found", `Server "${serverName}" not found.`) };
+    if (isServerDisabled(definition))
+        return { error: disabledResult("call", serverName) };
+    try {
+        // Connected metadata is read below, so it does not require another connection attempt.
+        let connection = state.manager.getConnection(serverName);
+        if (connection?.status !== "connected") {
+            await lazyConnect(state, serverName, ownedSignal);
+            connection = state.manager.getConnection(serverName);
         }
-    }
-    else {
-        let disabledMatch;
-        for (const [server, metadata] of state.toolMetadata.entries()) {
-            const found = findToolByName(metadata, toolName);
-            if (!found)
-                continue;
-            if (isServerDisabled(state.config.mcpServers[server])) {
-                disabledMatch ??= { serverName: server, toolMeta: found };
-                continue;
-            }
-            serverName = server;
-            toolMeta = found;
-            break;
+        else {
+            markKeepAliveAfterConnect(state, serverName);
         }
-        if (!toolMeta && disabledMatch)
-            return disabledCallResult(disabledMatch.serverName, disabledMatch.toolMeta);
-    }
-    if (serverName && !toolMeta && !state.toolMetadata.has(serverName)) {
-        const connected = await lazyConnect(state, serverName, ownedSignal);
-        if (connected) {
-            toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
+        if (connection?.status === "needs-auth")
+            connection = await recoverAuthConnection(serverName, ownedSignal);
+        if (connection?.status === "needs-auth")
+            throw new SessionRecoveryAuthRequiredError(serverName);
+        if (connection?.status !== "connected") {
+            const failedAgo = getFailureAgeSeconds(state, serverName);
+            return { error: failure(failedAgo === null ? "server_unavailable" : "server_backoff", `Server "${serverName}" not available${failedAgo === null ? "" : ` (last failed ${failedAgo}s ago)`}`) };
         }
-        else {
-            const needsAuthConnection = state.manager.getConnection(serverName);
-            if (needsAuthConnection?.status === "needs-auth") {
-                if (!autoAuthAttempted) {
-                    autoAuthAttempted = true;
-                    const autoAuth = await attemptAutoAuth(state, serverName, ownedSignal);
-                    if (autoAuth.status === "failed") {
-                        return {
-                            content: [{ type: "text", text: autoAuth.message }],
-                            details: { mode: "call", error: "auth_required", server: serverName, requestedTool: toolName, message: autoAuth.message },
-                        };
-                    }
-                    if (autoAuth.status === "success") {
-                        clearFailure(state, serverName);
-                        let connectedAfterAuth = false;
-                        try {
-                            const definition = state.config.mcpServers[serverName];
-                            if (definition) {
-                                await state.manager.reconnect(serverName, definition, needsAuthConnection, ownedSignal);
-                                connectedAfterAuth = true;
-                            }
-                        }
-                        catch (error) {
-                            if (isAbortError(error, ownedSignal))
-                                throwIfAborted(ownedSignal);
-                            recordFailure(state, serverName, error instanceof Error ? error.message : String(error));
-                            updateStatusBar(state);
-                        }
-                        if (connectedAfterAuth)
-                            connectedAfterAuth = await lazyConnect(state, serverName, ownedSignal);
-                        if (connectedAfterAuth) {
-                            toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
-                            if (!toolMeta) {
-                                const suggestions = rankSuggestions(state, toolName, 5, serverName);
-                                const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
-                                return {
-                                    content: [{ type: "text", text: `Tool "${toolName}" not found on "${serverName}" after reconnect.${suggestionText}` }],
-                                    details: { mode: "call", error: "tool_not_found_after_reconnect", server: serverName, requestedTool: toolName, suggestions },
-                                };
-                            }
-                        }
-                    }
-                }
-                if (!toolMeta && state.manager.getConnection(serverName)?.status === "needs-auth") {
-                    const message = getAuthRequiredMessage(state, serverName);
-                    return {
-                        content: [{ type: "text", text: message }],
-                        details: { mode: "call", error: "auth_required", server: serverName, requestedTool: toolName, message },
-                    };
-                }
-            }
-            if (!toolMeta) {
-                const failedAgo = getFailureAgeSeconds(state, serverName);
-                if (failedAgo !== null) {
-                    return {
-                        content: [{ type: "text", text: `Server "${serverName}" not available (last failed ${failedAgo}s ago)` }],
-                        details: { mode: "call", error: "server_backoff", server: serverName, requestedTool: toolName },
-                    };
-                }
-            }
+        // Use the live descriptor for visibility, filtering, approval, schema and UI hints.
+        if (connection.tools) {
+            const { metadata } = buildToolMetadata(connection.tools, connection.resources ?? [], definition, serverName, state.config.settings?.toolPrefix ?? "server");
+            state.toolMetadata.set(serverName, metadata);
         }
+        return { connection, recoverAuthConnection, autoAuthAttempted: () => autoAuthAttempted };
     }
-    let prefixMatchedServer;
-    if (!serverName && !toolMeta) {
-        const candidates = Object.keys(state.config.mcpServers)
-            .filter(name => !isServerDisabled(state.config.mcpServers[name]))
-            .map(name => ({
-            name,
-            prefix: getServerPrefix(name, resolveToolPrefix(state.config.mcpServers[name], prefixMode)),
-        }))
-            .filter(c => c.prefix && toolName.startsWith(c.prefix + "_"))
-            .sort((a, b) => b.prefix.length - a.prefix.length)
-            .slice(0, 1);
-        for (const { name: configuredServer } of candidates) {
-            const existingConnection = state.manager.getConnection(configuredServer);
-            const failedAgo = getFailureAgeSeconds(state, configuredServer);
-            if (failedAgo !== null && existingConnection?.status !== "needs-auth")
-                continue;
-            if (state.toolMetadata.has(configuredServer)) {
-                prefixMatchedServer ??= configuredServer;
-                continue;
-            }
-            let connected = await lazyConnect(state, configuredServer, ownedSignal);
-            const needsAuthConnection = state.manager.getConnection(configuredServer);
-            if (!connected && needsAuthConnection?.status === "needs-auth" && !autoAuthAttempted) {
-                autoAuthAttempted = true;
-                const autoAuth = await attemptAutoAuth(state, configuredServer, ownedSignal);
-                if (autoAuth.status === "failed") {
-                    return {
-                        content: [{ type: "text", text: autoAuth.message }],
-                        details: { mode: "call", error: "auth_required", server: configuredServer, requestedTool: toolName, message: autoAuth.message },
-                    };
-                }
-                if (autoAuth.status === "success") {
-                    clearFailure(state, configuredServer);
-                    try {
-                        const definition = state.config.mcpServers[configuredServer];
-                        if (definition) {
-                            await state.manager.reconnect(configuredServer, definition, needsAuthConnection, ownedSignal);
-                            connected = true;
-                        }
-                    }
-                    catch (error) {
-                        if (isAbortError(error, ownedSignal))
-                            throwIfAborted(ownedSignal);
-                        recordFailure(state, configuredServer, error instanceof Error ? error.message : String(error));
-                        updateStatusBar(state);
-                    }
-                    if (connected)
-                        connected = await lazyConnect(state, configuredServer, ownedSignal);
-                }
-            }
-            if (!connected)
-                continue;
-            if (!prefixMatchedServer)
-                prefixMatchedServer = configuredServer;
-            toolMeta = findToolByName(state.toolMetadata.get(configuredServer), toolName);
-            if (toolMeta) {
-                serverName = configuredServer;
-                break;
-            }
+    catch (error) {
+        if (isAbortError(error, ownedSignal))
+            throw error;
+        const message = error instanceof SessionRecoveryAuthRequiredError
+            ? error.authMessage ?? getAuthRequiredMessage(state, serverName)
+            : error instanceof Error ? error.message : String(error);
+        if (!(error instanceof SessionRecoveryAuthRequiredError)) {
+            recordFailure(state, serverName, message);
+            updateStatusBar(state);
         }
+        return { error: failure(error instanceof SessionRecoveryAuthRequiredError ? "auth_required" : "connect_failed", message) };
     }
-    if (!serverName || !toolMeta) {
-        const nativeTool = !serverOverride
-            ? getPiTools?.().find((tool) => tool.name === toolName && tool.name !== "mcp")
-            : undefined;
-        if (nativeTool) {
+}
+export async function executeCall(state, toolName, args, serverOverride, getPiTools, signal, identity = {}, beforeDispatch, options = {}) {
+    const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
+    throwIfAborted(ownedSignal);
+    if (typeof toolName !== "string" || !toolName.trim() || (serverOverride !== undefined && (typeof serverOverride !== "string" || !serverOverride)))
+        return {
+            content: [{ type: "text", text: "Specify a non-empty tool name and, when supplied, server." }],
+            details: { mode: "call", error: "invalid_arguments" },
+        };
+    if (args !== undefined && (args === null || typeof args !== "object" || Array.isArray(args)))
+        return {
+            content: [{ type: "text", text: "Tool arguments must be an object." }],
+            details: { mode: "call", error: "invalid_arguments", requestedTool: toolName },
+        };
+    let serverName = serverOverride;
+    const matches = (metadata = []) => {
+        if (options.resourceUri !== undefined)
+            return metadata.filter(tool => tool.resourceUri === options.resourceUri);
+        if (options.exactOriginalName)
+            return metadata.filter(tool => tool.originalName === toolName && !tool.resourceUri);
+        if (serverOverride) {
+            const originals = metadata.filter(tool => tool.originalName === toolName);
+            if (originals.length)
+                return originals;
+        }
+        const exact = metadata.filter(tool => tool.name === toolName);
+        if (exact.length)
+            return exact;
+        return metadata.filter(tool => tool.name.replace(/-/g, "_") === toolName.replace(/-/g, "_"));
+    };
+    const ambiguous = () => ({
+        content: [{ type: "text", text: `Tool "${toolName}" is ambiguous. Specify its exact server and tool name; no call was dispatched.` }],
+        details: { mode: "call", error: "ambiguous_tool", requestedTool: toolName, ...(serverName ? { server: serverName } : {}) },
+    });
+    if (!serverName) {
+        const candidates = [...state.toolMetadata].flatMap(([server, metadata]) => isServerDisabled(state.config.mcpServers[server]) ? [] : matches(metadata).map(tool => ({ server, tool })));
+        if (candidates.length > 1)
+            return ambiguous();
+        serverName = candidates[0]?.server;
+        if (!serverName) {
+            const disabled = [...state.toolMetadata].find(([server, metadata]) => isServerDisabled(state.config.mcpServers[server]) && matches(metadata).length > 0);
+            if (disabled)
+                return disabledResult("call", disabled[0]);
+            const prefixes = Object.entries(state.config.mcpServers)
+                .filter(([, definition]) => !isServerDisabled(definition))
+                .map(([server, definition]) => ({ server, prefix: getServerPrefix(server, resolveToolPrefix(definition, state.config.settings?.toolPrefix ?? "server")) }))
+                .filter(({ prefix }) => prefix && toolName.startsWith(`${prefix}_`))
+                .sort((a, b) => b.prefix.length - a.prefix.length);
+            if (prefixes.length > 1 && prefixes[0]?.prefix === prefixes[1]?.prefix)
+                return ambiguous();
+            serverName = prefixes[0]?.server;
+        }
+    }
+    const missing = () => {
+        const nativeTool = !serverOverride && getPiTools?.().find(tool => tool.name === toolName && tool.name !== "mcp");
+        if (nativeTool)
             return {
-                content: [{ type: "text", text: `"${toolName}" is a native Pi tool. Call ${toolName} directly instead of using mcp({ tool: "${toolName}" }).` }],
+                content: [{ type: "text", text: `"${toolName}" is a native Pi tool. Call ${toolName} directly instead of using mcp({ action: "call", tool: "${toolName}" }).` }],
                 details: { mode: "call", error: "native_tool", requestedTool: toolName },
             };
-        }
-        const hintServer = serverName ?? prefixMatchedServer;
-        const normalizedToolName = toolName.replace(/-/g, "_");
-        const localOriginalName = serverOverride && state.toolMetadata.get(serverOverride)
-            ?.some(tool => tool.originalName.replace(/-/g, "_") === normalizedToolName);
-        const suggestedOwner = serverOverride && !localOriginalName
-            ? [...state.toolMetadata].find(([candidateServer, metadata]) => candidateServer !== serverOverride
-                && !isServerDisabled(state.config.mcpServers[candidateServer])
-                && findToolByName(metadata, toolName))
-            : undefined;
-        const suggestedTool = suggestedOwner ? findToolByName(suggestedOwner[1], toolName) : undefined;
-        if (suggestedOwner && suggestedTool) {
-            const suggestedServer = suggestedOwner[0];
+        const normalizedName = toolName.replace(/-/g, "_");
+        const localOriginal = serverOverride && state.toolMetadata.get(serverOverride)?.some(tool => tool.originalName.replace(/-/g, "_") === normalizedName);
+        const owners = serverOverride && !localOriginal
+            ? [...state.toolMetadata].filter(([server, metadata]) => server !== serverOverride && !isServerDisabled(state.config.mcpServers[server]) && matches(metadata).length === 1)
+            : [];
+        const suggestedOwner = owners.length === 1 ? owners[0] : undefined;
+        if (suggestedOwner)
             return {
-                content: [{ type: "text", text: `Tool ${JSON.stringify(toolName)} is on server ${JSON.stringify(suggestedServer)}, not ${JSON.stringify(serverOverride)}. Retry the same call with server: ${JSON.stringify(suggestedServer)} or omit server.` }],
-                details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer, suggestedServer, suggestions: [suggestedTool.name] },
+                content: [{ type: "text", text: `Tool ${JSON.stringify(toolName)} is on server ${JSON.stringify(suggestedOwner[0])}, not ${JSON.stringify(serverOverride)}. Retry the same call with server: ${JSON.stringify(suggestedOwner[0])} or omit server.` }],
+                details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer: serverName, suggestedServer: suggestedOwner[0], suggestions: matches(suggestedOwner[1]).map(tool => tool.name) },
             };
-        }
-        const suggestions = rankSuggestions(state, toolName, 5, hintServer);
-        let hint;
-        if (suggestions.length > 0) {
-            hint = ` Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ describe: "${suggestions[0]}" }).`;
-        }
-        else if (hintServer) {
-            hint = ` Search with mcp({ search: ${JSON.stringify(toolName)}, server: ${JSON.stringify(hintServer)} }).`;
-        }
-        else {
-            hint = ` Use mcp({ search: "..." }) to search.`;
-        }
-        const suggestionOnHintServer = hintServer && suggestions.some(suggestion => state.toolMetadata.get(hintServer)?.some(tool => tool.name === suggestion));
-        if (hintServer && (suggestions.length === 0 || suggestionOnHintServer) && state.toolMetadata.has(hintServer) && state.manager.getConnection(hintServer)?.status !== "connected") {
-            hint += ` Refresh a stale catalog with mcp({ connect: ${JSON.stringify(hintServer)} }).`;
-        }
+        const suggestions = rankSuggestions(state, toolName, 5, serverName);
+        let hint = suggestions.length
+            ? ` Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ action: "describe", tool: ${JSON.stringify(suggestions[0])} }).`
+            : serverName ? ` Search with mcp({ action: "search", query: ${JSON.stringify(toolName)}, server: ${JSON.stringify(serverName)} }).` : ' Use mcp({ action: "search", query: "..." }) to search.';
+        if (serverName && state.toolMetadata.has(serverName) && state.manager.getConnection(serverName)?.status !== "connected")
+            hint += ` Refresh a stale catalog with mcp({ action: "connect", server: ${JSON.stringify(serverName)} }).`;
         return {
             content: [{ type: "text", text: `Tool "${toolName}" not found.${hint}` }],
-            details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer, suggestions },
+            details: { mode: "call", error: "tool_not_found", requestedTool: toolName, hintServer: serverName, suggestions },
         };
-    }
-    const callIdentity = toolMeta.resourceUri
-        ? { server: serverName, resourceUri: toolMeta.resourceUri }
-        : { server: serverName, tool: toolMeta.originalName };
-    let connection = state.manager.getConnection(serverName);
-    let refreshAfterAuth = false;
-    if (connection?.status === "needs-auth") {
-        if (!autoAuthAttempted) {
-            autoAuthAttempted = true;
-            const autoAuth = await attemptAutoAuth(state, serverName, ownedSignal);
-            if (autoAuth.status === "failed") {
-                return {
-                    content: [{ type: "text", text: autoAuth.message }],
-                    details: { mode: "call", error: "auth_required", ...callIdentity, message: autoAuth.message },
-                };
-            }
-            if (autoAuth.status === "success") {
-                clearFailure(state, serverName);
-                refreshAfterAuth = true;
-            }
-        }
-        if (connection?.status === "needs-auth" && !refreshAfterAuth) {
-            const message = getAuthRequiredMessage(state, serverName);
-            return {
-                content: [{ type: "text", text: message }],
-                details: { mode: "call", error: "auth_required", ...callIdentity, message },
-            };
-        }
-    }
-    if (!connection || connection.status !== "connected") {
-        const failedAgo = getFailureAgeSeconds(state, serverName);
-        if (failedAgo !== null) {
-            return {
-                content: [{ type: "text", text: `Server "${serverName}" not available (last failed ${failedAgo}s ago)` }],
-                details: { mode: "call", error: "server_backoff", ...callIdentity },
-            };
-        }
-        const definition = state.config.mcpServers[serverName];
-        if (!definition) {
-            return {
-                content: [{ type: "text", text: `Server "${serverName}" not connected` }],
-                details: { mode: "call", error: "server_not_connected", ...callIdentity },
-            };
-        }
-        try {
-            if (state.ui) {
-                state.ui.setStatus("mcp", formatMcpStatus(state.config, `connecting to ${serverName}...`));
-            }
-            connection = refreshAfterAuth && connection
-                ? await state.manager.reconnect(serverName, definition, connection, ownedSignal)
-                : await state.manager.connect(serverName, definition, ownedSignal);
-            if (connection.status === "needs-auth") {
-                if (!autoAuthAttempted) {
-                    autoAuthAttempted = true;
-                    const autoAuth = await attemptAutoAuth(state, serverName, ownedSignal);
-                    if (autoAuth.status === "failed") {
-                        return {
-                            content: [{ type: "text", text: autoAuth.message }],
-                            details: { mode: "call", error: "auth_required", ...callIdentity, message: autoAuth.message },
-                        };
-                    }
-                    if (autoAuth.status === "success") {
-                        connection = await state.manager.reconnect(serverName, definition, connection, ownedSignal);
-                    }
-                }
-                if (connection.status === "needs-auth") {
-                    const message = getAuthRequiredMessage(state, serverName);
-                    return {
-                        content: [{ type: "text", text: message }],
-                        details: { mode: "call", error: "auth_required", ...callIdentity, message },
-                    };
-                }
-            }
-            clearFailure(state, serverName);
-            updateServerMetadata(state, serverName);
-            updateMetadataCache(state, serverName);
-            notifyToolMetadataUpdated(state, serverName, "proxy-call-reconnect");
-            markKeepAliveAfterConnect(state, serverName);
-            updateStatusBar(state);
-            toolMeta = findToolByName(state.toolMetadata.get(serverName), toolName);
-            if (!toolMeta) {
-                const suggestions = rankSuggestions(state, toolName, 5, serverName);
-                const hint = suggestions.length > 0
-                    ? ` Did you mean: ${suggestions.join(", ")}. Inspect with mcp({ describe: "${suggestions[0]}" }).`
-                    : ` Search with mcp({ search: ${JSON.stringify(toolName)}, server: ${JSON.stringify(serverName)} }).`;
-                return {
-                    content: [{ type: "text", text: `Tool "${toolName}" not found on "${serverName}" after reconnect.${hint}` }],
-                    details: { mode: "call", error: "tool_not_found_after_reconnect", server: serverName, requestedTool: toolName, suggestions },
-                };
-            }
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            if (!isAbortError(error, ownedSignal))
-                recordFailure(state, serverName, message);
-            updateStatusBar(state);
-            return {
-                content: [{ type: "text", text: `Failed to connect to "${serverName}": ${message}` }],
-                details: { mode: "call", error: isAbortError(error, ownedSignal) ? "aborted" : "connect_failed", ...callIdentity, message },
-            };
-        }
-    }
-    if (isServerDisabled(state.config.mcpServers[serverName])) {
-        return disabledCallResult(serverName, toolMeta);
-    }
+    };
+    if (!serverName)
+        return missing();
+    const definition = state.config.mcpServers[serverName];
+    if (!definition)
+        return { content: [{ type: "text", text: `Server "${serverName}" not found. Use mcp({ action: "status" }) to see available servers.` }], details: { mode: "call", error: "server_not_found", server: serverName, requestedTool: toolName } };
+    if (isServerDisabled(definition))
+        return disabledResult("call", serverName);
+    const cached = state.toolMetadata.get(serverName);
+    if (matches(cached).length > 1)
+        return ambiguous();
+    // Misspellings in a known catalog do not cause connection churn or guessed execution.
+    if (cached && !matches(cached).length && !options.exactOriginalName && options.resourceUri === undefined)
+        return missing();
+    const prepared = await prepareMcpConnection(state, serverName, ownedSignal);
+    if (prepared.error) {
+        const cachedTarget = matches(cached)[0];
+        return { ...prepared.error, details: { ...prepared.error.details, ...(cachedTarget
+                    ? cachedTarget.resourceUri ? { resourceUri: cachedTarget.resourceUri } : { tool: cachedTarget.originalName }
+                    : { requestedTool: toolName }) } };
+    }
+    const targets = matches(state.toolMetadata.get(serverName));
+    if (targets.length > 1)
+        return ambiguous();
+    const toolMeta = targets[0];
+    if (!toolMeta)
+        return missing();
+    if (isServerDisabled(state.config.mcpServers[serverName]))
+        return disabledResult("call", serverName);
     const approval = await ensureToolCallApproved(state, serverName, toolMeta, args, ownedSignal);
-    if (approval.ok === false) {
+    if (!approval.ok) {
         const denied = approval.reason === "denied";
-        const message = denied
-            ? `The user declined approval to run MCP tool "${toolMeta.originalName}" on server "${serverName}".`
-            : `MCP tool "${toolMeta.originalName}" on server "${serverName}" is approval-gated and requires an interactive session.`;
         return {
-            content: [{ type: "text", text: message }],
-            details: {
-                mode: "call",
-                error: denied ? "approval_denied" : "approval_required",
-                server: serverName,
-                tool: toolMeta.originalName,
-            },
+            content: [{ type: "text", text: denied
+                        ? `The user declined approval to run MCP tool "${toolMeta.originalName}" on server "${serverName}".`
+                        : `MCP tool "${toolMeta.originalName}" on server "${serverName}" is approval-gated and requires an interactive session.` }],
+            details: { mode: "call", error: denied ? "approval_denied" : "approval_required", server: serverName, tool: toolMeta.originalName },
         };
     }
-    const recoverAuthConnection = async (_serverName, recoverySignal = ownedSignal, challenge) => {
-        throwIfAborted(recoverySignal);
-        const current = state.manager.getConnection(serverName);
-        if (current?.status === "connected" && current !== challenge?.connection)
-            return current;
-        if (!autoAuthAttempted) {
-            autoAuthAttempted = true;
-            const autoAuth = await attemptAutoAuth(state, serverName, recoverySignal);
-            throwIfAborted(recoverySignal);
-            if (autoAuth.status === "failed") {
-                throw new SessionRecoveryAuthRequiredError(serverName, autoAuth.message);
-            }
-            if (autoAuth.status === "success") {
-                const definition = state.config.mcpServers[serverName];
-                if (!definition)
-                    return undefined;
-                if (!current)
-                    return undefined;
-                clearFailure(state, serverName);
-                connection = await state.manager.reconnect(serverName, definition, current, recoverySignal);
-                return connection;
-            }
-        }
-        return challenge ? undefined : state.manager.getConnection(serverName);
-    };
     return runToolCall(state, serverName, toolMeta, args, {
         ...identity,
         ...(beforeDispatch ? { beforeDispatch } : {}),
-        detailsBase: { mode: "call", ...callIdentity },
-        ownedSignal,
-        signal,
-        recoverAuthConnection,
+        ...(options.raw !== undefined ? { raw: options.raw } : {}),
+        detailsBase: { mode: "call", server: serverName, ...(toolMeta.resourceUri ? { resourceUri: toolMeta.resourceUri } : { tool: toolMeta.originalName }) },
+        ownedSignal, signal,
+        recoverAuthConnection: prepared.recoverAuthConnection,
         authRequiredMessage: () => getAuthRequiredMessage(state, serverName),
-        autoAuthAttempted: () => autoAuthAttempted,
-        ...(onRawResult ? { onRawResult } : {}),
+        autoAuthAttempted: prepared.autoAuthAttempted,
     });
 }