pi-mcp-adapter 3.3.0 → 4.0.0

package/index.ts

@@ -1,4 +1,4 @@
-import { withFileMutationQueue, type AgentToolUpdateCallback, type ExtensionAPI, type ExtensionContext, type ToolInfo } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue, type AgentToolResult, type AgentToolUpdateCallback, type ExtensionAPI, type ExtensionContext, type ToolInfo } from "@earendil-works/pi-coding-agent";
 import { resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -61,7 +61,7 @@ const INIT_WAIT_TIMED_OUT: unique symbol = Symbol("init-wait-timed-out");
 function hasBuiltInMcpCommand(pi: ExtensionAPI): boolean {
   if (typeof pi.getCommands !== "function") return false;
   return pi.getCommands().some((command) => /^mcp(?::\d+)?$/.test(command.name)
-    && command.sourceInfo.path === "<inline:mcp>");
+    && command.sourceInfo.path === "builtin:mcp");
 }
 
 function hasEnabledServerWithoutValidMetadata(
@@ -114,6 +114,23 @@ export interface McpRuntimeSnapshotRequest {
   result?: McpRuntimeSnapshotResult;
 }
 
+export const MCP_RUNTIME_TOOL_CALL_EVENT = "pi-mcp-adapter:runtime-tool-call:v1" as const;
+export const MCP_RUNTIME_TOOL_CALL_VERSION = 1 as const;
+
+export type McpRuntimeToolCallResult =
+  | { ok: true; result: AgentToolResult<Record<string, unknown>> }
+  | { ok: false; error: Error };
+
+/** The adapter sets `result` to a promise during `emit()`; await it. */
+export interface McpRuntimeToolCallRequest {
+  version: typeof MCP_RUNTIME_TOOL_CALL_VERSION;
+  /** Tool name as accepted by `mcp({ tool })`. */
+  tool: string;
+  args?: Record<string, unknown>;
+  server?: string;
+  result?: Promise<McpRuntimeToolCallResult>;
+}
+
 // Fast path for callers that share the adapter's module and ExtensionAPI.
 const runtimeRegistrars = new WeakMap<ExtensionAPI, (name: string, definition: ServerEntry) => McpServerRegistration>();
 const runtimeSnapshotters = new WeakMap<ExtensionAPI, (name: string) => McpRuntimeServerSnapshot>();
@@ -179,6 +196,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   const sessionConfig = options.config !== undefined ? cloneMcpConfig(options.config) : undefined;
   const programmaticConfig = sessionConfig !== undefined;
   let state: McpExtensionState | null = null;
+  let sessionCtx: ExtensionContext | null = null;
   let initPromise: Promise<McpExtensionState> | null = null;
   let initStartedPromise: Promise<void> | null = null;
   let currentOwner: McpRuntimeOwner | null = null;
@@ -336,6 +354,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   const earlyConfig = programmaticConfig
     ? resolveConfiguredClaudePluginMcp(cloneMcpConfig(sessionConfig), process.cwd())
     : excludeProjectServersAtLoadTime(loadMcpConfig(earlyConfigPath));
+  // Pi registers tools and discovers skills once per load, so the script tool and every pointer to it follow this value.
+  const scriptTool = earlyConfig.settings?.scriptMode === true;
   const earlyCache = loadMetadataCache();
   const envRaw = process.env.MCP_DIRECT_TOOLS;
   const envDirectToolOverride = parseEnvDirectToolOverride(envRaw);
@@ -597,7 +617,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       const definition = config.mcpServers[serverName];
       if (!definition || isServerDisabled(definition)) continue;
       if (entry.configHash !== computeServerHash(definition)) continue;
-      const { ttlMs: _diskTtl, ...sessionEntry } = entry;
+      const { ttlMs: _sessionTtl, cacheScope: _sessionScope, ...sessionEntry } = entry;
       servers[serverName] = { ...sessionEntry, cachedAt: Date.now() };
     }
     return { version: 1, servers };
@@ -840,6 +860,38 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       request.result = { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
     }
   });
