pi-mcp-adapter 2.17.0 → 2.19.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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
+- Added `settings.freezeDirectTools` to keep direct MCP tool registration stable after initial sync while preserving explicit reconnect refreshes. Thanks @ddfourtwo for PR #254.
+- Added best-effort Linux OAuth credential recovery when Pi inherits a revoked session keyring, allowing explicit re-authentication through a fresh `keyctl` session helper. Thanks @anthod0 for issue #248 and the validation prototype.
+- Ranked, paginated MCP tool search: best matches come first in a short page of 12 instead of an unranked dump of every match with full schemas, so the model stops guessing and each search costs a fraction of the tokens. Misses on describe/call now return top-5 "Did you mean" suggestions, letting the model self-correct a typo or missing prefix in the same turn instead of burning a round trip.
+- Optional `approveTools` patterns (global and per-server) add the missing middle tier between "tool runs instantly" and "tool hidden entirely": flag risky tools and Pi asks before running them — Allow once / Allow for session / Deny — across proxy, direct, resource, and iframe-originated calls. Safe tools keep full speed; a deny is a normal result the model adapts to, not a crash.
+- Opt-in `mcp_script` trusted JavaScript MCP scripting turns N-step jobs into one call: loop, filter, and chain tools for tool-restricted subagents where every round trip costs child context. Scripts discover tools with `await tools.search({ query })`, inspect exact shapes with `await tools.describe({ path })`, and call them with `tools.call(path, args)` — no more guessing names from outside the script. A runaway script can never freeze Pi itself: scripts run isolated from the main process and are force-stopped at their time limit, even if stuck in an infinite loop. Result details include a `calls` trace of every invoked path and outcome, and a bundled `mcp-scripting` skill teaches the full workflow on demand. Every scripted call still goes through auth, output guarding, and the approval gate.
+- HTTP connection failures are now probe-classified into a plain-language diagnosis (for example "endpoint returned HTML (200) — this URL does not appear to speak MCP") instead of an opaque "fetch failed", so setup mistakes are fixed in seconds. Healthy connections are never probed.
+- Tool parameters render as compact TypeScript shapes (`{ query: string; limit?: number }`) in describe and search, replacing multi-line schema dumps — the model reads less and acts sooner, with the previous formatting kept as a fallback for exotic schemas.
+- `/mcp setup` gained curated one-click presets (DeepWiki, Context7, Notion, GitHub, Chrome DevTools): pick, preview the exact config write, confirm — new servers in under a minute with no hand-typed setup.
+
+The ranked search scoring, did-you-mean suggestions, approval patterns, endpoint shape probe, TypeScript-shaped schemas, and codemode design in this release are adapted from [Executor](https://github.com/UsefulSoftwareCo/executor) by Rhys Sullivan (@RhysSullivan). Thanks Rhys.
+
+### Fixed
+- Brought MCP Apps UI hosting in line with the current spec: provider HTML now runs in a real sandbox, gets a restrictive default CSP even when the resource omits one, and `_meta.ui.visibility` is honored so app-only tools stay out of the model tool list while model-only tools cannot be called from the UI.
+- MCP Apps UI sessions are now easier to open from Moshi and remote terminals: the local UI server uses Moshi-discoverable low ports, answers preview discovery probes, serves a loopback-only landing shell, prints Moshi/SSH access hints for remote sessions, and fits the host shell better in narrow in-app browsers. UI-submitted model context is now captured as a bounded handoff, wakes the agent like prompts and intents, and remains available through `mcp({ action: "ui-messages" })` after the UI closes.
+
 ## [2.17.0] - 2026-07-31
 
 ### Added

package/README.md

@@ -32,7 +32,7 @@ The adapter reads standard MCP files automatically. No extra setup needed if you
 |---------------------|--------------|
 | `.mcp.json` or `~/.config/mcp/mcp.json` | Pi uses it immediately. The first time you open `/mcp`, you'll see a short heads-up explaining which file Pi detected and that Pi only writes adapter-specific overrides to its own files. |
 | Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run `/mcp setup` to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
-| Nothing configured yet | Run `/mcp setup` to scaffold a minimal `.mcp.json`, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
+| Nothing configured yet | Run `/mcp setup` to scaffold a minimal `.mcp.json`, add a curated known server, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
 
 If you prefer the terminal, you can also run `pi-mcp-adapter init` after install to scan for host-specific configs and add missing compatibility imports to the Pi agent dir (`~/.pi/agent/mcp.json` by default, or `$PI_CODING_AGENT_DIR/mcp.json` when set).
 
@@ -222,7 +222,9 @@ The adapter owns only its client socket and closes that connection when the Pi r
 
 ### Remote/headless OAuth
 
-If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable:
+If Pi is running on a remote server and cannot open a local browser, start OAuth through the proxy tool. Persistent OAuth still requires an available OS credential store; on headless Linux that usually means an unlocked Secret Service/libsecret keyring. The adapter fails closed instead of falling back to plaintext credentials when the secure store is unavailable.
+
+On Linux, if credential access fails because Pi inherited a revoked session keyring, the adapter uses a best-effort recovery path through `keyctl session - node <packaged helper>` so explicit re-authentication can write fresh credentials without killing a long-lived tmux server. This path requires `keyctl` and `node` on `PATH`; missing, locked, or otherwise unavailable credential stores still fail closed.
 
 ```js
 mcp({ action: "auth-start", server: "linear-server" })
@@ -260,6 +262,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
     "showStatusIcon": true,
     "mcpFooterStatus": "full",
     "hostConfigDiscovery": "off",
+    "approveTools": ["github_delete_*", "notion_update_*"],
     "oauthDir": ".pi/mcp-oauth",
     "trace": {
       "enabled": true,
@@ -280,9 +283,12 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `showStatusIcon` | Show the plug icon in MCP status and connection text (default: `true`). Set to `false` for plain `MCP: ...` text. |
 | `mcpFooterStatus` | MCP footer verbosity: `"full"` (default), `"compact"` for `MCP connected/enabled`, or `"off"` to clear the persistent footer status. `/mcp status` remains available. |
 | `hostConfigDiscovery` | Host-specific config policy: `"off"` (default), `"prompt"` (detect/report only), or `"on"` (explicitly load detected host configs as the lowest-precedence fallback) |
+| `approveTools` | `true` to require approval before every MCP tool call, or an array of glob patterns such as `["github_delete_*", "notion_update_*"]`. Per-server `approveTools` overrides this. |
 | `oauthDir` | Legacy OAuth `tokens.json` import directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. Persistent OAuth credentials are stored in the OS credential store, not this directory. |
 | `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: 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). |
