@fitchmultz/pi-mcp-adapter 5.0.0 → 7.0.0

package/dist/commands.js

@@ -22,7 +22,8 @@ export async function showStatus(state, ctx) {
         }
         const connection = state.manager.getConnection(name);
         const metadata = state.toolMetadata.get(name);
-        const toolCount = metadata?.length ?? 0;
+        const toolCount = metadata?.filter(tool => tool.resourceUri === undefined).length ?? 0;
+        const resourceCount = metadata?.filter(tool => tool.resourceUri !== undefined).length ?? 0;
         const failedAgo = getFailureAgeSeconds(state, name);
         let status = "not connected";
         let statusIcon = "○";
@@ -44,7 +45,9 @@ export async function showStatus(state, ctx) {
         else if (metadata !== undefined) {
             status = "cached";
         }
-        const toolSuffix = failed ? "" : ` (${toolCount} tools${status === "cached" ? ", cached" : ""})`;
+        const toolSuffix = failed ? "" : metadata === undefined
+            ? " (undiscovered)"
+            : ` (${toolCount} tool${toolCount === 1 ? "" : "s"}, ${resourceCount} resource${resourceCount === 1 ? "" : "s"}${status === "cached" ? ", cached" : ""})`;
         lines.push(`${statusIcon} ${name}: ${status}${toolSuffix}`);
     }
     if (Object.keys(state.config.mcpServers).length === 0) {
@@ -96,17 +99,17 @@ export async function showTools(state, ctx) {
         return;
     const allTools = [...state.toolMetadata.entries()]
         .filter(([serverName]) => !isServerDisabled(state.config.mcpServers[serverName]))
-        .flatMap(([, metadata]) => metadata.map(m => m.name));
+        .flatMap(([, metadata]) => metadata.filter(tool => tool.resourceUri === undefined).map(tool => tool.name));
     if (allTools.length === 0) {
-        ctx.ui.notify("No MCP tools available", "info");
+        ctx.ui.notify("No MCP tools discovered. Use mcp_search to discover tools.", "info");
         return;
     }
     const lines = [
-        "MCP Tools:",
+        "Discovered MCP Tools:",
         "",
         ...allTools.map(t => `  ${t}`),
         "",
-        `Total: ${allTools.length} tools`,
+        `Total: ${allTools.length} tool${allTools.length === 1 ? "" : "s"}`,
     ];
     ctx.ui.notify(lines.join("\n"), "info");
 }

package/dist/config.js

@@ -1,7 +1,9 @@
 // config.ts - Config loading with import support
-import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync, renameSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync, renameSync, statSync, chmodSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import { parse as parseToml } from "smol-toml";
 import stripJsonComments from "strip-json-comments";
 import { getAdapterPath } from "./agent-dir.js";
@@ -367,6 +369,14 @@ function mergeServerMaps(base, next) {
                 delete baseEntry.oauth;
             }
         }
+        // Stdio env belongs to the program that received it, not just the server name.
+        if (existing?.command && ((definition.command !== undefined && definition.command !== existing.command)
+            || (definition.args !== undefined && !isDeepStrictEqual(definition.args, existing.args ?? []))
+            || (definition.cwd !== undefined && definition.cwd !== existing.cwd))) {
+            if (baseEntry === existing)
+                baseEntry = { ...existing };
+            delete baseEntry.env;
+        }
         merged[name] = { ...baseEntry, ...definition };
     }
     return merged;
@@ -533,8 +543,10 @@ function mergeOpenCodeConfigs(base, next) {
                         delete safeBase.cwd;
                     }
                 }
+                if (Object.hasOwn(override, "cwd") && override.cwd !== safeBase.cwd)
+                    delete safeBase.environment;
                 const mergedEntry = { ...safeBase, ...override };
