pi-mcp-adapter 2.18.0 → 2.19.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.19.0] - 2026-08-03
+
+### Added
+- `mcp_script` now records each search, describe, and call with its input, outcome, and duration in result details; emitted, returned, and console values retain readable Maps, Sets, cycles, functions, symbols, and BigInts. Its docs now lead with the plain JavaScript agents write and position it as the primary MCP multi-call workflow surface.
+- Documented how to hide the bundled `mcp-scripting` Pi skill while keeping the adapter extension installed. Thanks @aryzing for issue #267.
+- Documented Linux revoked-keyring recovery in the OAuth guide and `_meta.ui.visibility` behavior in the MCP UI guide.
+
+### Changed
+- `mcp_script` is now registered by default for trusted JavaScript MCP multi-call workflows, while `mcp` remains the right tool for status, discovery, auth, and single calls. Set `settings.scriptMode` to `false` to hide the tool.
+
+### Fixed
+- `mcp_script` traces now include missing describe attempts, and shared acyclic values no longer render as circular in script output formatting.
+
 ## [2.18.0] - 2026-08-02
 
 ### Added

package/README.md

@@ -263,7 +263,6 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
     "mcpFooterStatus": "full",
     "hostConfigDiscovery": "off",
     "approveTools": ["github_delete_*", "notion_update_*"],