@@ -291,7 +297,25 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `outputGuard` | Guard oversized MCP output: `true` (default), `false`, or `{ maxBytes, maxLines, detailsMaxBytes }`. See [Output Guard](#output-guard). |
 | `trace` | Opt-in metadata-only protocol tracing. Set `{ enabled: true }` globally or `trace: true` on a server. The per-session JSONL file defaults to `.pi/mcp-traces/`; `file`, `maxBytes` (default 262144), and `maxEvents` (default 10000) can be set. Raw MCP payloads, prompts, tool arguments/results, auth data, and URLs are never persisted. |
 
-Per-server `idleTimeout` and `requestTimeoutMs` override the global settings. `debug` remains stderr display and is unrelated to protocol tracing.
+Per-server `idleTimeout`, `requestTimeoutMs`, and `approveTools` override the global settings. `debug` remains stderr display and is unrelated to protocol tracing.
+
+### Tool Approval
+
+Use `approveTools` when a tool should stay visible but not run without confirmation. This is useful for destructive or high-cost actions where hiding the tool would make planning harder, but running it silently is too risky.
+
+```json
+{
+  "settings": {
+    "approveTools": ["github_delete_*", "notion_update_*"]
+  },
+  "mcpServers": {
+    "github": { "approveTools": ["delete_*", "merge_pull_request"] },
+    "docs": { "approveTools": false }
+  }
+}
+```
+
+When a matching tool is called from the proxy tool, a direct MCP tool, a resource call, or an MCP UI iframe, Pi asks: **Allow once**, **Allow for session**, or **Deny**. Session approvals are kept in memory only. In headless sessions, matching calls fail closed with an `approval_required` result instead of running. `excludeTools` still removes tools entirely; `approveTools` only gates visible tools at call time.
 
 ### Output Guard
 
@@ -313,6 +337,44 @@ Tune the limits with the object form:
 
 Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — to disable the guard and restore raw output behavior. Saved temp files are created with mode `0600` under the system temp directory and are not cleaned up automatically; note that spilled MCP output may contain sensitive data.
 
+### MCP Scripting
+
+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 { 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;
+```
+
+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.
+
 ### MCP Prompts
 
 MCP servers can advertise prompt templates alongside tools and resources. The adapter registers cached prompt definitions as Pi slash commands under `/mcp__<server>__<prompt>`, and refreshes their metadata whenever a server connects. Arguments support positional and `key=value` forms with quoting; required arguments are validated before `prompts/get` is called.
@@ -415,11 +477,13 @@ Each direct tool costs ~150-300 tokens in the system prompt (name + description
 
 Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only while the cache populates, then the extension hot-loads the refreshed direct tools into the current session. Servers that advertise MCP list-change notifications refresh the current session when their tool or resource list changes. On Pi versions that expose `pi.unregisterTool()`, stale direct tools are removed from the registry during refresh; older Pi versions still deactivate them from the active tool set. To force a refresh: `/mcp reconnect <server>`.
 
+If prompt-cache stability matters more than automatic direct-tool hot-loading, set `settings.freezeDirectTools` to `true`. The initial direct-tool sync still runs, but later automatic reconnects, lazy-connects, and list-change notifications keep the registered tool surface unchanged. Deliberate refreshes through `mcp({ connect: "server" })` or `/mcp reconnect <server>` still update direct tools.
+
 When you change direct-tool toggles in `/mcp`, the extension updates direct tool registration in the current session. Broader setup writes from `/mcp setup` still use Pi's normal reload flow because they can add or restructure MCP config files.
 
 **Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers and toggle tools between direct and proxy from the same overlay. For OAuth, press Enter on a server that needs auth or `ctrl+a` on any OAuth server.
 
-**Guided first-run setup:** Run `/mcp setup` to inspect detected shared MCP files, adopt compatibility imports from other hosts, open discovered config paths, preview exact before/after file diffs for writes, scaffold a minimal project `.mcp.json`, or quick-add RepoPrompt into a standard/shared MCP file.
+**Guided first-run setup:** Run `/mcp setup` to inspect detected shared MCP files, adopt compatibility imports from other hosts, open discovered config paths, preview exact before/after file diffs for writes, scaffold a minimal project `.mcp.json`, add a curated known server (DeepWiki, Context7, Notion, GitHub, or Chrome DevTools), or quick-add RepoPrompt into a standard/shared MCP file.
 
 **Subagent integration:** If you use the subagent extension, agents can request direct MCP tools in their frontmatter with `mcp:server-name` syntax. See the subagent README for details.
 
@@ -467,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.
@@ -508,7 +573,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 |------|---------|
 | Status | `mcp({ })` |
 | List server | `mcp({ server: "name" })` |
-| Search | `mcp({ search: "screenshot navigate" })` |
+| Search | `mcp({ search: "screenshot navigate", limit: 12, offset: 0 })` |
 | Describe | `mcp({ describe: "tool_name" })` |
 | Instructions | `mcp({ instructions: "name" })` |
 | Call | `mcp({ tool: "...", args: { key: "value" } })` |
@@ -521,9 +586,13 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 
 MCP proxy and direct-tool results render compactly by default: long text shows the first three terminal-wrapped lines plus a `Ctrl+O to expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
 
-Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are OR'd.
+Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are ranked by weighted matches across name, server, and description, then returned one page at a time (`limit` defaults to 12). Use `details.nextOffset` for the next page. Regex search is still available with `regex: true`, but regex results are paginated without ranking.
+
+Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_library_id` finds `context7_resolve-library-id`. When `describe` or `tool` cannot resolve a name, the result includes top suggestions so the agent can correct a typo or missing prefix in the same turn.
+
+When `includeSchemas` is enabled, search and describe render common JSON Schema parameters as compact TypeScript shapes like `{ query: string; limit?: number; }`, with the older schema formatter retained as a fallback for unsupported schemas.
 
-Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_library_id` finds `context7_resolve-library-id`.
+For HTTP servers, failed connects run a one-request shape probe that can turn opaque transport errors into setup hints such as `endpoint returned HTML (200) — this URL does not appear to speak MCP`. Healthy connections are not probed.
 
 Servers that provide usage guidance via the MCP `instructions` field surface it at three levels: a truncated head in the `mcp` proxy tool description itself (so the model sees it without any call), a longer preview at the end of `mcp({ server: "name" })` listings, and the full text via `mcp({ instructions: "name" })`. Instructions are captured at connect time and cached alongside tool metadata, so they stay available without a live connection.
 
@@ -532,7 +601,7 @@ Servers that provide usage guidance via the MCP `instructions` field surface it
 | Command | What it does |
 |---------|--------------|
 | `/mcp` | Interactive panel and first-run onboarding surface |
-| `/mcp setup` | Guided setup for imports, a minimal `.mcp.json`, RepoPrompt quick-add, and config-path inspection |
+| `/mcp setup` | Guided setup for imports, a minimal `.mcp.json`, curated known servers, RepoPrompt quick-add, and config-path inspection |
 | `/mcp tools` | List all tools |
 | `/mcp prompts` | List all MCP prompts registered as slash commands |
 | `/mcp reconnect` | Reconnect all servers |

package/commands.ts

@@ -4,6 +4,8 @@ import { isServerDisabled, type McpAuthResult, type McpConfig, type McpPanelCall
 import {
   ensureCompatibilityImports,
   getMcpDiscoverySummary,
+  getProjectConfigPath,
+  type KnownServerPreset,
   getServerProvenance,
   previewCompatibilityImports,
   previewSharedServerEntry,
@@ -395,6 +397,7 @@ export async function openMcpSetup(
       if (!repoPrompt.entry || !repoPrompt.targetPath || !repoPrompt.serverName) return null;
       return previewSharedServerEntry(repoPrompt.targetPath, repoPrompt.serverName, repoPrompt.entry);
     },
+    previewKnownServer: (preset: KnownServerPreset) => previewSharedServerEntry(getProjectConfigPath(ctx.cwd), preset.id, preset.entry),
     adoptImports: async (imports: ImportKind[]) => {
       const result = ensureCompatibilityImports(imports, configOverridePath);
       if (result.added.length > 0) configChanged = true;
@@ -414,6 +417,11 @@ export async function openMcpSetup(
       configChanged = true;
       return { path, serverName: repoPrompt.serverName };
     },
+    addKnownServer: async (preset: KnownServerPreset) => {
+      const path = writeSharedServerEntry(getProjectConfigPath(ctx.cwd), preset.id, preset.entry);
+      configChanged = true;
+      return { path, serverName: preset.name };
+    },
     openPath: async (targetPath: string) => {
       await openPath(pi, targetPath);
     },

package/config.ts

@@ -20,6 +20,46 @@ const REPOPROMPT_BINARY_CANDIDATES = [
   "/Applications/Repo Prompt.app/Contents/MacOS/repoprompt-mcp",
 ];
 
+export interface KnownServerPreset {
+  id: string;
+  name: string;
+  summary: string;
+  entry: ServerEntry;
+}
+
+export const KNOWN_SERVER_PRESETS: readonly KnownServerPreset[] = [
+  {
+    id: "deepwiki",
+    name: "DeepWiki",
+    summary: "Ask questions about public GitHub repositories.",
+    entry: { url: "https://mcp.deepwiki.com/mcp" },
+  },
+  {
+    id: "context7",
+    name: "Context7",
+    summary: "Look up current library documentation and examples.",
+    entry: { url: "https://mcp.context7.com/mcp" },
+  },
+  {
+    id: "notion",
+    name: "Notion",
+    summary: "Search and work with your Notion workspace.",
+    entry: { url: "https://mcp.notion.com/mcp", auth: "oauth" },
+  },
+  {
+    id: "github",
+    name: "GitHub",
+    summary: "Work with GitHub through your Copilot account.",
+    entry: { url: "https://api.githubcopilot.com/mcp", auth: "oauth" },
+  },
+  {
+    id: "chrome-devtools",
+    name: "Chrome DevTools",
+    summary: "Inspect and automate a local Chrome browser.",
+    entry: { command: "npx", args: ["-y", "chrome-devtools-mcp@latest"] },
+  },
+];
+
 const IMPORT_PATHS: Record<ImportKind, string[]> = {
   cursor: [join(homedir(), ".cursor", "mcp.json")],
   "claude-code": [

package/direct-tools.ts

@@ -17,6 +17,7 @@ import { authenticate, supportsOAuth } from "./mcp-auth-flow.ts";
 import { formatAuthRequiredMessage, resolveServerUrl, truncateAtWord } from "./utils.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
+import { ensureToolCallApproved } from "./tool-approval.ts";
 
 const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 const INSTRUCTIONS_SNIPPET_LENGTH = 150;
@@ -206,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) {
@@ -372,6 +373,30 @@ export function createDirectToolExecutor(
       };
     }
 
+    const approval = await ensureToolCallApproved(state, spec.serverName, {
+      name: spec.prefixedName,
+      originalName: spec.originalName,
+      description: spec.description,
+      inputSchema: spec.inputSchema,
+      resourceUri: spec.resourceUri,
+      uiResourceUri: spec.uiResourceUri,
+      uiStreamMode: spec.uiStreamMode,
+    }, params, ownedSignal);
+    if (approval.ok === false) {
+      const denied = approval.reason === "denied";
+      const message = denied
+        ? `The user declined approval to run MCP tool "${spec.originalName}" on server "${spec.serverName}".`
+        : `MCP tool "${spec.originalName}" on server "${spec.serverName}" is approval-gated and requires an interactive session.`;
+      return {
+        content: [{ type: "text" as const, text: message }],
+        details: {
+          error: denied ? "approval_denied" : "approval_required",
+          server: spec.serverName,
+          tool: spec.originalName,
+        },
+      };
+    }
+
     let uiSession: UiSessionRuntime | null = null;
     const requestOptions = state.manager.getRequestOptions?.(spec.serverName, ownedSignal) ?? (ownedSignal ? { signal: ownedSignal } : undefined);
 

package/host-html-template.ts

@@ -63,8 +63,8 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     }
     * { box-sizing: border-box; }
     html, body { margin: 0; padding: 0; height: 100%; font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: var(--bg); color: var(--text); }
-    body { display: flex; flex-direction: column; min-height: 100vh; }
-    header { background: var(--surface); border-bottom: 1px solid var(--border); padding: 10px 14px; display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+    body { display: flex; flex-direction: column; min-height: 100vh; min-height: 100dvh; }
+    header { background: var(--surface); border-bottom: 1px solid var(--border); padding: calc(10px + env(safe-area-inset-top, 0px)) calc(14px + env(safe-area-inset-right, 0px)) 10px calc(14px + env(safe-area-inset-left, 0px)); display: flex; align-items: center; justify-content: space-between; gap: 10px; }
     .title { display: flex; gap: 8px; align-items: baseline; min-width: 0; }
     .server { font-size: 12px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.08em; white-space: nowrap; }
     .tool { font-size: 14px; font-weight: 600; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
@@ -75,13 +75,24 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     button.primary { border-color: color-mix(in srgb, var(--good) 40%, var(--border) 60%); color: var(--good); }
     button.danger { border-color: color-mix(in srgb, var(--bad) 40%, var(--border) 60%); color: var(--bad); }
     button:hover { background: color-mix(in srgb, var(--surface) 75%, var(--accent) 25%); }
-    main { flex: 1; min-height: 0; padding: 10px; display: flex; }
+    main { flex: 1; min-height: 0; padding: 10px; padding-inline: calc(10px + env(safe-area-inset-left, 0px)) calc(10px + env(safe-area-inset-right, 0px)); padding-bottom: calc(10px + env(safe-area-inset-bottom, 0px)); display: flex; }
     iframe { width: 100%; height: 100%; border: 1px solid var(--border); border-radius: 10px; background: white; }
-    .overlay { position: fixed; inset: 0; background: color-mix(in srgb, var(--bg) 90%, black 10%); display: none; align-items: center; justify-content: center; z-index: 2; }
+    .overlay { position: fixed; inset: 0; background: color-mix(in srgb, var(--bg) 90%, black 10%); display: none; align-items: center; justify-content: center; z-index: 2; padding: 16px; }
     .overlay.visible { display: flex; }
     .panel { width: min(680px, calc(100vw - 40px)); background: var(--surface); border: 1px solid var(--border); border-radius: 12px; padding: 18px; }
     .panel h2 { margin: 0 0 8px; font-size: 16px; }
     .panel p { margin: 0; color: var(--muted); line-height: 1.4; font-size: 14px; white-space: pre-wrap; }
+    @media (max-width: 640px) {
+      header { align-items: stretch; flex-direction: column; gap: 8px; }
+      .title { flex-wrap: wrap; row-gap: 4px; }
+      .server { flex-basis: 100%; }
+      .controls { width: 100%; }
+      .status { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
+      button { min-height: 44px; padding: 10px 14px; }
+      main { padding: 6px; padding-inline: calc(6px + env(safe-area-inset-left, 0px)) calc(6px + env(safe-area-inset-right, 0px)); padding-bottom: calc(6px + env(safe-area-inset-bottom, 0px)); }
+      iframe { border-radius: 6px; }
+      .panel { width: 100%; }
+    }
   </style>
 </head>
 <body>
@@ -98,7 +109,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     </div>
   </header>
   <main>
-    <iframe id="mcp-app" referrerpolicy="no-referrer"></iframe>
+    <iframe id="mcp-app" sandbox="allow-scripts allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox allow-downloads" referrerpolicy="no-referrer"></iframe>
   </main>
   <div class="overlay" id="error-overlay">
     <div class="panel">
@@ -106,6 +117,12 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
       <p id="error-message"></p>
     </div>
   </div>
+  <div class="overlay" id="completion-overlay">
+    <div class="panel">
+      <h2>Done</h2>
+      <p>MCP UI session finished. You can close this page and return to Pi.</p>
+    </div>
+  </div>
   <script type="module">
     import { AppBridge, PostMessageTransport } from ${moduleUrl};
 
@@ -125,6 +142,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     const doneBtn = document.getElementById("done-btn");
     const cancelBtn = document.getElementById("cancel-btn");
     const errorOverlay = document.getElementById("error-overlay");
+    const completionOverlay = document.getElementById("completion-overlay");
     const errorMessage = document.getElementById("error-message");
 
     document.getElementById("server-name").textContent = SERVER_NAME;
@@ -141,6 +159,26 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
       setStatus("Error", true);
     };
 
+    let completionPending = false;
+    const showCompletion = () => {
+      completionOverlay.classList.add("visible");
+      setStatus("Complete");
+    };
+    const closeOrShowDone = () => {
+      completionPending = true;
+      window.close();
+      setTimeout(() => {
+        if (!document.hidden) {
+          showCompletion();
+        }
+      }, 1000);
+    };
+    document.addEventListener("visibilitychange", () => {
+      if (completionPending && !document.hidden) {
+        showCompletion();
+      }
+    });
+
     const post = async (endpoint, params) => {
       const response = await fetch(endpoint, {
         method: "POST",
@@ -315,7 +353,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
     eventSource.addEventListener("session-complete", async () => {
       await bridge.teardownResource({}).catch(() => {});
       eventSource.close();
-      window.close();
+      closeOrShowDone();
     });
     eventSource.onerror = () => {
       setStatus("Connection lost", true);
@@ -334,7 +372,7 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
       } catch {}
       clearInterval(heartbeat);
       eventSource.close();
-      window.close();
+      closeOrShowDone();
     };
 
     doneBtn.addEventListener("click", () => complete("done"));
@@ -353,13 +391,11 @@ export function buildHostHtmlTemplate(input: HostHtmlTemplateInput): string {
 </html>`;
 }
 
-export function buildCspMetaContent(csp: UiResourceCsp | undefined): string | undefined {
-  if (!csp) return undefined;
-
-  const resourceDomains = sanitizeCspDomains(csp.resourceDomains);
-  const connectDomains = sanitizeCspDomains(csp.connectDomains);
-  const frameDomains = sanitizeCspDomains(csp.frameDomains);
-  const baseUriDomains = sanitizeCspDomains(csp.baseUriDomains);
+export function buildCspMetaContent(csp: UiResourceCsp | undefined): string {
+  const resourceDomains = sanitizeCspDomains(csp?.resourceDomains);
+  const connectDomains = sanitizeCspDomains(csp?.connectDomains);
+  const frameDomains = sanitizeCspDomains(csp?.frameDomains);
+  const baseUriDomains = sanitizeCspDomains(csp?.baseUriDomains);
 
   return [
     "default-src 'none'",
@@ -368,11 +404,13 @@ export function buildCspMetaContent(csp: UiResourceCsp | undefined): string | un
     toDirective("font-src", ["'self'"], resourceDomains),
     toDirective("img-src", ["'self'", "data:"], resourceDomains),
     toDirective("media-src", ["'self'", "data:"], resourceDomains),
-    toDirective("connect-src", ["'self'"], connectDomains),
+    connectDomains.length > 0
+      ? `connect-src ${connectDomains.join(" ")}`
+      : "connect-src 'none'",
     frameDomains.length > 0
       ? `frame-src ${frameDomains.join(" ")}`
       : "frame-src 'none'",
-    toDirective("worker-src", ["'self'", "blob:"], resourceDomains),
+    "worker-src 'none'",
     "object-src 'none'",
     baseUriDomains.length > 0
       ? `base-uri ${baseUriDomains.join(" ")}`

package/index.ts

@@ -17,6 +17,7 @@ import { createMcpDirectToolCallRenderer, renderMcpProxyToolCall, renderMcpToolR
 import { toolErrorOverride } from "./error-signal.ts";
 import { createMcpRuntimeOwner, createOwnedUi, isAbortError, type McpRuntimeOwner } from "./runtime-owner.ts";
 import { publishMcpStatusShutdown } from "./mcp-status.ts";
+import { runMcpScript } from "./mcp-code.ts";
 
 export type { McpAdapterOptions } from "./types.ts";
 export {
@@ -106,6 +107,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   const fallbackDeactivatedTools = new Set<string>();
   let proxyToolRegistered = false;
   let proxyToolDescription: string | null = null;
+  let directToolsFrozen = false;
 
   // OMP remaps `typebox` to a host shim that historically lacked Type.Unsafe.
   // Prefer Unsafe when present (real TypeBox / fixed OMP shim); otherwise pass
@@ -278,12 +280,20 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
       nextState.onToolMetadataUpdated = (_serverName, _reason) => {
         if (state !== nextState || !owner.isActive()) return;
         syncPromptCommands();
+        if (directToolsFrozen) {
+          logger.debug(`MCP: metadata update for ${_serverName} (${_reason}) skipped — directTools frozen`);
+          return;
+        }
         syncToolSurface(ctx);
       };
       syncPromptCommands();
       syncToolSurface(ctx);
       updateStatusBar(nextState);
       initPromise = null;
+      if (earlyConfig.settings?.freezeDirectTools === true) {
+        directToolsFrozen = true;
+        logger.info("MCP: direct tools frozen after initial sync — reconnects won't rebuild the system prompt; use mcp({ connect: \"server\" }) to rediscover");
+      }
     }).catch(async err => {
       if (!owner.isActive() || generation !== lifecycleGeneration) {
         return;
@@ -462,6 +472,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         case "reconnect":
           commandOwner?.throwIfInactive();
           await reconnectServers(state, commandCtx, targetServer);
+          if (directToolsFrozen) syncToolSurface(commandCtx);
           break;
         case "tools":
           await showTools(state, commandCtx);
@@ -596,12 +607,58 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     },
   });
 
+  if (earlyConfig.settings?.scriptMode !== false) {
+    (pi.registerTool as (tool: unknown) => unknown)({
+      name: "mcp_script",
+      label: "MCP Script",
+      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).
+        timeoutMs: Type.Optional({ type: "number", minimum: 1, description: "Execution timeout in milliseconds (default: 30000)" } as any),
+      }),
+      renderResult: renderMcpToolResult,
+      async execute(_toolCallId, params: { code: string; timeoutMs?: number }, signal) {
+        const executeOwner = currentOwner;
+        if (!state && initPromise) {
+          try {
+            const initialized = await awaitWithTimeout(initPromise, INIT_WAIT_TIMEOUT_MS);
+            if (initialized === INIT_WAIT_TIMED_OUT) {
+              return {
+                content: [{ type: "text" as const, text: "MCP initialization is still in progress. Try again shortly." }],
+                details: { mode: "script", error: "init_timeout", timeoutMs: INIT_WAIT_TIMEOUT_MS },
+              };
+            }
+            executeOwner?.throwIfInactive();
+            state = initialized;
+          } catch (error) {
+            if (executeOwner && isAbortError(error, executeOwner.signal)) throw error;
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+              content: [{ type: "text" as const, text: `MCP initialization failed: ${message}` }],
+              details: { mode: "script", error: "init_failed", message },
+            };
+          }
+        }
+        if (!state) {
+          return {
+            content: [{ type: "text" as const, text: "MCP not initialized" }],
+            details: { mode: "script", error: "not_initialized" },
+          };
+        }
+        executeOwner?.throwIfInactive();
+        return runMcpScript(state, params.code, params.timeoutMs, getPiTools, signal);
+      },
+    });
+  }
+
   function registerProxyTool(description: string): void {
     (pi.registerTool as (tool: unknown) => unknown)({
       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')" })),
@@ -618,6 +675,9 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         search: Type.Optional(Type.String({ description: "Search tools by name/description" })),
         regex: Type.Optional(Type.Boolean({ description: "Treat search as regex (default: substring match)" })),
         includeSchemas: Type.Optional(Type.Boolean({ description: "Include parameter schemas in search results (default: true)" })),
+        // Raw JSON schema: host TypeBox shims may omit Type.Number (see index-lifecycle shim test).
+        limit: Type.Optional({ type: "number", minimum: 1, description: "Maximum search results to return (default: 12)" } as any),
+        offset: Type.Optional({ type: "number", minimum: 0, description: "Search result offset (default: 0)" } as any),
         server: Type.Optional(Type.String({ description: "Filter to specific server (also disambiguates tool calls)" })),
         action: Type.Optional(Type.String({ description: "Action: 'ui-messages', 'auth-start', or 'auth-complete'" })),
       }),
@@ -631,6 +691,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         search?: string;
         regex?: boolean;
         includeSchemas?: boolean;
+        limit?: number;
+        offset?: number;
         server?: string;
         action?: string;
       }, signal, _onUpdate, _ctx) {
@@ -732,8 +794,8 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         if (params.instructions) {
           return executeInstructions(state, params.instructions);
         }
-        if (params.search) {
-          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas);
+        if (params.search !== undefined) {
+          return executeSearch(state, params.search, params.regex, params.server, params.includeSchemas, params.limit, params.offset);
         }
         if (params.server) {
           return executeList(state, params.server);

package/init.ts

@@ -147,6 +147,7 @@ export async function initializeMcp(
   const serverInstructions = new Map<string, string>();
   const failureTracker = new Map<string, number>();
   const failureMessages = new Map<string, string>();
+  const approvedToolCalls = new Map<string, true>();
   const uiResourceHandler = new UiResourceHandler(manager, config);
   const consentManager = new ConsentManager("once-per-server");
   const state: McpExtensionState = {
@@ -164,6 +165,7 @@ export async function initializeMcp(
     authStorageOptions,
     failureTracker,
     failureMessages,
+    approvedToolCalls,
     uiResourceHandler,
     consentManager,
     uiServer: null,