-                for (const field of ["environment", "headers", "oauth"]) {
+                for (const field of ["headers", "oauth"]) {
                     const baseField = safeBase[field];
                     const nextField = override[field];
                     if (baseField && typeof baseField === "object" && !Array.isArray(baseField)
@@ -714,24 +726,37 @@ function buildConfigWritePreview(filePath, nextRaw) {
 function readRawConfigObject(filePath) {
     if (!existsSync(filePath))
         return {};
+    let raw;
     try {
-        const raw = parseJsonConfig(readFileSync(filePath, "utf-8"));
-        return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+        raw = parseJsonConfig(readFileSync(filePath, "utf-8"));
     }
-    catch {
-        return {};
+    catch (error) {
+        throw new Error(`Cannot read MCP config at ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`Invalid MCP config at ${filePath}: expected an object`);
     }
+    return raw;
 }
 function writeRawConfigObject(filePath, raw) {
     mkdirSync(dirname(filePath), { recursive: true });
-    const tmpPath = `${filePath}.${process.pid}.tmp`;
-    writeFileSync(tmpPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
+    const existingMode = existsSync(filePath) ? statSync(filePath).mode & 0o7777 : undefined;
+    const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(raw, null, 2)}\n`, {
+        encoding: "utf-8",
+        mode: existingMode ?? 0o666,
+        flag: "wx",
+    });
+    if (existingMode !== undefined)
+        chmodSync(tmpPath, existingMode);
     renameSync(tmpPath, filePath);
 }
-function getServersObject(raw) {
-    const existing = raw.mcpServers ?? raw["mcp-servers"] ?? {};
+function getServersObject(raw, filePath) {
+    const existing = raw.mcpServers !== undefined ? raw.mcpServers
+        : raw["mcp-servers"] !== undefined ? raw["mcp-servers"]
+            : {};
     if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
-        return {};
+        throw new Error(`Invalid MCP config at ${filePath}: mcpServers must be an object`);
     }
     return existing;
 }
@@ -886,7 +911,7 @@ export function previewCompatibilityImports(importKinds, overridePath) {
     const currentImports = Array.isArray(raw.imports) ? raw.imports.filter((value) => typeof value === "string") : [];
     const merged = [...new Set([...currentImports, ...importKinds])];
     const nextRaw = { ...raw, imports: merged };
-    setServersObject(nextRaw, getServersObject(nextRaw));
+    setServersObject(nextRaw, getServersObject(nextRaw, targetPath));
     return buildConfigWritePreview(targetPath, nextRaw);
 }
 export function ensureCompatibilityImports(importKinds, overridePath) {
@@ -899,7 +924,7 @@ export function ensureCompatibilityImports(importKinds, overridePath) {
         return { path: targetPath, added: [] };
     }
     raw.imports = merged;
-    const servers = getServersObject(raw);
+    const servers = getServersObject(raw, targetPath);
     setServersObject(raw, servers);
     writeRawConfigObject(targetPath, raw);
     return { path: targetPath, added };
@@ -923,14 +948,14 @@ export function writeStarterProjectConfig(cwd = process.cwd()) {
 export function previewSharedServerEntry(filePath, serverName, entry) {
     const raw = readRawConfigObject(filePath);
     const nextRaw = { ...raw };
-    const servers = getServersObject(nextRaw);
+    const servers = getServersObject(nextRaw, filePath);
     servers[serverName] = entry;
     setServersObject(nextRaw, servers);
     return buildConfigWritePreview(filePath, nextRaw);
 }
 export function writeSharedServerEntry(filePath, serverName, entry) {
     const raw = readRawConfigObject(filePath);
-    const servers = getServersObject(raw);
+    const servers = getServersObject(raw, filePath);
     servers[serverName] = entry;
     setServersObject(raw, servers);
     writeRawConfigObject(filePath, raw);
@@ -991,7 +1016,7 @@ export function writeDirectToolsConfig(changes, provenance) {
     }
     for (const [filePath, entries] of byPath) {
         const raw = readRawConfigObject(filePath);
-        const servers = getServersObject(raw);
+        const servers = getServersObject(raw, filePath);
         for (const { name, value } of entries) {
             // Keep inherited connection details in their source file.
             servers[name] = { ...servers[name], directTools: value };

package/dist/direct-tools.d.ts

@@ -1,10 +1,8 @@
 import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { McpExtensionState } from "./state.ts";
-import type { DirectToolSpec, McpAdapterOptions, McpConfig, ToolPrefix } from "./types.ts";
-import type { MetadataCache } from "./metadata-cache.ts";
+import type { DirectToolSpec, McpAdapterOptions, McpConfig } from "./types.ts";
 export { getMissingConfiguredDirectToolServers } from "./metadata-cache.ts";
-export declare const DIRECT_TOOLS_ADVISORY_THRESHOLD = 75;
-export declare function resolveDirectTools(config: McpConfig, cache: MetadataCache | null, prefix: ToolPrefix, envOverride?: string[]): DirectToolSpec[];
+export declare function directToolSelection(config: McpConfig, serverName: string, envOverride?: string[]): true | string[] | false;
 export declare function buildProxyDescription(config: McpConfig): string;
 type DirectToolExecute = (toolCallId: string, params: Record<string, unknown>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined, ctx: ExtensionContext) => Promise<AgentToolResult<Record<string, unknown>>>;
 export declare function createDirectToolExecutor(getState: () => McpExtensionState | null, getInitPromise: () => Promise<McpExtensionState> | null, spec: DirectToolSpec, beforeExecute?: McpAdapterOptions["beforeExecute"]): DirectToolExecute;

package/dist/direct-tools.js

@@ -1,204 +1,25 @@
-import { lazyConnect, getFailureAgeSeconds, clearFailure, recordFailure, updateStatusBar } from "./init.js";
 import { abortable, throwIfAborted } from "./abort.js";
-import { isServerCacheValid, parseDirectToolSelectors } from "./metadata-cache.js";
+import { parseDirectToolSelectors } from "./metadata-cache.js";
 export { getMissingConfiguredDirectToolServers } from "./metadata-cache.js";
-import { runToolCall } from "./proxy-modes.js";
-import { formatToolName, isServerDisabled, isNonInteractiveOAuth, isToolAllowed, resolveToolPrefix } from "./types.js";
-import { resourceNameToToolName } from "./resource-tools.js";
-import { authenticate, supportsOAuth } from "./mcp-auth-flow.js";
-import { formatAuthRequiredMessage, resolveServerUrl } from "./utils.js";
-import { SessionRecoveryAuthRequiredError } from "./session-recovery.js";
-import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
-import { ensureToolCallApproved } from "./tool-approval.js";
-const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
-export const DIRECT_TOOLS_ADVISORY_THRESHOLD = 75;
-const advisedDirectToolSets = new Set();
-function getDirectAuthRequiredMessage(state, serverName, defaultMessage = `MCP server "${serverName}" requires OAuth authentication. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`) {
-    const oauth = state.config.mcpServers[serverName]?.oauth;
-    if (oauth && oauth.crossAppAccess)
-        defaultMessage = `MCP server "${serverName}" requires enterprise authorization. Check oauth.crossAppAccess IdP configuration and ID-token source, then retry.`;
-    return formatAuthRequiredMessage(state.config, serverName, defaultMessage);
-}
-function getDirectAuthFailedMessage(state, serverName, message) {
-    const customGuidance = state.config.settings?.authRequiredMessage;
-    const oauth = state.config.mcpServers[serverName]?.oauth;
-    if (customGuidance || (oauth && oauth.crossAppAccess)) {
-        return `OAuth authentication failed for "${serverName}": ${message}. ${getDirectAuthRequiredMessage(state, serverName)}`;
-    }
-    return `OAuth authentication failed for "${serverName}": ${message}. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`;
-}
-async function attemptDirectAutoAuth(state, serverName, signal) {
-    if (state.config.settings?.autoAuth !== true) {
-        return { status: "skipped" };
-    }
-    const definition = state.config.mcpServers[serverName];
-    if (!definition || isServerDisabled(definition) || !supportsOAuth(definition)) {
-        return { status: "skipped" };
-    }
-    let serverUrl;
-    try {
-        serverUrl = resolveServerUrl(definition);
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { status: "failed", message: getDirectAuthFailedMessage(state, serverName, message) };
-    }
-    if (!serverUrl) {
-        return { status: "skipped" };
-    }
-    if (!state.ui && !isNonInteractiveOAuth(definition.oauth)) {
-        return {
-            status: "failed",
-            message: getDirectAuthRequiredMessage(state, serverName, `MCP server "${serverName}" requires OAuth authentication. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`),
-        };
-    }
-    try {
-        if (state.authStorageOptions) {
-            await authenticate(serverName, serverUrl, definition, signal
-                ? { authStorageOptions: state.authStorageOptions, signal, runtime: state.oauthRuntime }
-                : { authStorageOptions: state.authStorageOptions, runtime: state.oauthRuntime });
-        }
-        else {
-            await authenticate(serverName, serverUrl, definition, {
-                ...(signal ? { signal } : {}),
-                runtime: state.oauthRuntime,
-            });
-        }
-        return { status: "success" };
-    }
-    catch (error) {
-        if (isAbortError(error, signal))
-            throw error;
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            status: "failed",
-            message: getDirectAuthFailedMessage(state, serverName, message),
-        };
-    }
-}
-export function resolveDirectTools(config, cache, prefix, envOverride) {
-    const specs = [];
-    if (!cache)
-        return specs;
-    const seenNames = new Set();
-    const envSelection = envOverride ? parseDirectToolSelectors(envOverride) : null;
-    const globalDirect = config.settings?.directTools;
-    for (const [serverName, definition] of Object.entries(config.mcpServers)) {
-        if (isServerDisabled(definition))
-            continue;
-        const serverCache = cache.servers[serverName];
-        if (!serverCache || !isServerCacheValid(serverCache, definition))
-            continue;
-        let toolFilter = false;
-        if (envSelection) {
-            if (envSelection.servers.has(serverName)) {
-                toolFilter = true;
-            }
-            else if (envSelection.tools.has(serverName)) {
-                toolFilter = [...envSelection.tools.get(serverName)];
-            }
-        }
-        else {
-            if (definition.directTools !== undefined) {
-                toolFilter = definition.directTools;
-            }
-            else if (globalDirect) {
-                toolFilter = globalDirect;
-            }
-        }
-        if (!toolFilter)
-            continue;
-        const effectivePrefix = resolveToolPrefix(definition, prefix);
-        for (const tool of serverCache.tools ?? []) {
-            if (toolFilter !== true && !toolFilter.includes(tool.name))
-                continue;
-            if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools))
-                continue;
-            const prefixedName = formatToolName(tool.name, serverName, effectivePrefix);
-            if (BUILTIN_NAMES.has(prefixedName)) {
-                console.warn(`MCP: skipping direct tool "${prefixedName}" (collides with builtin)`);
-                continue;
-            }
-            if (seenNames.has(prefixedName)) {
-                console.warn(`MCP: skipping duplicate direct tool "${prefixedName}" from "${serverName}"`);
-                continue;
-            }
-            seenNames.add(prefixedName);
-            specs.push({
-                serverName,
-                originalName: tool.name,
-                prefixedName,
-                description: tool.description ?? "",
-                ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
-                ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
-                ...(tool.uiResourceUri !== undefined ? { uiResourceUri: tool.uiResourceUri } : {}),
-                ...(tool.uiStreamMode !== undefined ? { uiStreamMode: tool.uiStreamMode } : {}),
-            });
-        }
-        if (definition.exposeResources !== false) {
-            for (const resource of serverCache.resources ?? []) {
-                const baseName = `read_${resourceNameToToolName(resource.name)}`;
-                if (toolFilter !== true && !toolFilter.includes(baseName))
-                    continue;
-                if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools))
-                    continue;
-                const prefixedName = formatToolName(baseName, serverName, effectivePrefix);
-                if (BUILTIN_NAMES.has(prefixedName)) {
-                    console.warn(`MCP: skipping direct resource tool "${prefixedName}" (collides with builtin)`);
-                    continue;
-                }
-                if (seenNames.has(prefixedName)) {
-                    console.warn(`MCP: skipping duplicate direct resource tool "${prefixedName}" from "${serverName}"`);
-                    continue;
-                }
-                seenNames.add(prefixedName);
-                specs.push({
-                    serverName,
-                    originalName: baseName,
-                    prefixedName,
-                    description: resource.description ?? `Read resource: ${resource.uri}`,
-                    resourceUri: resource.uri,
-                });
-            }
-        }
-    }
-    const advisoryKey = specs.map(spec => spec.prefixedName).sort().join("\0");
-    if (specs.length >= DIRECT_TOOLS_ADVISORY_THRESHOLD && !advisedDirectToolSets.has(advisoryKey)) {
-        advisedDirectToolSets.add(advisoryKey);
-        console.warn(`MCP: ${specs.length} direct tools resolved. Each direct tool adds prompt context; README guidance recommends targeted sets of 5-20 tools and using the proxy or an explicit string[] when 75+ direct tools would be registered.`);
-    }
-    return specs;
+import { executeCall } from "./proxy-modes.js";
+import { isServerDisabled } from "./types.js";
+export function directToolSelection(config, serverName, envOverride) {
+    if (envOverride) {
+        const selection = parseDirectToolSelectors(envOverride);
+        if (selection.servers.has(serverName))
+            return true;
+        return selection.tools.has(serverName) ? [...selection.tools.get(serverName)] : false;
+    }
+    return config.mcpServers[serverName]?.directTools ?? config.settings?.directTools ?? false;
 }
 export function buildProxyDescription(config) {
-    let desc = `MCP gateway — server status, tool search/describe, auth, and single MCP tool calls. When one request needs several MCP calls with logic between them, use mcp_script. Non-MCP Pi tools should be called directly, not through mcp.\n`;
-    // Catalog counts and instruction previews change on connect and break prompt caching.
-    // Keep this directory config-only; discovery and instructions belong in tool results.
-    const enabledServers = Object.entries(config.mcpServers)
-        .filter(([, definition]) => !isServerDisabled(definition))
-        .map(([serverName]) => serverName)
-        .sort();
-    if (enabledServers.length > 0) {
-        desc += `\nConfigured servers (call mcp({}) for live status): ${enabledServers.join(", ")}\n`;
-    }
-    const disabledServers = Object.entries(config.mcpServers)
-        .filter(([, definition]) => isServerDisabled(definition))
-        .map(([serverName]) => serverName);
-    if (disabledServers.length > 0) {
-        desc += `\nDisabled servers (enable with /mcp enable <server> and /reload): ${disabledServers.join(", ")}\n`;
-    }
-    desc += `\nUsage:\n`;
-    desc += `  mcp({ })                              → Show server status\n`;
-    desc += `  mcp({ server: "name", limit: 12 })    → Browse a server's tools (use offset for more)\n`;
-    desc += `  mcp({ search: "query" })              → Search MCP tools by name/description\n`;
-    desc += `  mcp({ describe: "tool_name" })        → Show tool details and parameters\n`;
-    desc += `  mcp({ instructions: "name" })         → Show full server usage instructions\n`;
-    desc += `  mcp({ connect: "server-name" })       → Connect to a server and refresh metadata\n`;
-    desc += `  mcp({ tool: "name", args: { key: "value" } })         → Call a tool (object args; JSON string also accepted)\n`;
-    desc += `  mcp({ action: "ui-messages" })        → Retrieve accumulated messages from completed UI sessions\n`;
-    desc += `  mcp({ action: "auth-start", server: "name" })      → Start manual OAuth and get a browser URL\n`;
-    desc += `  mcp({ action: "auth-complete", server: "name", args: { redirectUrl: "..." } }) → Complete manual OAuth\n`;
-    desc += `\nMode: action > tool (call) > connect > describe > instructions > search > server (list) > nothing (status)`;
-    return desc;
+    const servers = Object.entries(config.mcpServers).filter(([, definition]) => !isServerDisabled(definition)).map(([name]) => name).sort();
+    return [
+        "MCP gateway. Use mcp_search to discover and load typed tools; mcp_script for multi-call composition. Native Pi tools are called directly.",
+        `Configured servers: ${servers.join(", ") || "none"}. Catalog discovery is lazy.`,
+        "Actions: status; list/search/describe; call (tool,args,server?); connect (server); instructions (server); resources (server); read-resource (server,uri); read-result (ref,path?,fields?,offset?,limit?); auth-start/auth-complete (server,args?); ui-messages.",
+        "Use call when a discovered direct tool is unavailable in this host. read-result reads a retained response without repeating the remote operation.",
+    ].join("\n");
 }
 export function createDirectToolExecutor(getState, getInitPromise, spec, beforeExecute) {
     return async function execute(toolCallId, params, signal, _onUpdate, ctx) {
@@ -224,127 +45,8 @@ export function createDirectToolExecutor(getState, getInitPromise, spec, beforeE
                 details: { error: "not_initialized" },
             };
         }
-        const definition = state.config.mcpServers[spec.serverName];
-        if (isServerDisabled(definition)) {
-            const message = `MCP server "${spec.serverName}" is disabled. Run /mcp enable ${spec.serverName} and /reload to enable it.`;
-            return {
-                content: [{ type: "text", text: message }],
-                details: { error: "server_disabled", server: spec.serverName, message },
-            };
-        }
-        const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
-        throwIfAborted(ownedSignal);
-        let connected = await lazyConnect(state, spec.serverName, ownedSignal);
-        let autoAuthAttempted = false;
-        const needsAuthConnection = state.manager.getConnection(spec.serverName);
-        if (!connected && needsAuthConnection?.status === "needs-auth") {
-            autoAuthAttempted = true;
-            const autoAuth = await attemptDirectAutoAuth(state, spec.serverName, ownedSignal);
-            if (autoAuth.status === "failed") {
-                return {
-                    content: [{ type: "text", text: autoAuth.message }],
-                    details: { error: "auth_required", server: spec.serverName, message: autoAuth.message },
-                };
-            }
-            if (autoAuth.status === "success") {
-                clearFailure(state, spec.serverName);
-                try {
-                    const liveDefinition = state.config.mcpServers[spec.serverName];
-                    if (liveDefinition) {
-                        await state.manager.reconnect(spec.serverName, liveDefinition, needsAuthConnection, ownedSignal);
-                        connected = true;
-                    }
-                }
-                catch (error) {
-                    if (isAbortError(error, ownedSignal))
-                        throwIfAborted(ownedSignal);
-                    recordFailure(state, spec.serverName, error instanceof Error ? error.message : String(error));
-                    updateStatusBar(state);
-                }
-                if (connected)
-                    connected = await lazyConnect(state, spec.serverName, ownedSignal);
-            }
-        }
-        if (!connected) {
-            const authConnection = state.manager.getConnection(spec.serverName);
-            if (authConnection?.status === "needs-auth") {
-                const message = getDirectAuthRequiredMessage(state, spec.serverName);
-                return {
-                    content: [{ type: "text", text: message }],
-                    details: { error: "auth_required", server: spec.serverName, message, autoAuthAttempted },
-                };
-            }
-            const failedAgo = getFailureAgeSeconds(state, spec.serverName);
-            return {
-                content: [{ type: "text", text: `MCP server "${spec.serverName}" not available${failedAgo !== null ? ` (failed ${failedAgo}s ago)` : ""}` }],
-                details: { error: "server_unavailable", server: spec.serverName },
-            };
-        }
-        const connection = state.manager.getConnection(spec.serverName);
-        if (!connection || connection.status !== "connected") {
-            return {
-                content: [{ type: "text", text: `MCP server "${spec.serverName}" not connected` }],
-                details: { error: "not_connected", server: spec.serverName },
-            };
-        }
-        const approval = await ensureToolCallApproved(state, spec.serverName, {
-            name: spec.prefixedName,
-            originalName: spec.originalName,
-            description: spec.description,
-            ...(spec.inputSchema !== undefined ? { inputSchema: spec.inputSchema } : {}),
-            ...(spec.resourceUri !== undefined ? { resourceUri: spec.resourceUri } : {}),
-            ...(spec.uiResourceUri !== undefined ? { uiResourceUri: spec.uiResourceUri } : {}),
-            ...(spec.uiStreamMode !== undefined ? { uiStreamMode: spec.uiStreamMode } : {}),
-        }, params, ownedSignal);
-        if (approval.ok === false) {
-            const denied = approval.reason === "denied";
-            const message = denied
-                ? `The user declined approval to run MCP tool "${spec.originalName}" on server "${spec.serverName}".`
-                : `MCP tool "${spec.originalName}" on server "${spec.serverName}" is approval-gated and requires an interactive session.`;
-            return {
-                content: [{ type: "text", text: message }],
-                details: {
-                    error: denied ? "approval_denied" : "approval_required",
-                    server: spec.serverName,
-                    tool: spec.originalName,
-                },
-            };
-        }
-        const recoverAuthConnection = async (_serverName, recoverySignal = ownedSignal, challenge) => {
-            throwIfAborted(recoverySignal);
-            const current = state.manager.getConnection(spec.serverName);
-            if (current?.status === "connected" && current !== challenge?.connection)
-                return current;
-            if (!autoAuthAttempted) {
-                autoAuthAttempted = true;
-                const autoAuth = await attemptDirectAutoAuth(state, spec.serverName, recoverySignal);
-                throwIfAborted(recoverySignal);
-                if (autoAuth.status === "failed") {
-                    throw new SessionRecoveryAuthRequiredError(spec.serverName, autoAuth.message);
-                }
-                if (autoAuth.status === "success") {
-                    const liveDefinition = state.config.mcpServers[spec.serverName];
-                    if (!current || !liveDefinition)
-                        return undefined;
-                    await state.manager.reconnect(spec.serverName, liveDefinition, current, recoverySignal);
-                    clearFailure(state, spec.serverName);
-                    const reconnected = await lazyConnect(state, spec.serverName, recoverySignal);
-                    return reconnected ? state.manager.getConnection(spec.serverName) : undefined;
-                }
-            }
-            return challenge ? undefined : state.manager.getConnection(spec.serverName);
-        };
-        return runToolCall(state, spec.serverName, spec, params, {
-            toolCallId,
-            ...(beforeExecute ? { beforeDispatch: (callSignal, operation) => beforeExecute(toolCallId, { ...ctx, signal: callSignal }, operation) } : {}),
-            detailsBase: spec.resourceUri
-                ? { server: spec.serverName, resourceUri: spec.resourceUri }
-                : { server: spec.serverName, tool: spec.originalName },
-            ownedSignal,
-            signal,
-            recoverAuthConnection,
-            authRequiredMessage: () => getDirectAuthRequiredMessage(state, spec.serverName),
-            autoAuthAttempted: () => autoAuthAttempted,
-        });
+        const result = await executeCall(state, spec.originalName, params, spec.serverName, undefined, signal, { toolCallId }, beforeExecute ? (callSignal, operation) => beforeExecute(toolCallId, { ...ctx, signal: callSignal }, operation) : undefined, { exactOriginalName: true, ...(spec.resourceUri ? { resourceUri: spec.resourceUri } : {}) });
+        const { mode: _mode, ...details } = result.details;
+        return { ...result, details };
     };
 }

package/dist/gateway-arguments.d.ts

@@ -0,0 +1,33 @@
+import { Type } from "typebox";
+declare const actions: readonly ["status", "search", "list", "describe", "call", "connect", "instructions", "resources", "read-resource", "read-result", "auth-start", "auth-complete", "ui-messages"];
+export type GatewayArguments = {
+    action: typeof actions[number];
+    server?: string;
+    tool?: string;
+    args?: Record<string, unknown>;
+    query?: string;
+    includeSchemas?: boolean;
+    limit?: number;
+    offset?: number;
+    uri?: string;
+    ref?: string;
+    path?: string;
+    fields?: string[];
+};
+export declare const gatewayParameters: Type.TObject<{
+    action: Type.TUnsafe<"auth-complete" | "auth-start" | "call" | "connect" | "describe" | "instructions" | "list" | "read-resource" | "read-result" | "resources" | "search" | "status" | "ui-messages">;
+    server: Type.TOptional<Type.TString>;
+    tool: Type.TOptional<Type.TString>;
+    args: Type.TOptional<Type.TObject<{}>>;
+    query: Type.TOptional<Type.TString>;
+    includeSchemas: Type.TOptional<Type.TBoolean>;
+    limit: Type.TOptional<Type.TInteger>;
+    offset: Type.TOptional<Type.TInteger>;
+    uri: Type.TOptional<Type.TString>;
+    ref: Type.TOptional<Type.TString>;
+    path: Type.TOptional<Type.TString>;
+    fields: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+/** Migrate stored v5 calls before host validation; the advertised schema stays explicit. */
+export declare function prepareGatewayArguments(input: unknown): GatewayArguments;
+export {};

package/dist/gateway-arguments.js

@@ -0,0 +1,63 @@
+import { Type } from "typebox";
+import { MAX_PAGE_SIZE, MAX_TOOL_NAME_LENGTH } from "./search-ranking.js";
+const actions = ["status", "search", "list", "describe", "call", "connect", "instructions", "resources", "read-resource", "read-result", "auth-start", "auth-complete", "ui-messages"];
+const requirements = {
+    search: ["query"], list: ["server"], describe: ["tool"], call: ["tool"],
+    connect: ["server"], instructions: ["server"], resources: ["server"],
+    "read-resource": ["server", "uri"], "read-result": ["ref"], "auth-start": ["server"], "auth-complete": ["server"],
+};
+export const gatewayParameters = Type.Object({
+    action: Type.Unsafe({ type: "string", enum: [...actions] }),
+    server: Type.Optional(Type.String({ description: "MCP server; required for server and resource actions." })),
+    tool: Type.Optional(Type.String({ maxLength: MAX_TOOL_NAME_LENGTH, description: "Exact tool name for call or describe. Use server to disambiguate." })),
+    args: Type.Optional(Type.Object({}, { additionalProperties: true, description: "Tool arguments, or {redirectUrl} for auth-complete." })),
+    query: Type.Optional(Type.String({ description: "Search terms. Prefer mcp_search to discover and load tools." })),
+    includeSchemas: Type.Optional(Type.Boolean({ description: "Include complete schemas in search results (default true)." })),
+    limit: Type.Optional(Type.Integer({ minimum: 1, description: "Page size (default 12, max 100); for read-result, characters of selected JSON." })),
+    offset: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based item offset; for read-result, character offset in selected JSON." })),
+    uri: Type.Optional(Type.String({ description: "Exact MCP resource URI for read-resource." })),
+    ref: Type.Optional(Type.String({ description: "Saved result reference returned by an earlier MCP call; read-result never calls the server again." })),
+    path: Type.Optional(Type.String({ description: "JSON Pointer into a saved result, e.g. /structuredContent/rows." })),
+    fields: Type.Optional(Type.Array(Type.String(), { description: "Immediate object fields to retain when reading a saved result." })),
+}, {
+    additionalProperties: false,
+    allOf: [
+        ...Object.entries(requirements).map(([action, required]) => ({ if: { properties: { action: { const: action } } }, then: { required } })),
+        { if: { properties: { action: { enum: ["search", "list", "connect", "resources"] } } }, then: { properties: { limit: { maximum: MAX_PAGE_SIZE } } } },
+    ],
+});
+/** Migrate stored v5 calls before host validation; the advertised schema stays explicit. */
+export function prepareGatewayArguments(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("MCP arguments must be an object");
+    const value = input;
+    let action = value.action;
+    const result = { ...value };
+    if (action === undefined) {
+        action = value.tool ? "call" : value.connect ? "connect" : value.describe ? "describe" : value.instructions ? "instructions" : value.search !== undefined ? "search" : value.server ? "list" : "status";
+        if (action === "connect")
+            result.server = value.connect;
+        if (action === "describe")
+            result.tool = value.describe;
+        if (action === "instructions")
+            result.server = value.instructions;
+        if (action === "search")
+            result.query = value.search;
+    }
+    for (const key of ["connect", "describe", "instructions", "search"])
+        delete result[key];
+    if (!actions.includes(action))
+        throw new Error(`Unknown MCP action: ${String(action)}`);
+    result.action = action;
+    if (typeof result.args === "string") {
+        result.args = result.args === "" ? undefined : JSON.parse(result.args);
+    }
+    if (result.args !== undefined && (!result.args || typeof result.args !== "object" || Array.isArray(result.args))) {
+        throw new Error("Invalid args: expected a JSON object");
+    }
+    for (const field of requirements[action] ?? []) {
+        if (typeof result[field] !== "string" || (field !== "query" && result[field] === ""))
+            throw new Error(`${action} requires ${field}`);
+    }
+    return result;
+}