+  pi.events.on(MCP_RUNTIME_TOOL_CALL_EVENT, (rawRequest: unknown) => {
+    if (typeof rawRequest !== "object" || rawRequest === null || Array.isArray(rawRequest)) return;
+    const request = rawRequest as McpRuntimeToolCallRequest;
+    if (request.result !== undefined) return;
+    const ctx = sessionCtx;
+    request.result = (async (): Promise<McpRuntimeToolCallResult> => {
+      try {
+        if (request.version !== MCP_RUNTIME_TOOL_CALL_VERSION) {
+          throw new Error(`Unsupported MCP runtime tool-call version: ${String(request.version)}`);
+        }
+        if (typeof request.tool !== "string" || request.tool.trim() === "") {
+          throw new Error("MCP runtime tool-call requires a non-empty `tool` name");
+        }
+        if (!ctx) throw new Error("MCP runtime tool calls require an active Pi session");
+        const callState = await awaitWithTimeout(ensureSessionRuntime(ctx), INIT_WAIT_TIMEOUT_MS);
+        if (callState === INIT_WAIT_TIMED_OUT) {
+          throw new Error(`MCP initialization is still in progress after ${INIT_WAIT_TIMEOUT_MS}ms`);
+        }
+        if (!callState) throw new Error("MCP is not initialized");
+        const guard = captureRuntimeGuard(callState);
+        const { executeCall } = await loadForRuntime(loadProxyModes, guard);
+        const result = await executeCall(callState, request.tool, request.args, request.server, getPiTools, undefined, "script");
+        assertRuntimeGuard(guard);
+        // Denials and tool errors resolve with details.error rather than rejecting.
+        const failure = result.details?.error;
+        if (failure !== undefined) return { ok: false, error: new Error(`MCP tool call failed: ${String(failure)}`) };
+        return { ok: true, result };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
+      }
+    })();
+  });
 
   const getPiTools = (): ToolInfo[] => pi.getAllTools();
 
@@ -923,6 +975,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       };
       const registeredDuringFinalization = new Set<string>();
       let statusPublicationAttempted = false;
+      nextState.scriptTool = scriptTool;
       state = nextState;
       nextState.migrationNotices = [...sessionMigrationNotices];
       finalizationGuard = guard;
@@ -1066,21 +1119,20 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     });
   }
 
