pi-mcp-adapter 3.3.0 → 4.0.0

package/proxy-modes.ts

@@ -9,17 +9,17 @@ import { abortable, throwIfAborted } from "./abort.ts";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
 import { buildToolMetadata, getToolNames, formatSchema } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
-import { getObservedOutput, recordObservedOutput, renderOutputShape } from "./output-shape.ts";
+import { getObservedOutput, observedOutputRecorder, renderOutputShape } from "./output-shape.ts";
 import { reconstructPromptMetadata } from "./metadata-cache.ts";
 import { resolveMcpResultContent, transformMcpResourceContents } from "./tool-registrar.ts";
-import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
+import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions, scriptPipeHint } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
 import { formatAuthRequiredMessage, formatMcpStatus, normalizeToolArguments, resolveServerUrl, truncateAtWord, withToolCallIdMeta } from "./utils.ts";
 import { authenticate, completeAuthFromInput, getAuthStatus, startAuth, supportsOAuth } from "./mcp-auth-flow.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
 import { callToolViaTaskSession } from "./mcp-tasks.ts";
 import { callToolPausingForElicitation } from "./elicitation-handler.ts";
-import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords } from "./search-ranking.ts";
+import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords, type RankedToolMatch } from "./search-ranking.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
 import { describeFailure, isServerInActiveFailureBackoff } from "./failure-backoff.ts";
 import { semanticSearch, type SemanticSearchBackend, type SemanticSearchEvaluator } from "./semantic-search.ts";
@@ -722,26 +722,28 @@ function formatToolHints(toolMeta: ToolMetadata): string {
   return hints.join(", ");
 }
 