-    "scriptMode": true,
     "oauthDir": ".pi/mcp-oauth",
     "trace": {
       "enabled": true,
@@ -289,7 +288,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `mcpServers.<name>.oauth.authorizationParams` | Extra authorization URL parameters for provider-specific OAuth extensions. Flow-owned parameters such as `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, and `resource` cannot be overridden. |
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
 | `freezeDirectTools` | Keep direct-tool registration stable after the initial sync so automatic reconnects and list-change notifications do not rebuild the system prompt. Use `mcp({ connect: "server" })` or `/mcp reconnect <server>` to refresh deliberately. Default: false. |
-| `scriptMode` | Register the MCP-only `mcp_script` plain-JavaScript tool (default: false). |
+| `scriptMode` | Register the MCP-only `mcp_script` plain-JavaScript tool (default: true). Set to `false` to hide it. |
 | `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
 | `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
 | `sampling` | Allow MCP servers to sample through Pi models, honoring `modelPreferences.hints` before current/default fallback (default: true when UI approval is available). |
@@ -340,17 +339,39 @@ Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — t
 
 ### MCP Scripting
 
-Set `settings.scriptMode` to `true` to register `mcp_script({ code, timeoutMs? })`, a trusted agent-authored JavaScript layer for orchestrating MCP tools. See the bundled `mcp-scripting` skill for the complete workflow guide. The canonical API is ordinary JavaScript with `await tools.search({ query, server?, limit?, offset? })`, `await tools.describe({ path })`, `tools.call(path, args)`, direct flat calls, `emit(value)`, and a captured `console`. Use ordinary JavaScript loops and Promise utilities for composition; fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided. MCP calls return `{ ok: true, data }` or `{ ok: false, error: { code, message } }`, so a failed call does not stop the rest of the script. Result details include a concise `calls` trace with each invoked path and outcome. Emitted values and console output appear before the script's final return value, and the combined result uses the normal MCP output guard. The default timeout is 30 seconds; each script runs in a worker thread that is terminated at the deadline, including for infinite loops.
+For multi-call MCP work, write ordinary JavaScript: discover, inspect, call, loop, filter, chain, or fan out, then return one result. Run that code with the default-on `mcp_script` tool. For a single MCP call, search, describe, status check, or auth action, use `mcp` instead. Set `settings.scriptMode` to `false` to hide the scripting tool.
+
+The bundled `mcp-scripting` skill is a separate Pi package resource. To hide that skill while keeping the adapter extension installed, replace the package entry in Pi settings with the object form and disable package skills:
+
+```json
+{
+  "packages": [
+    { "source": "npm:pi-mcp-adapter", "skills": [] }
+  ]
+}
+```
+
+Preserve any version pin in `source` if your existing package entry has one. You can also disable package resources through `pi config`.
+
+For example, this is the JavaScript passed as the `code` argument to `mcp_script`:
 
 ```js
-const first = await tools.github_search_issues({ query: "is:open label:bug" });
-if (!first.ok) return first;
-const selected = first.data.content.filter((item) => item.type === "text");
-emit({ searched: true });
-return selected;
+const { items } = await tools.search({ query: "search issues", server: "github" });
+const candidate = items[0];
+if (!candidate) 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" });
+if (!result.ok) return result;
+emit({ tool: details.path, completed: true });
+return result.data;
 ```
 
-For a tool-restricted subagent, enable script mode in the adapter configuration, then launch the child Pi with its tool allowlist set to `["mcp_script"]`. Have the parent discover MCP tool names with `mcp({ search: "..." })` and include the relevant prefixed names in the child's task; the child can then loop, filter, and chain those MCP calls without filesystem, shell, or edit tools. The adapter's ordinary lazy connection, authentication, output guard, abort handling, and approval gates still apply to every call.
+See the bundled `mcp-scripting` skill for the complete workflow guide. The API is `await tools.search({ query, server?, limit?, offset? })`, `await tools.describe({ path })`, `tools.call(path, args)`, direct flat calls, `emit(value)`, and a captured `console`. Use ordinary JavaScript loops and Promise utilities for composition; fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided. MCP calls return `{ ok: true, data }` or `{ ok: false, error: { code, message } }`, so a failed call does not stop the rest of the script. Result details include a concise `calls` trace with each operation, its path or query, outcome, and duration. Emitted values and console output appear before the script's final return value, and the combined result uses the normal MCP output guard. The default timeout is 30 seconds; each script runs in a worker thread that is terminated at the deadline, including for infinite loops.
+
+For a tool-restricted subagent, launch the child Pi with its tool allowlist set to `["mcp_script"]`. Have the parent discover MCP tool names with `mcp({ search: "..." })` and include the relevant prefixed names in the child's task; the child can then loop, filter, and chain those MCP calls without filesystem, shell, or edit tools. The adapter's ordinary lazy connection, authentication, output guard, abort handling, and approval gates still apply to every call.
 
 `mcp_script` is a trusted agent-authored MCP scripting layer, not an isolation boundary. If you need isolation, run Pi in an isolated environment. It is distinct from Pi's code-mode skill: Pi's skill batches general Pi tools, while `mcp_script` exposes MCP calls only and can be the child's sole tool.
 
@@ -510,6 +531,7 @@ Returns accumulated messages from UI sessions. Each message includes `type`, `se
 **Technical notes:**
 
 - Tool consent gates whether UIs can call MCP tools (never/once-per-server/always)
+- `_meta.ui.visibility` controls audience: tools marked app-only stay out of the model tool list, and tools marked model-only cannot be called from the UI iframe.
 - Works with both stdio and HTTP MCP servers
 - Uses a local 408KB AppBridge bundle (MCP SDK + Zod) for browser↔server communication
 - Enforces CSP from standard `_meta.ui.csp` and OpenAI-compatible `_meta["openai/widgetCSP"]` metadata in the response header while preserving provider HTML.

package/direct-tools.ts

@@ -207,7 +207,7 @@ export function buildProxyDescription(
   directSpecs: DirectToolSpec[],
 ): string {
   const prefix = config.settings?.toolPrefix ?? "server";
-  let desc = `MCP gateway - connect to MCP servers and call their tools. Non-MCP Pi tools should be called directly, not through mcp.\n`;
+  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`;
 
   const directByServer = new Map<string, number>();
   for (const spec of directSpecs) {

package/index.ts

@@ -607,12 +607,12 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     },
   });
 
-  if (earlyConfig.settings?.scriptMode === true) {
+  if (earlyConfig.settings?.scriptMode !== false) {
     (pi.registerTool as (tool: unknown) => unknown)({
       name: "mcp_script",
       label: "MCP Script",
-      description: "Run a trusted JavaScript MCP script to orchestrate MCP tools. 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. Load the mcp-scripting skill for the full workflow guide.",
-      promptSnippet: "Run a JavaScript MCP script to chain and filter tool calls in one request",
+      description: "Run trusted JavaScript that makes multiple MCP tool calls in one request — loop, filter, chain, or fan out between calls. For a single MCP call, search, describe, status check, or auth action, use the mcp tool instead. Discover with await tools.search({ query }) — resolves to { items: [{ path, name, server, description? }], total, hasMore, nextOffset }, not an { ok, data } envelope. Inspect with await tools.describe({ path }) — resolves to the tool descriptor with inputTypeScript, 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. Load the mcp-scripting skill for the full workflow guide.",
+      promptSnippet: "Batch multiple MCP tool calls in one JavaScript request (loop, filter, chain)",
       parameters: Type.Object({
         code: Type.String({ description: "Trusted JavaScript MCP script. Use tools.<prefixedToolName>(args) and emit(value)." }),
         // Raw JSON schema: host TypeBox shims may omit Type.Number (see index-lifecycle shim test).
@@ -658,7 +658,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       name: "mcp",
       label: "MCP",
       description,
-      promptSnippet: "MCP gateway - connect to MCP servers and call their tools",
+      promptSnippet: "MCP gateway — status, search, describe, auth, and single MCP tool calls",
       renderCall: renderMcpProxyToolCall,
       parameters: Type.Object({
         tool: Type.Optional(Type.String({ description: "Tool name to call (e.g., 'xcodebuild_list_sims')" })),

package/mcp-code.ts

@@ -1,4 +1,5 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import { formatWithOptions } from "node:util";
 import { Worker } from "node:worker_threads";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { executeCall } from "./proxy-modes.ts";
@@ -30,17 +31,29 @@ type WorkerMessage =
 
 type WorkerResultMessage = { type: "result"; id: number; envelope: unknown };
 
+function needsInspectableFormatting(value: unknown, stack = new WeakSet<object>()): boolean {
+  if (value === undefined || typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") return true;
+  if (typeof value !== "object" || value === null) return false;
+  if (stack.has(value)) return true;
+  if (value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) return true;
+  stack.add(value);
+  try {
+    return Object.values(value).some((entry) => needsInspectableFormatting(entry, stack));
+  } finally {
+    stack.delete(value);
+  }
+}
+
 function formatValue(value: unknown): string {
   if (typeof value === "string") return value;
-  if (value === undefined) return "undefined";
   try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    try {
-      return String(value);
-    } catch {
-      return "[unserializable value]";
+    if (!needsInspectableFormatting(value)) {
+      const json = JSON.stringify(value, null, 2);
+      if (json !== undefined) return json;
     }
+    return formatWithOptions({ colors: false, depth: 6 }, value);
+  } catch {
+    return "[unserializable value]";
   }
 }
 
@@ -106,25 +119,45 @@ export async function runMcpScript(
   const timeoutController = new AbortController();
   const callSignal = combineAbortSignals(externalSignal, timeoutController.signal);
 
-  type ScriptCall = { path: string; ok: true } | { path: string; ok: false; error: string };
-  const calls: ScriptCall[] = [];
-  let callsSnapshot: ScriptCall[] | undefined;
+  type ScriptOperation =
+    | { operation: "call"; path: string; ok: true; durationMs: number }
+    | { operation: "call"; path: string; ok: false; error: string; durationMs: number }
+    | { operation: "search"; query: string; ok: true; durationMs: number }
+    | { operation: "search"; query: string; ok: false; error: string; durationMs: number }
+    | { operation: "describe"; path: string; ok: true; durationMs: number }
+    | { operation: "describe"; path: string; ok: false; error: string; durationMs: number };
+  type TrackedScriptOperation = ScriptOperation & { startedAt: number };
+  const calls: TrackedScriptOperation[] = [];
+  const snapshotCalls = (): ScriptOperation[] => calls.map(({ startedAt, ...operation }) => ({
+    ...operation,
+    durationMs: "error" in operation && operation.error === "incomplete"
+      ? Math.max(0, Date.now() - startedAt)
+      : operation.durationMs,
+  }));
+  let callsSnapshot: ScriptOperation[] | undefined;
   const callTool = async (path: string, args?: Record<string, unknown>) => {
     // Record before dispatch so calls still in flight at timeout/abort appear in the trace.
-    const index = calls.push({ path, ok: false, error: "incomplete" }) - 1;
+    const startedAt = Date.now();
+    const index = calls.push({ operation: "call", path, ok: false, error: "incomplete", durationMs: 0, startedAt }) - 1;
     const result = await executeCall(state, path, args, undefined, getPiTools, callSignal);
     const details = result.details;
     if (details.error !== undefined) {
-      const message = typeof details.message === "string"
-        ? details.message
-        : textFromContent(result.content);
-      calls[index] = { path, ok: false, error: String(details.error) };
+      const errorCode = String(details.error);
+      const suggestions = Array.isArray(details.suggestions)
+        ? details.suggestions.filter((suggestion): suggestion is string => typeof suggestion === "string")
+        : [];
+      const message = errorCode === "tool_not_found"
+        ? `Tool "${path}" not found. Use await tools.search({ query: "..." }) inside mcp_script.${suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : ""}`
+        : typeof details.message === "string"
+          ? details.message
+          : textFromContent(result.content);
+      calls[index] = { operation: "call", path, ok: false, error: errorCode, durationMs: Date.now() - startedAt, startedAt };
       return {
         ok: false as const,
-        error: { code: String(details.error), message },
+        error: { code: errorCode, message },
       };
     }
-    calls[index] = { path, ok: true };
+    calls[index] = { operation: "call", path, ok: true, durationMs: Date.now() - startedAt, startedAt };
     return {
       ok: true as const,
       data: details.mcpResult !== undefined ? details.mcpResult : textFromContent(result.content),
@@ -132,48 +165,72 @@ export async function runMcpScript(
   };
 
   const searchTools = (input?: SearchInput) => {
-    if (typeof input?.query !== "string" || input.query.trim() === "") {
-      return { items: [], total: 0, hasMore: false, nextOffset: null };
+    const startedAt = Date.now();
+    const query = typeof input?.query === "string" ? input.query : "";
+    let error: unknown;
+    try {
+      if (query.trim() === "") {
+        return { items: [], total: 0, hasMore: false, nextOffset: null };
+      }
+      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 page = paginate(rankToolMatches(state, query, server), offset, limit);
+      return {
+        ...page,
+        items: page.items.map(({ server: matchServer, tool, score }) => ({
+          path: tool.name,
+          name: tool.originalName,
+          server: matchServer,
+          ...(tool.description ? { description: tool.description } : {}),
+          score,
+        })),
+      };
+    } catch (caught) {
+      error = caught;
+      throw caught;
+    } finally {
+      calls.push(error === undefined
+        ? { operation: "search", query, ok: true, durationMs: Date.now() - startedAt, startedAt }
+        : { operation: "search", query, ok: false, error: error instanceof Error ? error.message : String(error), durationMs: Date.now() - startedAt, startedAt });
     }
-    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 page = paginate(rankToolMatches(state, input.query, server), offset, limit);
-    return {
-      ...page,
-      items: page.items.map(({ server: matchServer, tool, score }) => ({
-        path: tool.name,
-        name: tool.originalName,
-        server: matchServer,
-        ...(tool.description ? { description: tool.description } : {}),
-        score,
-      })),
-    };
   };
 
   const describeTool = (input?: DescribeInput) => {
+    const startedAt = Date.now();
     const path = typeof input?.path === "string" ? input.path : "";
-    for (const [server, metadata] of state.toolMetadata) {
-      const tool = findToolByName(metadata, path);
-      if (!tool) continue;
-      const inputTypeScript = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
+    let error: unknown;
+    try {
+      for (const [server, metadata] of state.toolMetadata) {
+        const tool = findToolByName(metadata, path);
+        if (!tool) continue;
+        const inputTypeScript = tool.inputSchema ? renderTsShape(tool.inputSchema) : null;
+        return {
+          path: tool.name,
+          name: tool.originalName,
+          server,
+          ...(tool.description ? { description: tool.description } : {}),
+          ...(inputTypeScript ? { inputTypeScript } : {}),
+        };
+      }
+      const suggestions = path ? rankSuggestions(state, path, 5) : [];
+      error = "tool_not_found";
       return {
-        path: tool.name,
-        name: tool.originalName,
-        server,
-        ...(tool.description ? { description: tool.description } : {}),
-        ...(inputTypeScript ? { inputTypeScript } : {}),
+        path,
+        error: {
+          code: "tool_not_found",
+          message: `Tool not found: ${path}`,
+          suggestions,
+        },
       };
+    } catch (caught) {
+      error = caught;
+      throw caught;
+    } finally {
+      calls.push(error === undefined
+        ? { operation: "describe", path, ok: true, durationMs: Date.now() - startedAt, startedAt }
+        : { operation: "describe", path, ok: false, error: error instanceof Error ? error.message : String(error), durationMs: Date.now() - startedAt, startedAt });
     }
-    const suggestions = path ? rankSuggestions(state, path, 5) : [];
-    return {
-      path,
-      error: {
-        code: "tool_not_found",
-        message: `Tool not found: ${path}`,
-        suggestions,
-      },
-    };
   };
 
   let worker: Worker | undefined;
@@ -234,7 +291,7 @@ export async function runMcpScript(
     const timeoutError = new McpScriptTimeoutError(resolvedTimeoutMs);
     const timeout = new Promise<never>((_resolve, reject) => {
       timer = setTimeout(() => {
-        callsSnapshot = [...calls];
+        callsSnapshot = snapshotCalls();
         timeoutController.abort(timeoutError);
         void activeWorker.terminate();
         reject(timeoutError);
@@ -243,7 +300,7 @@ export async function runMcpScript(
     const aborted = externalSignal
       ? new Promise<never>((_resolve, reject) => {
           const onAbort = () => {
-            callsSnapshot = [...calls];
+            callsSnapshot = snapshotCalls();
             void activeWorker.terminate();
             reject(abortReasonError(externalSignal.reason));
           };
@@ -270,7 +327,7 @@ export async function runMcpScript(
     removeAbortListener();
     // "incomplete" means the call had not settled when the script finished
     // (deadline, abort, or early return). Snapshot before aborting stragglers.
-    callsSnapshot ??= [...calls];
+    callsSnapshot ??= snapshotCalls();
     // A script may finish without awaiting every call; abort leftovers so
     // parent-side dispatches do not outlive the script.
     timeoutController.abort(new Error("mcp_script finished"));
@@ -288,7 +345,7 @@ export async function runMcpScript(
       mode: "script",
       ...(errorCode ? { error: errorCode, message: errorMessage } : {}),
       timeoutMs: resolvedTimeoutMs,
-      ...((callsSnapshot ?? calls).length > 0 ? { calls: [...(callsSnapshot ?? calls)] } : {}),
+      ...(callsSnapshot.length > 0 ? { calls: callsSnapshot } : {}),
       ...guardedMcpDetails(guarded),
     },
   };

package/mcp-script-worker.mjs

@@ -5,17 +5,30 @@ import vm from "node:vm";
 const TOOLS_ENUMERATION_ERROR = "tools is not enumerable — use tools.search({ query })";
 const RESERVED_TOOL_PROPS = new Set(["then", "catch", "finally", "toJSON", "toString", "valueOf"]);
 
+// Keep this formatting logic in sync with mcp-code.ts; the standalone worker cannot import the TypeScript host module.
+function needsInspectableFormatting(value, stack = new WeakSet()) {
+  if (value === undefined || typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") return true;
+  if (typeof value !== "object" || value === null) return false;
+  if (stack.has(value)) return true;
+  if (value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) return true;
+  stack.add(value);
+  try {
+    return Object.values(value).some((entry) => needsInspectableFormatting(entry, stack));
+  } finally {
+    stack.delete(value);
+  }
+}
+
 function formatValue(value) {
   if (typeof value === "string") return value;
-  if (value === undefined) return "undefined";
   try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    try {
-      return String(value);
-    } catch {
-      return "[unserializable value]";
+    if (!needsInspectableFormatting(value)) {
+      const json = JSON.stringify(value, null, 2);
+      if (json !== undefined) return json;
     }
+    return formatWithOptions({ colors: false, depth: 6 }, value);
+  } catch {
+    return "[unserializable value]";
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",

package/skills/mcp-scripting/SKILL.md

@@ -5,13 +5,9 @@ description: Write mcp_script JavaScript for discovering, inspecting, and callin
 
 # MCP scripting
 
-Use `mcp_script` when a task needs to discover, filter, or orchestrate MCP tools in one JavaScript request.
+For multi-call MCP work, write ordinary JavaScript with loops, filtering, chaining, fan-out, or other logic between calls. Run that source with `mcp_script`; it is the primary MCP orchestration surface. For a single MCP search, describe, status check, auth action, or tool call, use `mcp` instead.
 
-## 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)`.
+Write the source naturally, then pass it as `mcp_script`'s `code` argument:
 
 ```js
 const { items } = await tools.search({ query: "search issues", server: "github" });
@@ -27,10 +23,16 @@ emit({ tool: details.path, completed: true });
 return result.data;
 ```
 
+## 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)`.
+
 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.
 
 `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)`.
 
-`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, output guarding, and approval gates. Result details contain a concise `calls` trace with each path and outcome.
+`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, output guarding, 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.
 
 Use plain JavaScript loops and Promise utilities for composition. Fluent helpers such as `tools.find(...).one()`, `tools.parallel(...)`, and `tools.retry(...)` are not provided.

package/types.ts

@@ -433,7 +433,7 @@ export interface McpSettings {
   idleTimeout?: number; // minutes, default 10, 0 to disable
   requestTimeoutMs?: number; // milliseconds, overrides the SDK request timeout when > 0
   directTools?: boolean;
-  /** Register the trusted MCP-only JavaScript scripting tool. Defaults to false. */
+  /** Register the trusted MCP-only JavaScript scripting tool. Defaults to true; set false to hide it. */
   scriptMode?: boolean;
   /** Default approval gate for matching tools/resources; per-server settings override it. */
   approveTools?: boolean | string[];