+  const scriptingSkillPath = fileURLToPath(new URL("./skills/mcp-scripting/SKILL.md", import.meta.url));
   pi.on("resources_discover", (event) => {
     const resourceConfig = programmaticConfig
       ? cloneMcpConfig(sessionConfig)
       : loadMcpConfig(earlyConfigPath, event.cwd);
     const skillPaths = discoverConfiguredClaudePluginSkills(resourceConfig, event.cwd);
-    if (earlyConfig.settings?.scriptMode !== false) {
-      const scriptingSkillPath = fileURLToPath(new URL("./skills/mcp-scripting/SKILL.md", import.meta.url));
-      if (existsSync(scriptingSkillPath) && !skillPaths.includes(scriptingSkillPath)) {
-        skillPaths.push(scriptingSkillPath);
-      }
+    if (scriptTool && existsSync(scriptingSkillPath) && !skillPaths.includes(scriptingSkillPath)) {
+      skillPaths.push(scriptingSkillPath);
     }
     return skillPaths.length > 0 ? { skillPaths } : undefined;
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    sessionCtx = null;
     const builtInMcpDetected = hasBuiltInMcpCommand(pi);
     if (!builtInMcpDetected && !mcpAliasRegistered) {
       registerMcpCommand("mcp");
@@ -1122,6 +1174,9 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     }
 
     if (generation !== lifecycleGeneration || !owner.isActive()) return;
+    // Recorded only after previous-session cleanup, so a runtime tool call cannot
+    // start initialization before session_start decides whether to defer it.
+    sessionCtx = ctx;
     if (state) return;
 
     if (!initPromise) {
@@ -1214,6 +1269,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   });
 
   pi.on("session_shutdown", async () => {
+    sessionCtx = null;
     ++lifecycleGeneration;
     const currentState = state;
     const owner = currentOwner;
@@ -1526,14 +1582,18 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     },
   });
 
-  if (earlyConfig.settings?.scriptMode !== false) {
+  if (scriptTool) {
+    // The skill file is manual-only; Pi reads disable-model-invocation from the file and extensions cannot override it.
+    const skillPointer = earlyConfig.settings?.scriptSkill === "model"
+      ? ` Before writing a script, read ${scriptingSkillPath} for result shapes and limits.`
+      : "";
     (pi.registerTool as (tool: unknown) => unknown)({
       name: "mcpScript",
       label: "MCP Script",
-      description: "Run sandboxed JavaScript that makes multiple MCP tool calls in one request — loop, filter, chain, or fan out between calls. For a single MCP call, search, describe, status check, or auth action, use the mcp tool instead. Discover with await tools.search({ query }) — resolves to { items: [{ path, name, server, description? }], total, hasMore, nextOffset }, not an { ok, data } envelope. Inspect with await tools.describe({ path }) — resolves to the tool descriptor with inputTypeScript, or { path, error: { code, message, suggestions } }. Then call tools.call(path, args) — resolves to { ok: true, data } or { ok: false, error: { code, message } } — or use direct flat calls when the name is already known; use emit(value) for user-visible output.",
+      description: "Run sandboxed JavaScript to loop, filter, chain, or fan out across multiple MCP calls in one request. Use mcp for a single call, search, describe, status, or auth. await tools.search({ query }) returns { items: [{ path, name, server, description? }], total, hasMore, nextOffset }, not { ok, data }. await tools.describe({ path }) returns a descriptor with inputTypeScript or { path, error: { code, message, suggestions } }. tools.call(path, args) and tools.<path>(args) return { ok: true, data } or { ok: false, error: { code, message } }. data is the raw MCP result { content, structuredContent? }: use data.structuredContent when present; otherwise JSON usually needs JSON.parse(data.content[0].text). Use emit(value) for user-visible output." + skillPointer,
       promptSnippet: "Batch multiple MCP tool calls in one JavaScript request (loop, filter, chain)",
       parameters: Type.Object({
-        code: Type.String({ description: "Sandboxed JavaScript MCP script. Use tools.<prefixedToolName>(args) and emit(value)." }),
+        code: Type.String({ description: "Sandboxed JavaScript MCP script. Pass tool names exactly as mcp lists them, e.g. tools.call(\"github_search_issues\", args), and use emit(value)." }),
         timeoutMs: optionalNumber({ minimum: 1, description: "Execution timeout in milliseconds (default: 30000)" }),
       }),
       renderCall: createMcpScriptToolCallRenderer(toolRenderOptions),
@@ -2055,7 +2115,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       || hasEnabledServerWithoutValidMetadata(config, cache, directSpecs);
 
     if (shouldRegisterProxyTool) {
-      const description = buildProxyDescription(config);
+      const description = buildProxyDescription(config, scriptTool);
       if (!proxyToolRegistered || proxyToolDescription !== description) {
         finalizationRegistrations?.add("mcp");
         registerProxyTool(description);

package/init.ts

@@ -12,6 +12,7 @@ import {
   getMetadataCachePath,
   getMissingConfiguredDirectToolServers,
   isServerCacheValid,
+  keepOutputShapes,
   loadMetadataCache,
   reconstructPromptMetadata,
   reconstructToolMetadata,
@@ -43,6 +44,7 @@ import {
   createSessionApprovalWriter,
   restoreSessionApprovalState,
 } from "./session-approvals.ts";
+import { seedObservedOutputs } from "./output-shape.ts";
 export { getFailureAgeSeconds, getFailureMessage } from "./failure-backoff.ts";
 
 const MAX_FAILURE_MESSAGE_CHARS = 8 * 1024;
@@ -339,6 +341,7 @@ export async function initializeMcp(
       if (cachedEntry.instructions) {
         serverInstructions.set(name, cachedEntry.instructions);
       }
+      seedObservedOutputs(state, name, cachedEntry);
     }
   }
 
@@ -603,19 +606,29 @@ export function updateMetadataCache(
 
   const tools = serializeTools(connection.tools);
   let resources = definition.exposeResources === false ? [] : serializeResources(connection.resources);
+  const sessionEntry = state.sessionMetadata?.get(serverName);
+  const cacheScope = connection.toolListHints?.cacheScope;
+  // Metadata from a private listing is tied to that authorization context; it may only fill an entry that is private too.
+  const sessionFallback = sessionEntry?.configHash === configHash && (sessionEntry.cacheScope !== "private" || cacheScope === "private")
+    ? sessionEntry
+    : undefined;
   const prompts = connection.promptDiscoveryFailed
-    ? existingEntry?.configHash === configHash ? existingEntry.prompts : undefined
+    ? sessionFallback
+      ? sessionFallback.prompts
+      : existingEntry?.configHash === configHash && isServerCacheValid(existingEntry, definition)
+        ? existingEntry.prompts
+        : undefined
     : serializePrompts(connection.prompts ?? []);
 
   if (definition.exposeResources !== false && connection.resourceDiscoveryFailed === true) {
-    const sessionEntry = state.sessionMetadata?.get(serverName);
-    if (sessionEntry?.configHash === configHash) {
-      resources = sessionEntry.resources ?? [];
+    if (sessionFallback) {
+      resources = sessionFallback.resources ?? [];
     } else if (existingEntry?.resources?.length && isServerCacheValid(existingEntry, definition)) {
       resources = existingEntry.resources;
     }
   }
 
+  const outputShapes = keepOutputShapes(existingEntry, configHash, tools);
   const entry: ServerCacheEntry = {
     configHash,
     tools,
@@ -623,12 +636,14 @@ export function updateMetadataCache(
     ...(prompts !== undefined ? { prompts } : {}),
     ...(connection.instructions !== undefined ? { instructions: connection.instructions } : {}),
     ...(connection.toolListHints?.ttlMs !== undefined ? { ttlMs: connection.toolListHints.ttlMs } : {}),
-    ...(connection.toolListHints?.cacheScope !== undefined ? { cacheScope: connection.toolListHints.cacheScope } : {}),
+    ...(cacheScope !== undefined ? { cacheScope } : {}),
+    ...(outputShapes !== undefined ? { outputShapes } : {}),
     cachedAt: Date.now(),
   };
 
   (state.sessionMetadata ??= new Map()).set(serverName, entry);
   saveMetadataCache({ version: 1, servers: { [serverName]: entry } });
+  seedObservedOutputs(state, serverName, entry);
 }
 
 export function notifyToolMetadataUpdated(state: McpExtensionState, serverName: string, reason: string): void {

package/mcp-auth-flow.ts

@@ -8,6 +8,7 @@ import {
   auth as runSdkAuth,
   extractWWWAuthenticateParams,
   LATEST_PROTOCOL_VERSION,
+  RegistrationRejectedError,
   UnauthorizedError,
   validateClientMetadataUrl,
   type AuthOptions,
@@ -443,6 +444,13 @@ function parseOAuthRedirectUri(redirectUri: string): OAuthRedirectTarget {
   }
 }
 
+export function explainRegistrationRejection(error: RegistrationRejectedError, serverUrl: string): Error {
+  const hint = new URL(serverUrl).hostname === "mcp.figma.com"
+    ? "Figma's remote MCP server only accepts approved clients, and Pi isn't approved yet. Use the Figma desktop app's local server instead: run /mcp-adapter setup."
+    : "This server only accepts pre-registered OAuth clients. If the provider gave you a client ID, set oauth.clientId (and oauth.clientSecret if required) for this server."
+  return new Error(`${error.message}. ${hint}`, { cause: error })
+}
+
 /**
  * Start OAuth authentication flow for a server.
  * Returns the authorization URL when browser authorization is required.
@@ -464,6 +472,9 @@ export async function startAuth(
   const signal = combineAbortSignals(runtime.signal, options.signal)
   const generation = runtimeState.generation
   throwIfAborted(signal)
+  const explainRejection = (error: unknown): never => {
+    throw error instanceof RegistrationRejectedError ? explainRegistrationRejection(error, serverUrl) : error
+  }
 
   if (config.grantType === "client_credentials") {
     const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions)
@@ -486,7 +497,7 @@ export async function startAuth(
       const discovery = applyOAuthConfig(await probeAuthDiscovery(serverUrl, definition, signal), config)
       authority()
       throwIfAborted(signal)
-      const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }), signal)
+      const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }).catch(explainRejection), signal)
       authority()
       throwIfAborted(signal)
       if (result !== "AUTHORIZED") {
@@ -580,7 +591,7 @@ export async function startAuth(
     const discovery = applyOAuthConfig(await probeAuthDiscovery(serverUrl, definition, signal), config)
     authority()
     throwIfAborted(signal)
-    const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }), signal)
+    const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn }).catch(explainRejection), signal)
     authority()
     throwIfAborted(signal)
     if (result === "AUTHORIZED") {

package/mcp-code.ts

@@ -6,20 +6,30 @@ import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from
 import { loadMcpScriptWasm, resolveMcpScriptQuickJsUrl } from "./mcp-script-wasm.ts";
 import { evaluateJev, validateJevSettings } from "./jev-client.ts";
 import type { JevErrorCode, JevEvaluateInput, JevEvaluationEnvelope } from "./jev-contracts.ts";
-import { executeCall } from "./proxy-modes.ts";
+import { executeCall, findTools, resolveDescribeTarget, unscopedCallReachesServer } from "./proxy-modes.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
-import { paginate, rankSuggestions, rankToolMatches } from "./search-ranking.ts";
-import { semanticSearch, type SemanticSearchEvaluator } from "./semantic-search.ts";
-import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
+import { paginate } from "./search-ranking.ts";
+import type { SemanticSearchEvaluator } from "./semantic-search.ts";
 import type { McpExtensionState } from "./state.ts";
-import { findToolByName, formatSchema, hasSchemaDescriptions } from "./tool-metadata.ts";
+import { formatSchema, hasSchemaDescriptions } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
 import { getObservedOutput, renderOutputShape } from "./output-shape.ts";
+import type { ObservedOutput } from "./output-shape.ts";
 import type { ContentBlock } from "./types.ts";
 
 export const DEFAULT_MCP_SCRIPT_TIMEOUT_MS = 30_000;
 const MCP_SCRIPT_INTERMEDIATE_MAX_BYTES = 16 * 1024 * 1024;
 const MCP_SCRIPT_OUTPUT_MAX_BYTES = 16 * 1024 * 1024;
+const SEEN_FIELDS_MAX_CHARS = 8 * 1024;
+const EMPTY_RETURNS = new Set(["[]", "{}", "null", ""]);
+
+// Spelled out from the call because models otherwise read `content` off the { ok, data } envelope.
+// Names the server only when the path alone would not reach this server's tool, e.g. a name two servers share.
+const observedTarget = (state: McpExtensionState, observed: ObservedOutput, path: string, server: string) => {
+  const scope = unscopedCallReachesServer(state, path, server) ? "" : `, { server: ${JSON.stringify(server)} }`;
+  const call = `(await tools.call(${JSON.stringify(path)}, args${scope}))`;
+  return observed.source === "structuredContent" ? `${call}.data.structuredContent` : `JSON.parse(${call}.data.content[0].text)`;
+};
 
 class McpScriptTimeoutError extends Error {
   constructor(timeoutMs: number) {
@@ -29,10 +39,10 @@ class McpScriptTimeoutError extends Error {
 }
 
 type SearchInput = { query?: unknown; server?: unknown; limit?: unknown; offset?: unknown; searchMode?: unknown; regex?: unknown };
-type DescribeInput = { path?: unknown };
+type DescribeInput = { path?: unknown; server?: unknown };
 type WorkerMessage =
   | { type: "emit"; block: unknown }
-  | { type: "call"; id: number; path: string; args?: unknown }
+  | { type: "call"; id: number; path: string; args?: unknown; server?: string }
   | { type: "evaluate"; id: number; input: unknown }
   | { type: "search"; id: number; input?: unknown }
   | { type: "describe"; id: number; input?: unknown }
@@ -88,6 +98,19 @@ function textFromContent(content: ContentBlock[]): string {
     .join("\n");
 }
 
+function resultErrorMessage(result: { content: ContentBlock[]; details: Record<string, unknown> }): string {
+  return typeof result.details.message === "string" ? result.details.message : textFromContent(result.content);
+}
+
+/** Script-usable guidance for scoping errors whose shared text points at mcp(), which scripts cannot call. */
+function scriptScopeMessage(code: string, path: string, server: unknown, retry: string): string | undefined {
+  if (code === "server_not_found") return `Server "${String(server)}" not found. Use the server from a tools.search hit.`;
+  if (code !== "ambiguous_tool") return undefined;
+  return typeof server === "string"
+    ? `Tool "${path}" matches multiple tools on server "${server}". Use an exact path from tools.search({ query: "", server: ${JSON.stringify(server)} }).`
+    : `Tool "${path}" matches multiple servers. Pass the server from tools.search: ${retry}.`;
+}
+
 function abortReasonError(reason: unknown): Error {
   return reason instanceof Error ? reason : new Error(String(reason ?? "MCP request aborted"));
 }
@@ -97,9 +120,13 @@ function parseWorkerMessage(value: unknown): WorkerMessage | null {
   const message = value as Record<string, unknown>;
   if (message.type === "emit" && "block" in message) return { type: "emit", block: message.block };
   if (message.type === "call" && typeof message.id === "number" && typeof message.path === "string") {
-    return "args" in message
-      ? { type: "call", id: message.id, path: message.path, args: message.args }
-      : { type: "call", id: message.id, path: message.path };
+    return {
+      type: "call",
+      id: message.id,
+      path: message.path,
+      ...("args" in message ? { args: message.args } : {}),
+      ...(typeof message.server === "string" ? { server: message.server } : {}),
+    };
   }
   if (message.type === "evaluate" && typeof message.id === "number" && "input" in message) {
     return { type: "evaluate", id: message.id, input: message.input };
@@ -162,18 +189,21 @@ export async function runMcpScript(
   }));
   let callsSnapshot: ScriptOperation[] | undefined;
   let intermediateBytes = 0;
+  // Successful calls by server and path, for listing the result fields they returned when the script fails or finds nothing.
+  const calledTools = new Map<string, { path: string; server: string; tool: string }>();
+  let returnedEmpty = false;
   const reserveIntermediateBytes = (dataJson: string): boolean => {
     const bytes = Buffer.byteLength(dataJson, "utf8");
     if (bytes > MCP_SCRIPT_INTERMEDIATE_MAX_BYTES - intermediateBytes) return false;
     intermediateBytes += bytes;
     return true;
   };
-  const callTool = async (path: string, args?: Record<string, unknown>): Promise<WorkerResultPayload> => {
+  const callTool = async (path: string, args?: Record<string, unknown>, server?: string): Promise<WorkerResultPayload> => {
     // Record before dispatch so calls still in flight at timeout/abort appear in the trace.
     const startedAt = Date.now();
     const index = calls.push({ operation: "call", path, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
     let dataJson: string | undefined;
-    const result = await executeCall(state, path, args, undefined, getPiTools, callSignal, "script", {
+    const result = await executeCall(state, path, args, server, getPiTools, callSignal, "script", {
       onSuccess(data) {
         // Serialize once for both byte accounting and worker transfer, never for display.
         dataJson = JSON.stringify(data);
@@ -188,9 +218,7 @@ export async function runMcpScript(
         : [];
       const message = errorCode === "tool_not_found"
         ? `Tool "${path}" not found. Use await tools.search({ query: "..." }) inside mcpScript.${suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : ""}`
-        : typeof details.message === "string"
-          ? details.message
-          : textFromContent(result.content);
+        : scriptScopeMessage(errorCode, path, details.server, "tools.call(path, args, { server })") ?? resultErrorMessage(result);
       calls[index] = { operation: "call", path, ok: false, error: errorCode, durationMs: Date.now() - startedAt, startedAt };
       return {
         envelope: { ok: false, error: { code: errorCode, message } },
@@ -210,6 +238,10 @@ export async function runMcpScript(
     }
     // Rejected responses do not consume budget. This bounds transfer, not upstream allocation.
     calls[index] = { operation: "call", path, ok: true, durationMs: Date.now() - startedAt, startedAt };
+    if (typeof details.server === "string" && typeof details.tool === "string") {
+      const calledPath = typeof details.canonicalTool === "string" ? details.canonicalTool : path;
+      calledTools.set(JSON.stringify([details.server, calledPath]), { path: calledPath, server: details.server, tool: details.tool });
+    }
     return { dataJson };
   };
 
@@ -279,34 +311,27 @@ export async function runMcpScript(
     const index = calls.push({ operation: "search", query, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
     let error: unknown;
     try {
-      if (input?.searchMode !== undefined && input.searchMode !== "lexical" && input.searchMode !== "semantic") {
-        error = "invalid_search_mode";
-        return { items: [], total: 0, hasMore: false, nextOffset: null, error: { code: "invalid_search_mode", message: "Search mode must be lexical or semantic." } };
-      }
-      if (query.trim() === "" && input?.searchMode !== "semantic") {
-        return { items: [], total: 0, hasMore: false, nextOffset: null };
+      const outcome = await findTools(state, {
+        query,
+        regex: input?.regex === true,
+        server: typeof input?.server === "string" ? input.server : undefined,
+        searchMode: input?.searchMode,
+        signal: callSignal,
+        semanticEvaluator: async (semanticState, semanticInput, options) => {
+          const rejected = admitEvaluation(semanticInput);
+          if (rejected) return rejected;
+          const envelope = await (semanticEvaluator ?? evaluateJev)(semanticState, semanticInput, options);
+          return chargeEvaluationTokens(envelope);
+        },
+        observedSources: [...observedSources],
+      });
+      if ("error" in outcome) {
+        error = String(outcome.error.details.error);
+        return { items: [], total: 0, hasMore: false, nextOffset: null, error: { code: error, message: resultErrorMessage(outcome.error) } };
       }
-      const server = typeof input?.server === "string" ? input.server : undefined;
       const limit = typeof input?.limit === "number" ? input.limit : 12;
       const offset = typeof input?.offset === "number" ? input.offset : 0;
-      const searchMode = input?.searchMode === "semantic" ? "semantic" : "lexical";
-      if (searchMode === "semantic" && input?.regex === true) {
-        error = "invalid_search_mode";
-        return { items: [], total: 0, hasMore: false, nextOffset: null, error: { code: "invalid_search_mode", message: "Semantic search cannot be combined with regex search." } };
-      }
-      const semantic = searchMode === "semantic"
-        ? await semanticSearch(state, query, server, callSignal, async (semanticState, semanticInput, options) => {
-            const rejected = admitEvaluation(semanticInput);
-            if (rejected) return rejected;
-            const envelope = await (semanticEvaluator ?? evaluateJev)(semanticState, semanticInput, options);
-            return chargeEvaluationTokens(envelope);
-          }, [...observedSources])
-        : undefined;
-      if (semantic && !semantic.ok) {
-        error = semantic.error.code;
-        return { items: [], total: 0, hasMore: false, nextOffset: null, error: semantic.error };
-      }
-      const page = paginate(semantic?.matches ?? rankToolMatches(state, query, server), offset, limit);
+      const page = paginate(outcome.matches, offset, limit);
       return {
         ...page,
         items: page.items.map(({ server: matchServer, tool, score }) => ({
@@ -316,7 +341,7 @@ export async function runMcpScript(
           ...(tool.description ? { description: tool.description } : {}),
           score,
         })),
-        ...(semantic ? { backend: semantic.backend } : {}),
+        ...(outcome.backend ? { backend: outcome.backend } : {}),
       };
     } catch (caught) {
       error = caught;
@@ -333,44 +358,45 @@ export async function runMcpScript(
     const path = typeof input?.path === "string" ? input.path : "";
     let error: unknown;
     try {
-      for (const [server, metadata] of state.toolMetadata) {
-        if (isServerInActiveFailureBackoff(state, server)) continue;
-        const tool = findToolByName(metadata, path);
-        if (!tool) continue;
-        const inputShape = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
-        const inputTypeScript = inputShape ?? (tool.inputSchema ? formatSchema(tool.inputSchema) : null);
-        const observed = tool.resourceUri ? undefined : getObservedOutput(state, server, tool);
+      const target = resolveDescribeTarget(state, path, typeof input?.server === "string" ? input.server : undefined);
+      if ("error" in target) {
+        const details = target.error.details;
+        const code = String(details.error);
+        error = code;
         return {
-          path: tool.name,
-          name: tool.originalName,
-          server,
-          ...(tool.description ? { description: tool.description } : {}),
-          ...(inputTypeScript ? { inputTypeScript } : {}),
-          ...(inputShape && hasSchemaDescriptions(tool.inputSchema)
-            ? { inputGuidance: formatSchema(tool.inputSchema) } : {}),
-          ...(tool.outputSchema !== undefined ? {
-            outputSchemaTarget: "data.structuredContent",
-            outputSchema: tool.outputSchema,
-          } : {}),
-          ...(tool.annotations ? { annotations: tool.annotations } : {}),
-          ...(observed ? {
-            observedOutput: {
-              target: observed.source === "structuredContent" ? "data.structuredContent" : "JSON.parse(data.content[0].text)",
-              typeScript: renderOutputShape(observed.shape),
-              calls: observed.calls,
-            },
-          } : {}),
+          path,
+          error: {
+            code,
+            message: code === "tool_not_found"
+              ? `Tool not found: ${path}`
+              : scriptScopeMessage(code, path, details.server, "tools.describe({ path, server })") ?? resultErrorMessage(target.error),
+            suggestions: Array.isArray(details.suggestions) ? details.suggestions : [],
+          },
         };
       }
-      const suggestions = path ? rankSuggestions(state, path, 5) : [];
-      error = "tool_not_found";
+      const { server, tool } = target;
+      const inputShape = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
+      const inputTypeScript = inputShape ?? (tool.inputSchema ? formatSchema(tool.inputSchema) : null);
+      const observed = tool.resourceUri ? undefined : getObservedOutput(state, server, tool);
       return {
-        path,
-        error: {
-          code: "tool_not_found",
-          message: `Tool not found: ${path}`,
-          suggestions,
-        },
+        path: tool.name,
+        name: tool.originalName,
+        server,
+        ...(tool.description ? { description: tool.description } : {}),
+        ...(inputTypeScript ? { inputTypeScript } : {}),
+        ...(inputShape && hasSchemaDescriptions(tool.inputSchema)
+          ? { inputGuidance: formatSchema(tool.inputSchema) } : {}),
+        ...(tool.outputSchema !== undefined ? {
+          outputSchemaTarget: "data.structuredContent",
+          outputSchema: tool.outputSchema,
+        } : {}),
+        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+        ...(observed ? {
+          observedOutput: {
+            target: observedTarget(state, observed, tool.name, server),
+            typeScript: renderOutputShape(observed.shape),
+          },
+        } : {}),
       };
     } catch (caught) {
       error = caught;
@@ -457,6 +483,8 @@ export async function runMcpScript(
             rejectOutputBudget();
             return;
           }
+          const returned = message.returnBlock as { type?: unknown; text?: unknown } | undefined;
+          returnedEmpty = returned?.type === "text" && typeof returned.text === "string" && EMPTY_RETURNS.has(returned.text.trim());
           completed = true;
           resolve();
           return;
@@ -470,7 +498,7 @@ export async function runMcpScript(
         void (async () => {
           let payload: WorkerResultPayload;
           if (message.type === "call") {
-            payload = await callTool(message.path, message.args as Record<string, unknown> | undefined);
+            payload = await callTool(message.path, message.args as Record<string, unknown> | undefined, message.server);
           } else if (message.type === "evaluate") {
             payload = await evaluate(message.input);
           } else if (message.type === "search") {
@@ -514,10 +542,30 @@ export async function runMcpScript(
     await worker?.terminate();
   }
 
+  // A script that fails or finds nothing after calling a tool without an output schema usually guessed
+  // the result fields wrong. Listing the fields seen saves a separate turn spent looking at the data.
+  let seenFields: string | undefined;
+  if (errorCode === "timeout" || errorCode === "script_error" || returnedEmpty || output.length === 0) {
+    const sections: string[] = [];
+    let chars = 0;
+    for (const { path, server, tool } of calledTools.values()) {
+      const meta = state.toolMetadata.get(server)?.find(entry => entry.originalName === tool && !entry.resourceUri);
+      const observed = meta && getObservedOutput(state, server, meta);
+      if (!observed) continue;
+      const section = `${observedTarget(state, observed, path, server)} is:\n${renderOutputShape(observed.shape)}`;
+      if (chars + section.length > SEEN_FIELDS_MAX_CHARS) break;
+      chars += section.length;
+      sections.push(section);
+    }
+    if (sections.length > 0) {
+      seenFields = `\n\n[Result fields seen from the tools this script called (names and types only, not a contract):\n${sections.join("\n\n")}]`;
+    }
+  }
+
   // Snapshot before the asynchronous output guard; the terminated worker can no longer emit.
   const guarded = await guardMcpOutput(
     output.length > 0 ? [...output] : [{ type: "text", text: "(no output)" }],
-    resolveMcpOutputGuardOptions(state.config.settings),
+    { ...resolveMcpOutputGuardOptions(state.config.settings), ...(seenFields ? { footer: seenFields } : {}) },
   );
   return {
     content: guarded.content,