-export function executeDescribe(state: McpExtensionState, toolName: string, serverOverride?: string): ProxyToolResult {
-  let serverName: string | undefined;
-  let toolMeta: ToolMetadata | undefined;
-  let disabledMatch: string | undefined;
-  let failedMatch: string | undefined;
-
+export function resolveDescribeTarget(
+  state: McpExtensionState,
+  toolName: string,
+  serverOverride?: string,
+): { server: string; tool: ToolMetadata } | { error: ProxyToolResult } {
   if (serverOverride) {
     if (!state.config.mcpServers[serverOverride]) {
       return {
-        content: [{ type: "text" as const, text: `Server "${serverOverride}" not found. Use mcp({}) to see available servers.` }],
-        details: { mode: "describe", error: "server_not_found", server: serverOverride, requestedTool: toolName },
+        error: {
+          content: [{ type: "text" as const, text: `Server "${serverOverride}" not found. Use mcp({}) to see available servers.` }],
+          details: { mode: "describe", error: "server_not_found", server: serverOverride, requestedTool: toolName },
+        },
       };
     }
     const match = getServerScopedToolMatch(state.toolMetadata.get(serverOverride), toolName);
-    if (match === "ambiguous") return ambiguousServerToolResult("describe", toolName, serverOverride);
-    if (isServerDisabled(state.config.mcpServers[serverOverride])) return disabledResult(state, "describe", serverOverride);
-    if (isServerInActiveFailureBackoff(state, serverOverride)) return serverBackoffResult(state, "describe", serverOverride);
-    serverName = serverOverride;
-    toolMeta = match?.tool;
+    if (match === "ambiguous") return { error: ambiguousServerToolResult("describe", toolName, serverOverride) };
+    if (isServerDisabled(state.config.mcpServers[serverOverride])) return { error: disabledResult(state, "describe", serverOverride) };
+    if (isServerInActiveFailureBackoff(state, serverOverride)) return { error: serverBackoffResult(state, "describe", serverOverride) };
+    if (match) return { server: serverOverride, tool: match.tool };
   } else {
+    let disabledMatch: string | undefined;
+    let failedMatch: string | undefined;
     const matches: Array<{ server: string; tool: ToolMetadata; precedence: number }> = [];
     for (const [server, metadata] of state.toolMetadata.entries()) {
       const candidates = getServerScopedToolCandidates(metadata, toolName);
@@ -759,27 +761,31 @@ export function executeDescribe(state: McpExtensionState, toolName: string, serv
     if (matches.length > 0) {
       const precedence = Math.min(...matches.map(match => match.precedence));
       const bestMatches = matches.filter(match => match.precedence === precedence);
-      if (bestMatches.length > 1) return ambiguousToolResult("describe", toolName);
-      serverName = bestMatches[0]!.server;
-      toolMeta = bestMatches[0]!.tool;
+      if (bestMatches.length > 1) return { error: ambiguousToolResult("describe", toolName) };
+      return { server: bestMatches[0]!.server, tool: bestMatches[0]!.tool };
     }
+    if (disabledMatch) return { error: disabledResult(state, "describe", disabledMatch) };
+    if (failedMatch) return { error: serverBackoffResult(state, "describe", failedMatch) };
   }
 
-  if (!serverName || !toolMeta) {
-    if (disabledMatch) return disabledResult(state, "describe", disabledMatch);
-    if (failedMatch) return serverBackoffResult(state, "describe", failedMatch);
-    const suggestions = rankSuggestions(state, toolName, 5, serverOverride);
-    const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
-    const scopeText = serverOverride ? ` on server "${serverOverride}"` : "";
-    const searchHint = serverOverride
-      ? `mcp({ search: "...", server: "${serverOverride}" })`
-      : `mcp({ search: "..." })`;
-    return {
+  const suggestions = rankSuggestions(state, toolName, 5, serverOverride);
+  const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
+  const scopeText = serverOverride ? ` on server "${serverOverride}"` : "";
+  const searchHint = serverOverride
+    ? `mcp({ search: "...", server: "${serverOverride}" })`
+    : `mcp({ search: "..." })`;
+  return {
+    error: {
       content: [{ type: "text" as const, text: `Tool "${toolName}" not found${scopeText}. Use ${searchHint} to search.${suggestionText}` }],
       details: { mode: "describe", error: "tool_not_found", server: serverOverride, requestedTool: toolName, suggestions },
-    };
-  }
+    },
+  };
+}
 
+export function executeDescribe(state: McpExtensionState, toolName: string, serverOverride?: string): ProxyToolResult {
+  const target = resolveDescribeTarget(state, toolName, serverOverride);
+  if ("error" in target) return target.error;
+  const { server: serverName, tool: toolMeta } = target;
   const approvalMarker = isToolCallApprovalRequired(state.config, serverName, toolMeta, state.toolMetadata)
     ? " (requires approval)"
     : "";
@@ -804,7 +810,7 @@ export function executeDescribe(state: McpExtensionState, toolName: string, serv
   const observed = toolMeta.resourceUri ? undefined : getObservedOutput(state, serverName, toolMeta);
   if (observed) {
     const source = observed.source === "structuredContent" ? "structuredContent" : "JSON text result";
-    text += `\n\nObserved output (${source}, from ${observed.calls} call${observed.calls === 1 ? "" : "s"} this session, not a contract):\n${renderOutputShape(observed.shape)}`;
+    text += `\n\nObserved output (${source}, from earlier calls, not a contract):\n${renderOutputShape(observed.shape)}`;
   }
 
   return {
@@ -885,81 +891,66 @@ function renderSearchResults(
   };
 }
 
-export function executeSearch(
-  state: McpExtensionState,
-  query: string,
-  regex?: boolean,
-  server?: string,
-  includeSchemas?: boolean,
-  limit = 12,
-  offset = 0,
-  searchMode: "lexical" | "semantic" = "lexical",
-  signal?: AbortSignal,
-  semanticEvaluator?: SemanticSearchEvaluator,
-): ProxyToolResult | Promise<ProxyToolResult> {
-  const showSchemas = includeSchemas !== false;
-  if ((searchMode as string) !== "lexical" && (searchMode as string) !== "semantic") {
-    return {
-      content: [{ type: "text" as const, text: "Search mode must be lexical or semantic." }],
-      details: { mode: "search", error: "invalid_search_mode", query },
-    };
+export interface ToolSearchInput {
+  query: string;
+  regex?: boolean | undefined;
+  server?: string | undefined;
+  searchMode?: unknown;
+  signal?: AbortSignal | undefined;
+  semanticEvaluator?: SemanticSearchEvaluator | undefined;
+  observedSources?: readonly string[];
+}
+
+/** Ranked matches, unpaginated; each surface pages and renders them its own way. */
+export type ToolSearchOutcome =
+  | { matches: RankedToolMatch[]; backend?: SemanticSearchBackend }
+  | { error: ProxyToolResult };
+
+export function findTools(state: McpExtensionState, input: ToolSearchInput): ToolSearchOutcome | Promise<ToolSearchOutcome> {
+  const { query, regex, server, searchMode = "lexical" } = input;
+  const failure = (text: string, details: Record<string, unknown>): ToolSearchOutcome => ({
+    error: { content: [{ type: "text" as const, text }], details: { mode: "search", ...details } },
+  });
+  if (searchMode !== "lexical" && searchMode !== "semantic") {
+    return failure("Search mode must be lexical or semantic.", { error: "invalid_search_mode", query });
   }
-  if (server && isServerDisabled(state.config.mcpServers[server])) return disabledResult(state, "search", server);
-  if (server && isServerInActiveFailureBackoff(state, server)) return serverBackoffResult(state, "search", server);
+  if (server && isServerDisabled(state.config.mcpServers[server])) return { error: disabledResult(state, "search", server) };
+  if (server && isServerInActiveFailureBackoff(state, server)) return { error: serverBackoffResult(state, "search", server) };
   if (searchMode === "semantic" && regex) {
-    return {
-      content: [{ type: "text" as const, text: "Semantic search cannot be combined with regex search." }],
-      details: { mode: "search", error: "invalid_search_mode", query },
-    };
+    return failure("Semantic search cannot be combined with regex search.", { error: "invalid_search_mode", query });
   }
   if (searchMode === "semantic") {
-    return semanticSearch(state, query, server, signal, semanticEvaluator).then(result => {
-      if (!result.ok) {
-        return {
-          content: [{ type: "text" as const, text: `Semantic search failed: ${result.error.message}` }],
-          details: { mode: "search", error: result.error.code, message: result.error.message, query },
-        };
-      }
-      return renderSearchResults(state, query, server, showSchemas, limit, offset, result.matches, result.backend);
-    });
+    return semanticSearch(state, query, server, input.signal, input.semanticEvaluator, input.observedSources).then(result => result.ok
+      ? { matches: result.matches, backend: result.backend }
+      : failure(`Semantic search failed: ${result.error.message}`, { error: result.error.code, message: result.error.message, query }));
   }
 
-  let matches: Array<{ server: string; tool: ToolMetadata; score: number }>;
   if (regex) {
+    if (query.length > MAX_REGEX_SEARCH_QUERY_LENGTH) {
+      return failure(
+        `Regex query is too long; maximum length is ${MAX_REGEX_SEARCH_QUERY_LENGTH} characters.`,
+        { error: "query_too_long", query, maxLength: MAX_REGEX_SEARCH_QUERY_LENGTH },
+      );
+    }
     let pattern: RegExp;
     try {
-      if (query.length > MAX_REGEX_SEARCH_QUERY_LENGTH) {
-        return {
-          content: [{ type: "text" as const, text: `Regex query is too long; maximum length is ${MAX_REGEX_SEARCH_QUERY_LENGTH} characters.` }],
-          details: { mode: "search", error: "query_too_long", query, maxLength: MAX_REGEX_SEARCH_QUERY_LENGTH },
-        };
-      }
       pattern = new RegExp(query, "i");
-      let safety;
-      try {
-        const { checkSync } = require("recheck") as typeof import("recheck");
-        safety = checkSync(query, "i", REGEX_SAFETY_CHECK_PARAMS);
-      } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        return {
-          content: [{ type: "text" as const, text: "Regex query rejected because safety analysis failed." }],
-          details: { mode: "search", error: "unsafe_pattern", query, reason },
-        };
-      }
-      if (safety.status !== "safe") {
-        return {
-          content: [{ type: "text" as const, text: `Regex query rejected as unsafe (${safety.status}).` }],
-          details: { mode: "search", error: "unsafe_pattern", query, safetyStatus: safety.status },
-        };
-      }
     } catch {
-      return {
-        content: [{ type: "text" as const, text: `Invalid regex: ${query}` }],
-        details: { mode: "search", error: "invalid_pattern", query },
-      };
+      return failure(`Invalid regex: ${query}`, { error: "invalid_pattern", query });
+    }
+    let safety;
+    try {
+      const { checkSync } = require("recheck") as typeof import("recheck");
+      safety = checkSync(query, "i", REGEX_SAFETY_CHECK_PARAMS);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      return failure("Regex query rejected because safety analysis failed.", { error: "unsafe_pattern", query, reason });
+    }
+    if (safety.status !== "safe") {
+      return failure(`Regex query rejected as unsafe (${safety.status}).`, { error: "unsafe_pattern", query, safetyStatus: safety.status });
     }
 
-    matches = [];
+    const matches: RankedToolMatch[] = [];
     const globalPrefix = state.config.settings?.toolPrefix ?? "server";
     for (const [serverName, metadata] of state.toolMetadata.entries()) {
       const definition = state.config.mcpServers[serverName];
@@ -972,21 +963,37 @@ export function executeSearch(
         if (matched) matches.push({ server: serverName, tool, score: 0 });
       }
     }
-  } else if (query.trim().length === 0) {
-    if (!server) {
-      return {
-        content: [{ type: "text" as const, text: "Search query cannot be empty" }],
-        details: { mode: "search", error: "empty_query" },
-      };
-    }
-    matches = (state.toolMetadata.get(server) ?? [])
-      .map(tool => ({ server, tool, score: 0 }))
-      .sort((a, b) => a.tool.name.localeCompare(b.tool.name));
-  } else {
-    matches = rankToolMatches(state, query, server);
+    return { matches };
+  }
+
+  if (query.trim().length === 0) {
+    if (!server) return failure("Search query cannot be empty", { error: "empty_query" });
+    return {
+      matches: (state.toolMetadata.get(server) ?? [])
+        .map(tool => ({ server, tool, score: 0 }))
+        .sort((a, b) => a.tool.name.localeCompare(b.tool.name)),
+    };
   }
+  return { matches: rankToolMatches(state, query, server) };
+}
 
-  return renderSearchResults(state, query, server, showSchemas, limit, offset, matches);
+export function executeSearch(
+  state: McpExtensionState,
+  query: string,
+  regex?: boolean,
+  server?: string,
+  includeSchemas?: boolean,
+  limit = 12,
+  offset = 0,
+  searchMode: "lexical" | "semantic" = "lexical",
+  signal?: AbortSignal,
+  semanticEvaluator?: SemanticSearchEvaluator,
+): ProxyToolResult | Promise<ProxyToolResult> {
+  const render = (outcome: ToolSearchOutcome): ProxyToolResult => "error" in outcome
+    ? outcome.error
+    : renderSearchResults(state, query, server, includeSchemas !== false, limit, offset, outcome.matches, outcome.backend);
+  const outcome = findTools(state, { query, regex, server, searchMode, signal, semanticEvaluator });
+  return outcome instanceof Promise ? outcome.then(render) : render(outcome);
 }
 
 export function executeList(state: McpExtensionState, server: string): ProxyToolResult {
@@ -1178,6 +1185,12 @@ export async function executeConnect(state: McpExtensionState, serverName: strin
   }
 }
 
+/** Whether executeCall without a server resolves this exact displayed tool name to serverName (its first, exact-name lookup). */
+export function unscopedCallReachesServer(state: McpExtensionState, toolName: string, serverName: string): boolean {
+  const matches = getEnabledToolMatches(state, toolName, true);
+  return matches.length === 1 && matches[0]!.server === serverName;
+}
+
 export async function executeCall(
   state: McpExtensionState,
   toolName: string,
@@ -1636,6 +1649,7 @@ export async function executeCall(
       : null;
 
     const requestMeta = withToolCallIdMeta(uiSession?.requestMeta, toolCallId);
+    const recordOutput = observedOutputRecorder(state, serverName, toolMeta.originalName);
     const result = await withSessionRecovery<ClientCallToolResult>(
       {
         manager: state.manager,
@@ -1662,7 +1676,7 @@ export async function executeCall(
         }, requestOptions), ownedSignal);
       },
     );
-    if (!result.isError) recordObservedOutput(state, serverName, toolMeta.originalName, result as Record<string, unknown>);
+    if (!result.isError) recordOutput(result as Record<string, unknown>);
 
     if (toolMeta.uiResourceUri) {
       uiSession?.sendToolResult(result as unknown as import("@modelcontextprotocol/client").CallToolResult);
@@ -1714,7 +1728,9 @@ export async function executeCall(
 
     const content = resolveMcpResultContent(result as Record<string, unknown>, state.owner?.signal);
     const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
-    const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, rawMcpResult: result });
+    // Runtime event-bus callers ("script" origin) are extensions, not the model, so they get no hint.
+    const pipeHint = scriptPipeHint(origin !== "script" && state.scriptTool, outputContent);
+    const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, ...pipeHint, rawMcpResult: result });
     return {
       content: guarded.content,
       details: { mode: "call", ...guardedMcpDetails(guarded), ...callIdentity },

package/server-manager.ts

@@ -18,6 +18,7 @@ import {
   type SubscriptionFilter,
   type CacheableRequestOptions,
   type RequestOptions,
+  RegistrationRejectedError,
   type UrlElicitationRequiredError,
   type VersionNegotiationOptions,
 } from "@modelcontextprotocol/client";
@@ -43,7 +44,7 @@ import { logger } from "./logger.ts";
 import { RESOURCE_MIME_TYPE } from "./ui-app-bridge-helpers.ts";
 import { isBuiltInAgentPlugin } from "./agent-plugin-provenance.ts";
 import { McpOAuthProvider } from "./mcp-oauth-provider.ts";
-import { extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
+import { explainRegistrationRejection, extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import {
   captureOAuthAuthority,
   inspectAuthForUrl,
@@ -110,17 +111,22 @@ function isLiteralLocalAddress(url: string): boolean {
   return local.check(hostname, family === 6 ? "ipv6" : "ipv4");
 }
 
-function localNetworkFailureCodes(error: unknown, seen = new Set<object>()): string[] {
+function isLoopbackUrl(url: string): boolean {
+  return ["localhost", "127.0.0.1", "[::1]"].includes(new URL(url).hostname);
+}
+
+const LOCAL_NETWORK_FAILURE_CODES = ["EHOSTUNREACH", "ENETUNREACH", "EACCES"];
+
+function networkFailureCodes(error: unknown, wanted: readonly string[], seen = new Set<object>()): string[] {
   if (typeof error !== "object" || error === null || seen.has(error)) return [];
   seen.add(error);
   const codes: string[] = [];
-  if ("code" in error && typeof error.code === "string"
-    && ["EHOSTUNREACH", "ENETUNREACH", "EACCES"].includes(error.code)) {
+  if ("code" in error && typeof error.code === "string" && wanted.includes(error.code)) {
     codes.push(error.code);
   }
-  if ("cause" in error) codes.push(...localNetworkFailureCodes(error.cause, seen));
+  if ("cause" in error) codes.push(...networkFailureCodes(error.cause, wanted, seen));
   if (error instanceof AggregateError) {
-    for (const nested of error.errors) codes.push(...localNetworkFailureCodes(nested, seen));
+    for (const nested of error.errors) codes.push(...networkFailureCodes(nested, wanted, seen));
   }
   return [...new Set(codes)];
 }
@@ -1287,9 +1293,15 @@ export class McpServerManager {
   }
 
   private async enrichHttpConnectionError(definition: ServerDefinition, error: unknown): Promise<Error> {
+    // The transport's OAuth provider can register a client during connect, bypassing startAuth.
+    if (error instanceof RegistrationRejectedError) return explainRegistrationRejection(error, resolveServerUrl(definition)!);
     const originalMessage = error instanceof Error ? error.message : String(error);
+    if (networkFailureCodes(error, ["ECONNREFUSED"]).length > 0 && isLoopbackUrl(resolveServerUrl(definition)!)) {
+      const url = new URL(resolveServerUrl(definition)!);
+      return new Error(`${originalMessage} — Nothing is listening at ${url.origin}${url.pathname}. Start the app or local process that serves this MCP server.`, { cause: error });
+    }
     if (process.platform === "darwin") {
-      const codes = localNetworkFailureCodes(error);
+      const codes = networkFailureCodes(error, LOCAL_NETWORK_FAILURE_CODES);
       if (codes.length > 0 && isLiteralLocalAddress(resolveServerUrl(definition)!)) {
         return new Error(`${originalMessage} — ${codes.join(", ")} — macOS Local Network Privacy may be blocking access. Check System Settings > Privacy & Security > Local Network for the app hosting Pi; enable access if listed and restart it. Try launching Pi from Terminal.app or SSH. Routing or firewall problems can also cause this error.`, { cause: error });
       }
@@ -1422,8 +1434,7 @@ export class McpServerManager {
     if (!connection || connection.client !== client || connection.status !== "connected") return;
     connection.tools = tools;
     connection.toolsRevision = (connection.toolsRevision ?? 0) + 1;
-    this.metadataListChangedListener?.(serverName, "tools-list-changed");
-    this.pendingMetadataPublications.delete(serverName);
+    this.publishMetadataChanged(serverName, connection, "tools-list-changed");
   }
 
   private handlePromptsListChanged(
@@ -1441,8 +1452,7 @@ export class McpServerManager {
     if (!connection || connection.client !== client || connection.status !== "connected") return;
     connection.prompts = prompts;
     connection.promptDiscoveryFailed = false;
-    this.metadataListChangedListener?.(serverName, "prompts-list-changed");
-    this.pendingMetadataPublications.delete(serverName);
+    this.publishMetadataChanged(serverName, connection, "prompts-list-changed");
   }
 
   private handleResourcesListChanged(
@@ -1460,8 +1470,7 @@ export class McpServerManager {
     if (!connection || connection.client !== client || connection.status !== "connected") return;
     connection.resources = resources;
     connection.resourceDiscoveryFailed = false;
-    this.metadataListChangedListener?.(serverName, "resources-list-changed");
-    this.pendingMetadataPublications.delete(serverName);
+    this.publishMetadataChanged(serverName, connection, "resources-list-changed");
   }
 
   async handleUrlElicitationRequired(
@@ -1631,13 +1640,17 @@ export class McpServerManager {
     > => {
       const authProvider = "provider" in authState ? authState.provider : undefined;
       let sseFetchFailure: unknown;
-      const transportFetch: FetchLike | undefined = kind === "sse" && process.platform === "darwin" && isLiteralLocalAddress(serverUrl)
+      const sseFailureCodes = kind !== "sse" ? []
+        : isLoopbackUrl(serverUrl) ? ["ECONNREFUSED"]
+        : process.platform === "darwin" && isLiteralLocalAddress(serverUrl) ? LOCAL_NETWORK_FAILURE_CODES
+        : [];
+      const transportFetch: FetchLike | undefined = sseFailureCodes.length > 0
         ? async (input, init) => {
           try {
             return await (requestFetch ?? globalThis.fetch)(input, init);
           } catch (error) {
             // EventSource discards the fetch cause before the SDK creates SseError.
-            if (localNetworkFailureCodes(error).length > 0) sseFetchFailure = error;
+            if (networkFailureCodes(error, sseFailureCodes).length > 0) sseFetchFailure = error;
             throw error;
           }
         }

package/skills/mcp-scripting/SKILL.md

@@ -1,51 +1,45 @@
 ---
 name: mcp-scripting
-description: Write mcpScript JavaScript for discovering, inspecting, and calling MCP tools.
+description: Read before writing mcpScript code. Covers tool discovery, the shape of call results (including JSON returned as text), and script limits.
 disable-model-invocation: true
 ---
 
 # MCP scripting
 
-For multi-call MCP work, write ordinary JavaScript with loops, filtering, chaining, fan-out, or other logic between calls. Run that source with `mcpScript`; it is the primary MCP orchestration surface. For a single MCP search, describe, status check, auth action, or tool call, use `mcp` instead.
+Use `mcpScript` when a request needs several MCP calls with logic between them, or when one call's output should go straight into another call. For a single search, describe, status check, auth action, or call, use `mcp`.
 
-Write the source naturally, then pass it as `mcpScript`'s `code` argument:
+Only what the script emits, logs, or returns enters the conversation, so keep intermediate data in variables and return a small result:
 
 ```js
-const { items } = await tools.search({ query: "search issues", server: "github" });
-const candidate = items[0];
-if (!candidate) return { error: "No matching tool" };
+const found = await tools.search({ query: "list issues", server: "github" });
+const path = found.items[0]?.path;
+if (!path) return { error: "No matching tool" };
 
-const details = await tools.describe({ path: candidate.path });
-if (details.error) return details;
-
-const result = await tools.call(details.path, { query: "is:open label:bug" });
+const result = await tools.call(path, { state: "open" });
 if (!result.ok) return result;
-emit({ tool: details.path, completed: true });
-return result.data;
+const issues = result.data.structuredContent ?? JSON.parse(result.data.content[0].text);
+return issues.filter((issue) => issue.comments === 0).map((issue) => issue.number);
 ```
 
-## Workflow
-
-1. Find candidate tools with `await tools.search({ query, server?, limit?, offset? })`.
-2. Inspect the exact returned path with `await tools.describe({ path })`.
-3. Call it with `tools.call(path, args)`.
-
-Descriptors include `inputTypeScript` (a compact parameter shape, or formatted schema fallback). When a compact shape would omit documented fields, `inputGuidance` preserves their descriptions, including formats and units. Undocumented inputs stay compact.
-
-When advertised by the server, `outputSchema` is the original JSON Schema and `outputSchemaTarget` is `"data.structuredContent"`: it describes structured output inside the successful `{ ok: true, data }` call envelope, not the envelope itself. Inspect this schema for result fields and constraints; unsupported constructs remain intact rather than being presented as an approximate TypeScript type. Both output fields are absent when no output schema is advertised. Discovery and cache refresh preserve these optional schemas; old cache entries gain them on the next server metadata refresh. Ordinary search results do not include schemas.
-
-When no output schema is advertised but the tool already returned structured content or a JSON text result earlier in this session, `observedOutput` gives `{ target, typeScript, calls }`: the path inside the call envelope (`"data.structuredContent"` or `"JSON.parse(data.content[0].text)"`), the field names and types seen so far, and how many calls they came from. It is a hint, not a contract: fields missing from some results are optional, and wide objects appear as `Record<string, ...>`.
+## API
 
-Calls resolve to `{ ok: true, data }` or `{ ok: false, error }`; handle failed calls instead of expecting them to stop the script. `emit(value)` adds user-visible output before the final `return` value. `console` output is captured too.
+- `await tools.search({ query, server?, regex?, searchMode?, limit?, offset? })` returns `{ items: [{ path, name, server, description? }], total, hasMore, nextOffset }`, plus `error: { code, message }` when the search cannot run. It is the same search as `mcp({ search })`; an empty `query` with `server` lists that server's tools. Filter the items in code; follow `nextOffset` for more than one page.
+- `await tools.describe({ path, server? })` returns `inputTypeScript` (plus `inputGuidance` when documented fields would otherwise be lost) and optional `annotations`. When the server declares an `outputSchema`, it describes `data.structuredContent`. Otherwise, once the tool has returned JSON (in this or an earlier `mcpScript` session), `observedOutput` gives `{ target, typeScript }`: where the JSON is, and the field names and types seen so far. It is a hint, not a contract.
+- `await tools.call(path, args, { server }?)` returns `{ ok: true, data }` or `{ ok: false, error: { code, message } }`. A failed call does not stop the script. When two servers share a tool name, pass the hit's `server` to `describe` and `call`.
+- Known paths can be called directly and resolve the same `{ ok, data }` way: `tools.github_search_issues(args)`, or `tools["server_tool-name"](args)` for hyphenated names. `tools` cannot be enumerated. `search`, `call`, `describe`, `then`, `catch`, `finally`, `toJSON`, `toString`, and `valueOf` are reserved; call a colliding path with `tools.call`.
+- `emit(value)` adds output before the final `return` value; `console` output is captured too.
 
-With `settings.jev.scriptEvaluation` enabled, call `jev.evaluate({ state, questions, sources })`; declare every MCP server represented in state. The host conservatively taints the whole script with every server-attributed call result or error, so every declared or observed source must remain enabled and allowed for later direct evaluations and semantic searches. Semantic search requires `searchMode: "semantic"`. Direct and semantic attempts share count, UTF-8 request-byte, deadline, and provider-reported token budgets. Scores do not bypass `tools.call` approval. Action loops must use fresh observations, positive step/time/evaluation budgets, validated operations and targets, and stop on uncertainty, staleness, no progress, no match, or missing information. Do not retry a possibly side-effectful action.
+## Reading results
 
-On success, `data` may still be the raw MCP `CallToolResult` envelope rather than the domain payload. Check `data.structuredContent` for the fields your script expects; if they are absent, inspect text blocks in `data.content` too (some servers emit newline-delimited JSON). If neither shape is understood, return or emit the envelope for inspection instead of coercing it to `[]` or `{}`.
+A tool call's `data` is the raw MCP `CallToolResult` (`{ content, structuredContent?, isError? }`), not the domain payload; resource reads return text. Use `data.structuredContent` when present. Otherwise most JSON APIs return their payload as text, so parse `data.content[0].text` (some servers emit newline-delimited JSON). If neither shape is understood, emit the envelope for inspection instead of coercing it to `[]` or `{}`.
 
-`tools` is a non-enumerable proxy: `Object.keys(tools)` throws. Always use `tools.search` for discovery. When a known flat path is a valid identifier, direct calls such as `tools.github_search_issues(args)` are supported; use bracket syntax for hyphenated names: `tools["server_tool-name"](args)`. `search`, `call`, `describe`, and promise/serialization names (`then`, `catch`, `finally`, `toJSON`, `toString`, `valueOf`) are reserved on the proxy; if a flat path collides with one, call it via `tools.call("exact-path", args)`.
+Write the real script first instead of spending a turn looking at a result. Use `observedOutput` when describe has it; otherwise use the tool description and the field names the API most likely uses. Before a loop that writes (comments, closes, creates), check that the first item has the fields you filter on and throw if it does not, so a wrong guess stops before it changes anything. When a script throws, times out, or returns `[]`, `{}`, `null`, or `""`, its result lists the fields seen from the tools it called; fix the script from that. Never emit a whole list to inspect it.
 
-Successful intermediate data bypasses presentation truncation, summarization, and artifact spill until the script emits, logs, or returns it. A fixed, non-configurable **16 MiB cumulative UTF-8 JSON transfer budget per script** covers sequential and parallel calls. A result exceeding the remaining budget returns `{ ok: false, error: { code: "intermediate_result_too_large", message } }` with a failed call trace; rejected calls do not consume the budget, but upstream side effects may already have happened. Resource calls retain transformed text or `"(empty resource)"`; emitted, logged, or returned output and ordinary MCP calls remain guarded. This is not a memory limit: responses, serialization, copies, concurrency, and script values still allocate memory, and synchronous serialization can delay deadline handling.
+## Limits
 
-`tools.search` and `tools.describe` are asynchronous and must be awaited. The default script timeout is 30 seconds; the worker is terminated at the deadline, including for infinite loops. Every invocation still uses normal lazy connection, authentication, and approval gates. Result details contain a concise `calls` trace with every search, describe, and call operation; each entry includes its query or path, outcome, and duration.
+- Scripts time out after 30 seconds by default (`timeoutMs` changes it). The worker is stopped at the deadline, including infinite loops.
+- Intermediate results share a fixed 16 MiB transfer budget per script. A result that does not fit returns `{ ok: false, error: { code: "intermediate_result_too_large" } }`, and the upstream call may still have had side effects.
+- Every call goes through the normal connection, auth, and approval gates. The result details list each search, describe, and call with its outcome and duration.
+- There are no fluent helpers such as `tools.find`, `tools.parallel`, or `tools.retry`; use loops and `Promise.all`.
 
-Use plain JavaScript loops and Promise utilities for composition. Fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided.
+When `settings.jev.scriptEvaluation` is enabled, read [references/jev.md](references/jev.md) before calling `jev.evaluate`.

package/skills/mcp-scripting/references/jev.md

@@ -0,0 +1,3 @@
+# jev.evaluate in mcpScript
+
+With `settings.jev.scriptEvaluation` enabled, call `jev.evaluate({ state, questions, sources })`; declare every MCP server represented in state. The host conservatively taints the whole script with every server-attributed call result or error, so every declared or observed source must remain enabled and allowed for later direct evaluations and semantic searches. Semantic search requires `searchMode: "semantic"`. Direct and semantic attempts share count, UTF-8 request-byte, deadline, and provider-reported token budgets. Scores do not bypass `tools.call` approval. Action loops must use fresh observations, positive step/time/evaluation budgets, validated operations and targets, and stop on uncertainty, staleness, no progress, no match, or missing information. Do not retry a possibly side-effectful action.

package/state.ts

@@ -60,6 +60,8 @@ export interface McpExtensionState {
   observedOutputs?: WeakMap<ServerDefinition, Map<string, ObservedOutput>>;
   /** Configured project servers disabled by trust or approval policy for this session. */
   blockedProjectServers?: Map<string, ProjectServerBlock>;
+  /** mcpScript is registered. Fixed when Pi loads the adapter, so a session's own config cannot change it. */
+  scriptTool?: boolean;
   /** Runtime-only server grants. Never persisted or restored from session entries. */
   approvedServers?: Map<string, { definition: ServerDefinition; hash: string }>;
   /** Optional active-session sink for approval decisions. */

package/types.ts

@@ -634,8 +634,10 @@ export interface McpSettings {
   directToolResultDetails?: "lean" | "bounded";
   /** Show the advisory when 75 or more direct tools resolve. Defaults to true. */
   warnOnLargeDirectTools?: boolean;
-  /** Register the trusted MCP-only JavaScript scripting tool. Defaults to true; set false to hide it. */
+  /** Register the MCP-only JavaScript scripting tool and its manual skill. Defaults to false. */
   scriptMode?: boolean;
+  /** `"model"` points the model at the mcp-scripting skill from the mcpScript description. Defaults to `"manual"`: `/skill:mcp-scripting` only. */
+  scriptSkill?: "manual" | "model";
   /** Expose MCP resources as tools (default: true). Set to false to disable globally across all servers. */
   exposeResources?: boolean;
   /** Optional Jev (System One) integrations. A valid key enables semantic search; script evaluation remains disabled by default. */
@@ -818,6 +820,11 @@ export interface ServerCacheEntry {
   /** Server-level hints from the aggregated tools/list result. */
   ttlMs?: ListToolsResult["ttlMs"];
   cacheScope?: ListToolsResult["cacheScope"];
+  /**
+   * Result shapes (field names and types, never values) seen from tools without an outputSchema,
+   * keyed by original tool name. Dropped when the server config or that tool's description or input schema changes.
+   */
+  outputShapes?: Record<string, { source: "structuredContent" | "jsonText"; shape: unknown }>;
   cachedAt: number;
 }