pi-mcp-adapter 2.21.2 → 2.23.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.23.0] - 2026-08-11
+
+### Added
+- Added interactive callback URL pasting to `/mcp-auth` for OAuth flows running on remote or headless machines. Thanks @trevorleibert-mixpanel for PR #330.
+
+### Fixed
+- Stopped load-time MCP initialization from printing a TUI startup error when Pi action methods are not bound yet. Thanks @21307369 for issue #327.
+- Kept interactive OAuth authorization URLs clickable as a single terminal hyperlink. Thanks @rfccg for PR #329.
+
+## [2.22.0] - 2026-08-11
+
+### Added
+- Added the `pi-mcp-adapter/oauth` subpath for URL-bound OAuth token reuse by cooperating Pi extensions. Thanks @ThePhoenixCoding for issue #323.
+- Added `oauth.logoUri` for OAuth Dynamic Client Registration, with validation that requires an absolute HTTP(S) URL. Thanks @grinich for PR #321.
+
+### Fixed
+- Materialized binary MCP resources as private temporary files before model-facing output, with bounded per-session cleanup. Thanks @zenworr and @shaworr for PR #324.
+- Named OAuth callback pages and dynamic client registrations after rebranded Pi hosts, while preserving stock Pi defaults and avoiding guessed client homepages. Thanks @grinich for PR #320.
+
 ## [2.21.2] - 2026-08-09
 
 ### Fixed

package/README.md

@@ -153,6 +153,17 @@ A supplied `config` is a complete, isolated snapshot. It is not merged with file
 
 With `configPath` and no `config`, the adapter keeps normal file merge behavior, and that path takes precedence over argv and `--mcp-config`. The default export keeps the normal file-based behavior. OAuth credentials are stored in the operating system credential store and keyed by the configured server name; URL binding prevents credentials from being accepted for a different server URL. `settings.oauthDir` and `MCP_OAUTH_DIR` are used only as legacy plaintext import locations for older `tokens.json` files, not as credential namespaces. CSRF state and PKCE verifiers are flow-local, so concurrent authorization flows do not share transient secrets.
 
+Cooperating Pi extensions can use `pi-mcp-adapter/oauth` to reuse URL-bound OAuth tokens without deep-importing private files:
+
+```ts
+import { getMcpOAuthTokensForUrl, updateMcpOAuthTokensForUrl } from "pi-mcp-adapter/oauth";
+
+const tokens = await getMcpOAuthTokensForUrl("jira", "https://jira.example.com/mcp");
+updateMcpOAuthTokensForUrl("jira", "https://jira.example.com/mcp", { accessToken: "..." });
+```
+
+The public subpath exposes only token read/update helpers plus a status helper. The async read path uses the adapter's refresh logic before it returns tokens. The helpers keep secure-store storage, URL binding, refresh persistence, chunk handling, legacy import, and fail-closed credential-store errors. They do not expose client registration secrets, PKCE verifiers, or OAuth state.
+
 ### Runtime status snapshots
 
 Extensions can subscribe to the adapter's versioned shared event-bus channel instead of parsing `/mcp` or `mcp({})` output:
@@ -203,7 +214,8 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `oauth.scope` | Requested OAuth scopes |
 | `oauth.redirectUri` | Exact localhost redirect URI for browser OAuth, including port and path, for providers that pre-register callbacks |
 | `oauth.clientName` | Client display name advertised during Dynamic Client Registration fallback |
-| `oauth.clientUri` | Client homepage URI advertised during Dynamic Client Registration fallback |
+| `oauth.clientUri` | Client homepage URI advertised during Dynamic Client Registration fallback. Defaults to `piConfig.clientUri` from the host's manifest when set, and is omitted rather than guessed under a rebranded host |
+| `oauth.logoUri` | Client logo URL advertised during Dynamic Client Registration fallback (RFC 7591 `logo_uri`). Must be an absolute `http(s)` URL — consent screens fetch it server-side, so local paths render nothing. Omitted from the registration request when unset |
 | `oauth.skipIssuerMetadataValidation` | `true` disables the OAuth authorization-server metadata issuer check for this server. This weakens OAuth mix-up protection and should only be used for known-misconfigured internal servers while their metadata is being fixed. |
 | `bearerToken` / `bearerTokenEnv` | Token or env var name; `bearerToken` supports `${VAR}` and `$env:VAR` interpolation. A leading `!` in `bearerToken` runs a command when the HTTP server connects; use `!!` for a literal leading `!`. |
 | `lifecycle` | `"lazy"` (default), `"eager"`, `"keep-alive"`, or `"lazy-keep-alive"` |
@@ -253,7 +265,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, `/mcp-auth <server>` prints the authorization URL and opens a callback input. Open the URL in your local browser. After approval, the browser may fail to load the localhost callback page because localhost refers to your workstation; copy the full URL from its address bar and paste it into Pi. The input closes automatically instead when the browser can reach Pi's callback directly.
+
+The same flow is available through the proxy tool for non-interactive clients. 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.
 
@@ -372,9 +386,10 @@ Oversized MCP tool/resource results are guarded by default so a single huge resp
 
 - Inline text output is capped at **50 KiB / 2,000 lines** (matching Pi's built-in `bash` guard). Larger output is truncated to a head preview and the full text is saved to a temp file whose path is included in the result, so the agent can `read`/`grep` it.
 - **Image content blocks pass through unchanged** — only text output is guarded. Images are delivered to the provider as native image content.
+- Binary resource blobs up to **10 MiB** are decoded to private temp files and replaced with file references. Each session is limited to **100 MiB** and **10,000 files**. The files are removed at session teardown.
 - In proxy mode, `details.mcpResult` is kept raw when its JSON is **≤ 16 KiB**; larger results are replaced with a compact summary (block counts, sizes, key previews) and the raw JSON is saved to a temp file. Direct tools keep their lean details and never carry `mcpResult`.
 
-Tune the limits with the object form:
+Tune the text and details limits with the object form:
 
 ```json
 {
@@ -384,7 +399,7 @@ 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.
+Set `"outputGuard": false` — or the env kill switch `MCP_OUTPUT_GUARD=0` — to disable text and details guarding. Binary resource materialization and its safety limits remain active. Output-guard spill 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
 

package/agent-dir.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
@@ -18,3 +19,42 @@ export function getAgentDir(): string {
 export function getAgentPath(...segments: string[]): string {
   return join(getAgentDir(), ...segments);
 }
+
+/**
+ * What the host calls itself.
+ *
+ * pi supports rebranding through `piConfig.name` in the package.json that its
+ * `getPackageDir()` resolves, and distributions built on pi (arc, tau, …) point
+ * `PI_PACKAGE_DIR` at their own manifest. Read that manifest directly rather
+ * than importing pi: this package deliberately depends on pi-ai and pi-tui
+ * only, and `getAgentDir()` above reads its env var the same self-contained way.
+ *
+ * Falls back to "pi", which is what pi's own APP_NAME resolves to.
+ */
+function readPiConfig(): { name?: unknown; clientUri?: unknown } | undefined {
+  const dir = process.env.PI_PACKAGE_DIR?.trim()
+  if (!dir) return undefined
+  try {
+    const manifest = JSON.parse(readFileSync(join(resolve(dir), "package.json"), "utf8")) as {
+      piConfig?: { name?: unknown; clientUri?: unknown }
+    }
+    return manifest.piConfig
+  } catch {
+    return undefined
+  }
+}
+
+export function getAppName(): string {
+  const name = readPiConfig()?.name
+  return typeof name === "string" && name.trim() ? name.trim() : "pi"
+}
+
+/**
+ * Home page the host declares for itself, via `piConfig.clientUri` in the same
+ * manifest that carries `piConfig.name`. Only the distribution knows its own
+ * URL, so this is the one place it can come from without guessing.
+ */
+export function getAppClientUri(): string | undefined {
+  const uri = readPiConfig()?.clientUri
+  return typeof uri === "string" && uri.trim() ? uri.trim() : undefined
+}

package/commands.ts

@@ -25,6 +25,10 @@ import { loadOnboardingState, markSetupCompleted as persistSetupCompleted, markS
 import { openPath, resolveServerUrl, sanitizeTerminalText } from "./utils.ts";
 import { isAbortError } from "./runtime-owner.ts";
 
+function terminalHyperlink(label: string, url: string): string {
+  return `\u001B]8;;${sanitizeTerminalText(url)}\u001B\\${sanitizeTerminalText(label)}\u001B]8;;\u001B\\`;
+}
+
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
 
@@ -273,11 +277,17 @@ export async function authenticateServer(
       ...(authStorageOptions.baseDir ? { authStorageOptions } : {}),
       onAuthorizationUrl: (authorizationUrl) => {
         ui.notify(
-          `Open this URL to authenticate ${serverName}:\n\n${authorizationUrl}\n\n` +
-          "After approving, return to Pi; the local callback will complete automatically.",
+          `Open this URL to authenticate ${serverName}:\n\n${terminalHyperlink(authorizationUrl, authorizationUrl)}\n\n` +
+          "After approving, Pi will complete automatically if the browser can reach its localhost callback. " +
+          "On a remote machine, copy the full localhost URL from the browser address bar and paste it into Pi.",
           "info"
         );
       },
+      onAuthorizationInput: (_authorizationUrl, inputSignal) => ui.input(
+        `Complete ${serverName} OAuth`,
+        "Paste the full callback URL, or wait for automatic completion",
+        { signal: inputSignal },
+      ),
       ...(signal ? { signal } : {}),
       ...(runtime ? { runtime } : {}),
     });

package/direct-tools.ts

@@ -8,7 +8,7 @@ import { abortable, throwIfAborted } from "./abort.ts";
 import { isServerCacheValid, parseDirectToolSelectors } from "./metadata-cache.ts";
 export { getMissingConfiguredDirectToolServers } from "./metadata-cache.ts";
 import { formatSchema } from "./tool-metadata.ts";
-import { resolveMcpResultContent, transformMcpContent } from "./tool-registrar.ts";
+import { resolveMcpResultContent, transformMcpContent, transformMcpResourceContents } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
 import { formatToolName, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.ts";
@@ -20,6 +20,7 @@ import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
 import { ensureToolCallApproved } from "./tool-approval.ts";
 
 type ClientCallToolResult = Awaited<ReturnType<Client["callTool"]>>;
+type ClientReadResourceResult = Awaited<ReturnType<Client["readResource"]>>;
 
 const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 const INSTRUCTIONS_SNIPPET_LENGTH = 150;
@@ -435,7 +436,7 @@ export function createDirectToolExecutor(
       state.manager.incrementInFlight(spec.serverName);
 
       if (spec.resourceUri) {
-        const result = await withSessionRecovery(
+        const result = await withSessionRecovery<ClientReadResourceResult>(
           {
             manager: state.manager,
             config: state.config,
@@ -445,10 +446,7 @@ export function createDirectToolExecutor(
           spec.serverName,
           (conn) => conn.client.readResource({ uri: spec.resourceUri! }, requestOptions),
         );
-        const content = (result.contents ?? []).map(c => ({
-          type: "text" as const,
-          text: "text" in c ? c.text : ("blob" in c ? `[Binary data: ${(c as { mimeType?: string }).mimeType ?? "unknown"}]` : JSON.stringify(c)),
-        }));
+        const content = transformMcpResourceContents(result.contents ?? [], state.owner?.signal);
         const guarded = await guardMcpOutput(content.length > 0 ? content : [{ type: "text" as const, text: "(empty resource)" }], outputGuardOptions);
         return {
           content: guarded.content,
@@ -487,7 +485,7 @@ export function createDirectToolExecutor(
 
       if (result.isError) {
         const mcpContent = (result.content ?? []) as McpContent[];
-        const content = transformMcpContent(mcpContent);
+        const content = transformMcpContent(mcpContent, state.owner?.signal);
         const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
         const schemaText = spec.inputSchema ? `\n\nExpected parameters:\n${formatSchema(spec.inputSchema)}` : "";
         const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, prefix: "Error: ", suffix: schemaText, emptyTextFallback: "Tool execution failed" });
@@ -497,7 +495,7 @@ export function createDirectToolExecutor(
         };
       }
 
-      const content = resolveMcpResultContent(result as Record<string, unknown>);
+      const content = resolveMcpResultContent(result as Record<string, unknown>, state.owner?.signal);
       const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
       if (hasUi) {
         const uiSummary = summarizeUiSessionResult(uiSession);

package/index.ts

@@ -19,6 +19,7 @@ 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";
+import { cleanupMaterializedBinaryResources } from "./tool-registrar.ts";
 
 export type { McpAdapterOptions } from "./types.ts";
 export {
@@ -168,13 +169,23 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
     return resolveDirectTools(config, cache, prefix, envDirectToolOverride);
   }
 
+  function getActiveToolsIfReady(): string[] | undefined {
+    try {
+      return pi.getActiveTools?.();
+    } catch (error) {
+      if (error instanceof Error
+        && error.message.includes("Action methods cannot be called during extension loading")) return undefined;
+      throw error;
+    }
+  }
+
   function deactivateTools(toolNames: string[]): string[] {
     if (toolNames.length === 0) return [];
     const unregisterTool = (pi as ExtensionAPI & { unregisterTool?: (name: string) => boolean }).unregisterTool;
     const unregistered = toolNames.filter((toolName) => unregisterTool?.(toolName) === true);
     const fallbackNames = toolNames.filter((toolName) => !unregistered.includes(toolName));
     const remove = new Set(toolNames);
-    const activeTools = pi.getActiveTools?.();
+    const activeTools = getActiveToolsIfReady();
     if (!activeTools || activeTools.length === 0) {
       for (const toolName of fallbackNames) fallbackDeactivatedTools.add(toolName);
       return unregistered;
@@ -206,7 +217,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         registerDirectTool(spec);
         registeredDirectTools.set(spec.prefixedName, fingerprint);
         if (fallbackDeactivatedTools.delete(spec.prefixedName)) {
-          const activeTools = pi.getActiveTools?.();
+          const activeTools = getActiveToolsIfReady();
           if (activeTools && !activeTools.includes(spec.prefixedName)) {
             pi.setActiveTools([...activeTools, spec.prefixedName]);
           }
@@ -275,6 +286,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
   });
 
   function startInitialization(ctx: ExtensionContext, owner: McpRuntimeOwner, oauthRuntime: McpOAuthRuntime, generation: number, staleReason: string): Promise<void> {
+    owner.addCleanup(() => cleanupMaterializedBinaryResources(owner.signal));
     const promise = initializeMcp(pi, ctx, owner, {
       ...(programmaticConfig || options.configPath !== undefined
         ? {
@@ -847,7 +859,7 @@ function installMcpAdapter(pi: ExtensionAPI, options: McpAdapterOptions) {
         registerProxyTool(description);
         return;
       }
-      const activeTools = pi.getActiveTools?.();
+      const activeTools = getActiveToolsIfReady();
       if (activeTools && !activeTools.includes("mcp")) {
         pi.setActiveTools([...activeTools, "mcp"]);
       }

package/mcp-auth-flow.ts

@@ -31,6 +31,7 @@ import {
   getOAuthState,
   clearOAuthState,
   getAuthBaseDir,
+  OAuthCredentialStoreError,
   type AuthStorageOptions,
   type StoredTokens,
 } from "./mcp-auth.ts"
@@ -48,6 +49,10 @@ export interface McpOAuthRuntime {
 
 export interface AuthenticateOptions {
   onAuthorizationUrl?: (authorizationUrl: string) => void | Promise<void>
+  onAuthorizationInput?: (
+    authorizationUrl: string,
+    signal: AbortSignal,
+  ) => Promise<string | undefined>
   authStorageOptions?: AuthStorageOptions
   signal?: AbortSignal
   runtime?: McpOAuthRuntime
@@ -211,6 +216,27 @@ export function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
     }
     config.clientUri = clientUri
   }
+  if (definition.oauth?.logoUri !== undefined) {
+    if (typeof definition.oauth.logoUri !== "string") {
+      throw new Error("OAuth logoUri must be a string")
+    }
+    const logoUri = interpolateEnvVars(definition.oauth.logoUri).trim()
+    if (!logoUri) {
+      throw new Error("OAuth logoUri must not be empty")
+    }
+    // Consent screens fetch this server-side, so a local path silently renders
+    // nothing. Fail here instead, where the message can say why.
+    let parsed: URL
+    try {
+      parsed = new URL(logoUri)
+    } catch {
+      throw new Error("OAuth logoUri must be an absolute http(s) URL")
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      throw new Error("OAuth logoUri must be an absolute http(s) URL")
+    }
+    config.logoUri = logoUri
+  }
   if (definition.oauth?.skipIssuerMetadataValidation !== undefined) {
     if (typeof definition.oauth.skipIssuerMetadataValidation !== "boolean") {
       throw new Error("OAuth skipIssuerMetadataValidation must be a boolean")
@@ -546,6 +572,53 @@ export function parseAuthorizationCodeInput(input: string, expectedState?: strin
   return parseAuthorizationRedirectInput(input, expectedState).code
 }
 
+type AuthorizationResponse = {
+  input: AuthorizationCodeInput
+  source: "callback" | "manual"
+}
+
+/**
+ * Wait for either the localhost callback or a manually pasted redirect URL.
+ * The manual input prompt is dismissed as soon as either path finishes.
+ */
+export async function waitForAuthorizationResponse(
+  callbackPromise: Promise<AuthorizationCodeInput>,
+  authorizationUrl: string,
+  expectedState: string,
+  onAuthorizationInput?: AuthenticateOptions["onAuthorizationInput"],
+  signal?: AbortSignal,
+): Promise<AuthorizationResponse> {
+  if (!onAuthorizationInput) {
+    return {
+      input: await abortable(callbackPromise, signal),
+      source: "callback",
+    }
+  }
+
+  const inputController = new AbortController()
+  try {
+    const response = await abortable(Promise.race([
+      callbackPromise.then((input) => ({ input, source: "callback" as const })),
+      onAuthorizationInput(authorizationUrl, inputController.signal).then((input) => ({
+        input,
+        source: "manual" as const,
+      })),
+    ]), signal)
+
+    if (response.source === "callback") return response
+    if (!response.input?.trim()) throw new Error("OAuth authentication cancelled")
+    if (!getSearchParamsFromInput(response.input.trim())) {
+      throw new Error("Paste the full OAuth callback URL, including its code and state parameters")
+    }
+    return {
+      input: parseAuthorizationRedirectInput(response.input, expectedState),
+      source: "manual",
+    }
+  } finally {
+    inputController.abort()
+  }
+}
+
 /**
  * Complete OAuth authentication from manual user input.
  */
@@ -706,12 +779,22 @@ export async function authenticate(
         console.warn(`MCP Auth: Failed to open browser for ${serverName}; waiting for manual callback`, { error })
       }
 
-      const callbackResult = await abortable(callbackPromise, signal)
+      const authorizationResponse = await waitForAuthorizationResponse(
+        callbackPromise,
+        authorizationUrl,
+        oauthState,
+        options.onAuthorizationInput,
+        signal,
+      )
+      if (authorizationResponse.source === "manual") {
+        cancelPendingCallback(oauthState)
+      }
 
-      // The callback server accepted only the flow-local reserved state.
+      // The callback server accepted only the flow-local reserved state. Manual
+      // input is checked against the same state before token exchange.
       throwIfAborted(signal)
 
-      return await completeAuth(serverName, callbackResult, {
+      return await completeAuth(serverName, authorizationResponse.input, {
         ...options,
         ...(signal ? { signal } : {}),
         runtime,
@@ -799,7 +882,7 @@ export async function getValidToken(
         authProvider.deactivate()
       }
     } catch (error) {
-      if (isAbortError(error, signal)) throw error
+      if (isAbortError(error, signal) || error instanceof OAuthCredentialStoreError) throw error
       console.error(`MCP Auth: Token refresh failed for ${serverName}`, { error })
       return null
     }

package/mcp-callback-server.ts

@@ -6,6 +6,7 @@
  */
 
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from "http"
+import { getAppName } from "./agent-dir.ts"
 import {
   DEFAULT_OAUTH_CALLBACK_PATH,
   getConfiguredOAuthCallbackPort,
@@ -15,45 +16,106 @@ import {
   setOAuthCallbackPort,
 } from "./mcp-oauth-provider.ts"
 
-// HTML templates for callback responses
-const HTML_SUCCESS = `<!DOCTYPE html>
-<html>
-<head>
-  <title>Pi - Authorization Successful</title>
-  <style>
-    body { font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #1a1a2e; color: #eee; }
-    .container { text-align: center; padding: 2rem; }
-    h1 { color: #4ade80; margin-bottom: 1rem; }
-    p { color: #aaa; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <h1>Authorization Successful</h1>
-    <p>You can close this window and return to Pi.</p>
-  </div>
-  <script>setTimeout(() => window.close(), 2000);</script>
-</body>
-</html>`
-
-const HTML_MANUAL_SUCCESS = `<!DOCTYPE html>
-<html>
+// HTML templates for callback responses.
+//
+// These pages are served from localhost during OAuth and are the last thing a
+// user sees before returning to their terminal, so they are self-contained: no
+// webfonts, no external assets, nothing that needs the network. They also name
+// the host rather than hardcoding "Pi", so a distribution that rebrands pi
+// (arc, tau, …) does not send its users back to an app they are not running.
+
+/** Shared chrome: system fonts, a centred card, and light/dark support. */
+const PAGE_STYLE = `
+    :root { color-scheme: light dark; }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+      font: 15px/1.55 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+      background: #0f1117;
+      color: #e6e8ee;
+    }
+    .card {
+      width: 100%;
+      max-width: 26rem;
+      padding: 2.5rem 2rem;
+      text-align: center;
+      background: #161922;
+      border: 1px solid #242938;
+      border-radius: 14px;
+      box-shadow: 0 1px 2px rgba(0,0,0,.3), 0 12px 32px rgba(0,0,0,.25);
+    }
+    .badge {
+      width: 3rem; height: 3rem;
+      margin: 0 auto 1.25rem;
+      display: grid; place-items: center;
+      border-radius: 50%;
+    }
+    .badge svg { width: 1.5rem; height: 1.5rem; display: block; }
+    .ok   { background: rgba(74,222,128,.12); color: #4ade80; }
+    .bad  { background: rgba(248,113,113,.12); color: #f87171; }
+    h1 { margin: 0 0 .5rem; font-size: 1.15rem; font-weight: 600; letter-spacing: -0.01em; }
+    p  { margin: 0; color: #9aa1b1; }
+    .app { color: #e6e8ee; font-weight: 500; }
+    .hint { margin-top: 1.25rem; font-size: .8125rem; color: #6b7280; }
+    code {
+      display: block;
+      margin-top: 1.25rem;
+      padding: .75rem .875rem;
+      text-align: left;
+      font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+      color: #fca5a5;
+      background: rgba(248,113,113,.08);
+      border: 1px solid rgba(248,113,113,.2);
+      border-radius: 8px;
+      overflow-wrap: anywhere;
+    }
+    @media (prefers-color-scheme: light) {
+      body { background: #f6f7f9; color: #121620; }
+      .card { background: #fff; border-color: #e4e7ee; }
+      p { color: #5b6474; }
+      .app { color: #121620; }
+      .hint { color: #8b93a3; }
+    }`
+
+const CHECK_ICON =
+  '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg>'
+
+const CROSS_ICON =
+  '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg>'
+
+function page(options: {
+  title: string
+  heading: string
+  body: string
+  icon: string
+  tone: "ok" | "bad"
+  extra?: string
+  autoClose?: boolean
+}): string {
+  return `<!DOCTYPE html>
+<html lang="en">
 <head>
-  <title>Pi - Authorization Received</title>
-  <style>
-    body { font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #1a1a2e; color: #eee; }
-    .container { text-align: center; padding: 2rem; }
-    h1 { color: #4ade80; margin-bottom: 1rem; }
-    p { color: #aaa; }
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${options.title}</title>
+  <style>${PAGE_STYLE}
   </style>
 </head>
 <body>
-  <div class="container">
-    <h1>Authorization Received</h1>
-    <p>Copy the full callback URL from your browser address bar and paste it back into Pi with auth-complete.</p>
-  </div>
-</body>
+  <main class="card">
+    <div class="badge ${options.tone}">${options.icon}</div>
+    <h1>${options.heading}</h1>
+    <p>${options.body}</p>
+    ${options.extra ?? ""}
+  </main>
+${options.autoClose ? "  <script>setTimeout(() => window.close(), 2000);</script>\n" : ""}</body>
 </html>`
+}
 
 function escapeHtml(value: string): string {
   return value
@@ -64,26 +126,41 @@ function escapeHtml(value: string): string {
     .replace(/'/g, "&#39;")
 }
 
-const HTML_ERROR = (error: string) => `<!DOCTYPE html>
-<html>
-<head>
-  <title>Pi - Authorization Failed</title>
-  <style>
-    body { font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #1a1a2e; color: #eee; }
-    .container { text-align: center; padding: 2rem; }
-    h1 { color: #f87171; margin-bottom: 1rem; }
-    p { color: #aaa; }
-    .error { color: #fca5a5; font-family: monospace; margin-top: 1rem; padding: 1rem; background: rgba(248,113,113,0.1); border-radius: 0.5rem; }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <h1>Authorization Failed</h1>
-    <p>An error occurred during authorization.</p>
-    <div class="error">${escapeHtml(error)}</div>
-  </div>
-</body>
-</html>`
+/** Built per request so a host that sets PI_PACKAGE_DIR late is still named right. */
+function htmlSuccess(): string {
+  const app = escapeHtml(getAppName())
+  return page({
+    title: `${app} — Authorization Successful`,
+    heading: "Authorization Successful",
+    body: `You can close this window and return to <span class="app">${app}</span>.`,
+    icon: CHECK_ICON,
+    tone: "ok",
+    autoClose: true,
+  })
+}
+
+function htmlManualSuccess(): string {
+  const app = escapeHtml(getAppName())
+  return page({
+    title: `${app} — Authorization Received`,
+    heading: "Authorization Received",
+    body: `Copy the full callback URL from your browser address bar and paste it back into <span class="app">${app}</span> with auth-complete.`,
+    icon: CHECK_ICON,
+    tone: "ok",
+  })
+}
+
+function htmlError(error: string): string {
+  const app = escapeHtml(getAppName())
+  return page({
+    title: `${app} — Authorization Failed`,
+    heading: "Authorization Failed",
+    body: `Something went wrong during authorization. You can close this window and try again from <span class="app">${app}</span>.`,
+    icon: CROSS_ICON,
+    tone: "bad",
+    extra: `<code>${escapeHtml(error)}</code>`,
+  })
+}
 
 /** Result of a successful OAuth callback */
 export interface OAuthCallbackResult {
@@ -145,7 +222,7 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   if (!state) {
     const errorMsg = "Missing required state parameter - potential CSRF attack"
     res.writeHead(400, { "Content-Type": "text/html" })
-    res.end(HTML_ERROR(errorMsg))
+    res.end(htmlError(errorMsg))
     return
   }
 
@@ -157,14 +234,14 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
     if (!pending && !isReserved) {
       const errorMsg = "Invalid or expired state parameter - potential CSRF attack"
       res.writeHead(400, { "Content-Type": "text/html" })
-      res.end(HTML_ERROR(errorMsg))
+      res.end(htmlError(errorMsg))
       return
     }
 
     const errorMsg = errorDescription || error
     // Send HTTP response first before rejecting promise
     res.writeHead(200, { "Content-Type": "text/html" })
-    res.end(HTML_ERROR(errorMsg))
+    res.end(htmlError(errorMsg))
     // Reject promise after response is sent (defer to allow test to attach handler)
     if (pending) {
       reservedAuthStates.delete(state)
@@ -179,20 +256,20 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   if (!pending && !isReserved) {
     const errorMsg = "Invalid or expired state parameter - potential CSRF attack"
     res.writeHead(400, { "Content-Type": "text/html" })
-    res.end(HTML_ERROR(errorMsg))
+    res.end(htmlError(errorMsg))
     return
   }
 
   // Require authorization code
   if (!code) {
     res.writeHead(400, { "Content-Type": "text/html" })
-    res.end(HTML_ERROR("No authorization code provided"))
+    res.end(htmlError("No authorization code provided"))
     return
   }
 
   if (!pending) {
     res.writeHead(200, { "Content-Type": "text/html" })
-    res.end(HTML_MANUAL_SUCCESS)
+    res.end(htmlManualSuccess())
     return
   }
 
@@ -202,7 +279,7 @@ function handleRequest(req: IncomingMessage, res: ServerResponse): void {
   pending.resolve({ code, ...(iss !== null ? { iss } : {}) })
 
   res.writeHead(200, { "Content-Type": "text/html" })
-  res.end(HTML_SUCCESS)
+  res.end(htmlSuccess())
 }
 
 /**

package/mcp-oauth-provider.ts

@@ -30,6 +30,37 @@ import {
   type StoredClientInfo,
 } from "./mcp-auth.ts"
 import { resolveCommandSecret } from "./utils.ts"
+import { getAppClientUri, getAppName } from "./agent-dir.ts"
+
+/**
+ * Client name advertised during Dynamic Client Registration.
+ *
+ * A distribution that rebrands pi (arc, tau, …) should register under its own
+ * name — otherwise every consent screen its users see asks them to authorize
+ * an app they have never run. Stock pi keeps the long-standing
+ * "Pi Coding Agent" so existing registrations are unaffected.
+ */
+function defaultClientName(): string {
+  const app = getAppName()
+  return app === "pi" ? "Pi Coding Agent" : app
+}
+
+/**
+ * Client homepage advertised during Dynamic Client Registration.
+ *
+ * RFC 7591 defines client_uri as the home page *of the client*. Under a
+ * rebranded pi the client is that distribution, not this adapter, so pointing
+ * at the adapter's repository misidentifies it on the consent screen. There is
+ * no way to guess the right URL and a wrong one is worse than none, so the
+ * field is omitted unless a server config supplies oauth.clientUri.
+ *
+ * Stock pi keeps the historical value.
+ */
+function defaultClientUri(): string | undefined {
+  const declared = getAppClientUri()
+  if (declared) return declared
+  return getAppName() === "pi" ? "https://github.com/nicobailon/pi-mcp-adapter" : undefined
+}
 
 type IssuerBoundClientInformation = OAuthClientInformationMixed & { issuer?: string }
 type IssuerBoundTokens = OAuthTokens & { issuer?: string }
@@ -86,6 +117,7 @@ export interface McpOAuthConfig {
   redirectUri?: string
   clientName?: string
   clientUri?: string
+  logoUri?: string
   skipIssuerMetadataValidation?: boolean
 }
 
@@ -189,6 +221,11 @@ export class McpOAuthProvider implements OAuthClientProvider {
     return this.redirectUrlSnapshot
   }
 
+  /** Configured homepage, else the historical default on stock pi, else nothing. */
+  private get clientUri(): string | undefined {
+    return this.config.clientUri ?? defaultClientUri()
+  }
+
   /**
    * Client metadata for dynamic registration.
    * Describes this client to the OAuth authorization server.
@@ -196,8 +233,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
   get clientMetadata(): OAuthClientMetadata {
     if (this.usesClientCredentials) {
       return {
-        client_name: this.config.clientName ?? "Pi Coding Agent",
-        client_uri: this.config.clientUri ?? "https://github.com/nicobailon/pi-mcp-adapter",
+        client_name: this.config.clientName ?? defaultClientName(),
+        ...(this.clientUri !== undefined ? { client_uri: this.clientUri } : {}),
+        ...(this.config.logoUri !== undefined ? { logo_uri: this.config.logoUri } : {}),
         redirect_uris: [],
         grant_types: ["client_credentials"],
         token_endpoint_auth_method: this.config.clientSecret ? "client_secret_post" : "none",
@@ -211,8 +249,9 @@ export class McpOAuthProvider implements OAuthClientProvider {
 
     return {
       redirect_uris: [redirectUrl],
-      client_name: this.config.clientName ?? "Pi Coding Agent",
-      client_uri: this.config.clientUri ?? "https://github.com/nicobailon/pi-mcp-adapter",
+      client_name: this.config.clientName ?? defaultClientName(),
+      ...(this.clientUri !== undefined ? { client_uri: this.clientUri } : {}),
+      ...(this.config.logoUri !== undefined ? { logo_uri: this.config.logoUri } : {}),
       grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
       token_endpoint_auth_method: this.config.clientSecret ? "client_secret_post" : "none",

package/oauth.ts

@@ -0,0 +1,48 @@
+import { getValidToken } from "./mcp-auth-flow.ts";
+import {
+  inspectAuthForUrl,
+  updateTokens,
+  type AuthStorageOptions,
+  type StoredTokens,
+} from "./mcp-auth.ts";
+
+export type McpOAuthTokens = StoredTokens;
+export type McpOAuthStorageOptions = AuthStorageOptions;
+export interface McpOAuthTokenOptions {
+  authStorageOptions?: McpOAuthStorageOptions;
+  signal?: AbortSignal;
+  skipIssuerMetadataValidation?: boolean;
+}
+export type McpOAuthTokenStatus =
+  | { status: "present"; tokens: McpOAuthTokens }
+  | { status: "absent" }
+  | { status: "unavailable"; message: string };
+
+export async function getMcpOAuthTokensForUrl(
+  serverName: string,
+  serverUrl: string,
+  options: McpOAuthTokenOptions = {},
+): Promise<McpOAuthTokens | undefined> {
+  return (await getValidToken(serverName, serverUrl, options)) ?? undefined;
+}
+
+export function inspectMcpOAuthTokensForUrl(
+  serverName: string,
+  serverUrl: string,
+  options?: McpOAuthStorageOptions,
+): McpOAuthTokenStatus {
+  const status = inspectAuthForUrl(serverName, serverUrl, options);
+  if (status.status !== "present") return status;
+  return status.entry.tokens
+    ? { status: "present", tokens: status.entry.tokens }
+    : { status: "absent" };
+}
+
+export function updateMcpOAuthTokensForUrl(
+  serverName: string,
+  serverUrl: string,
+  tokens: McpOAuthTokens,
+  options?: McpOAuthStorageOptions,
+): void {
+  updateTokens(serverName, tokens, serverUrl, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.21.2",
+  "version": "2.23.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -14,6 +14,11 @@
       "types": "./types.ts",
       "import": "./types.ts",
       "default": "./types.ts"
+    },
+    "./oauth": {
+      "types": "./oauth.ts",
+      "import": "./oauth.ts",
+      "default": "./oauth.ts"
     }
   },
   "license": "MIT",
@@ -29,7 +34,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test --test-concurrency=1 mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
+    "test:oauth": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test --test-concurrency=1 oauth-public-api.test.ts mcp-auth.test.ts mcp-auth-flow.test.ts mcp-callback-server.test.ts mcp-oauth-provider.test.ts",
     "test:oauth-provider": "PI_MCP_ADAPTER_TEST_AUTH_STORE=memory node --import tsx --test mcp-oauth-provider.test.ts",
     "test:conformance": "bash conformance/run.sh"
   },
@@ -107,6 +112,7 @@
     "glimpse-ui.ts",
     "npx-resolver.ts",
     "oauth-handler.ts",
+    "oauth.ts",
     "mcp-auth.ts",
     "mcp-keyring-helper.cjs",
     "mcp-oauth-provider.ts",

package/proxy-modes.ts

@@ -10,7 +10,7 @@ import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
 import { buildToolMetadata, getToolNames, findToolByName, formatSchema } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
 import { reconstructPromptMetadata } from "./metadata-cache.ts";
-import { resolveMcpResultContent, transformMcpContent } from "./tool-registrar.ts";
+import { resolveMcpResultContent, transformMcpContent, transformMcpResourceContents } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
 import { maybeStartUiSession, summarizeUiSessionResult, type UiSessionRuntime } from "./ui-session.ts";
 import { formatAuthRequiredMessage, formatMcpStatus, resolveServerUrl, truncateAtWord } from "./utils.ts";
@@ -21,6 +21,7 @@ import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-appro
 
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
 type ClientCallToolResult = Awaited<ReturnType<Client["callTool"]>>;
+type ClientReadResourceResult = Awaited<ReturnType<Client["readResource"]>>;
 
 const require = createRequire(import.meta.url);
 const MAX_REGEX_SEARCH_QUERY_LENGTH = 256;
@@ -1112,7 +1113,7 @@ export async function executeCall(
     state.manager.incrementInFlight(serverName);
 
     if (toolMeta.resourceUri) {
-      const result = await withSessionRecovery(
+      const result = await withSessionRecovery<ClientReadResourceResult>(
         {
           manager: state.manager,
           config: state.config,
@@ -1122,10 +1123,7 @@ export async function executeCall(
         serverName,
         (conn) => conn.client.readResource({ uri: toolMeta.resourceUri! }, requestOptions),
       );
-      const content = (result.contents ?? []).map(c => ({
-        type: "text" as const,
-        text: "text" in c ? c.text : ("blob" in c ? `[Binary data: ${(c as { mimeType?: string }).mimeType ?? "unknown"}]` : JSON.stringify(c)),
-      }));
+      const content = transformMcpResourceContents(result.contents ?? [], state.owner?.signal);
       const guarded = await guardMcpOutput(content.length > 0 ? content : [{ type: "text" as const, text: "(empty resource)" }], outputGuardOptions);
       return {
         content: guarded.content,
@@ -1165,7 +1163,7 @@ export async function executeCall(
 
       if (result.isError) {
         const mcpContent = (result.content ?? []) as McpContent[];
-        const content = transformMcpContent(mcpContent);
+        const content = transformMcpContent(mcpContent, state.owner?.signal);
         const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
         const schemaText = toolMeta.inputSchema ? `\n\nExpected parameters:\n${formatSchema(toolMeta.inputSchema)}` : "";
         const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, prefix: "Error: ", suffix: schemaText, emptyTextFallback: "Tool execution failed", rawMcpResult: result });
@@ -1175,7 +1173,7 @@ export async function executeCall(
         };
       }
 
-      const content = resolveMcpResultContent(result as Record<string, unknown>);
+      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 uiSummary = summarizeUiSessionResult(uiSession);
       const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, suffix: `\n\n${uiSummary.message}`, rawMcpResult: result });
@@ -1194,7 +1192,7 @@ export async function executeCall(
 
     if (result.isError) {
       const mcpContent = (result.content ?? []) as McpContent[];
-      const content = transformMcpContent(mcpContent);
+      const content = transformMcpContent(mcpContent, state.owner?.signal);
       const outputContent = content.length > 0 ? content : [{ type: "text" as const, text: "(empty result)" }];
       const schemaText = toolMeta.inputSchema ? `\n\nExpected parameters:\n${formatSchema(toolMeta.inputSchema)}` : "";
       const guarded = await guardMcpOutput(outputContent, { ...outputGuardOptions, prefix: "Error: ", suffix: schemaText, emptyTextFallback: "Tool execution failed", rawMcpResult: result });
@@ -1204,7 +1202,7 @@ export async function executeCall(
       };
     }
 
-    const content = resolveMcpResultContent(result as Record<string, unknown>);
+    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 });
     return {

package/tool-registrar.ts

@@ -2,12 +2,189 @@
 // NOTE: Tools are NOT registered with Pi - only the unified `mcp` proxy tool is registered.
 // This keeps the LLM context small (1 tool instead of 100s).
 
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { McpContent, ContentBlock } from "./types.ts";
 
+const MAX_BINARY_RESOURCE_BYTES = 10 * 1024 * 1024;
+const MAX_SESSION_RESOURCE_BYTES = 100 * 1024 * 1024;
+const MAX_SESSION_RESOURCE_FILES = 10_000; // Bounds metadata from empty or tiny resources.
+const CLEANUP_RETRY_DELAY_MS = 30_000;
+const MAX_CLEANUP_RETRY_ATTEMPTS = 3;
+type MaterializedResourceSession = {
+  directory: string | undefined;
+  bytes: number;
+  files: number;
+  sequence: number;
+};
+
+function createMaterializedResourceSession(): MaterializedResourceSession {
+  return {
+    directory: undefined,
+    bytes: 0,
+    files: 0,
+    sequence: 0,
+  };
+}
+
+const defaultMaterializedResourceSession = createMaterializedResourceSession();
+const scopedMaterializedResourceSessions = new WeakMap<object, MaterializedResourceSession>();
+const pendingCleanupDirectories = new Set<string>();
+const cleanupRetryAttempts = new Map<string, number>();
+let pendingCleanupRetry: ReturnType<typeof setTimeout> | undefined;
+
+function isAbortedScope(scope: object | undefined): boolean {
+  return !!scope && "aborted" in scope && (scope as { aborted?: unknown }).aborted === true;
+}
+
+function getMaterializedResourceSession(scope?: object): MaterializedResourceSession | undefined {
+  if (isAbortedScope(scope)) return undefined;
+  if (!scope) return defaultMaterializedResourceSession;
+  let session = scopedMaterializedResourceSessions.get(scope);
+  if (!session) {
+    session = createMaterializedResourceSession();
+    scopedMaterializedResourceSessions.set(scope, session);
+  }
+  return session;
+}
+
+type BinaryResource = { uri?: string | undefined; text?: string | undefined; mimeType?: string | undefined; blob: string };
+type McpResourceContent = {
+  uri: string;
+  text?: string | undefined;
+  blob?: string | undefined;
+  mimeType?: string | undefined;
+  [key: string]: unknown;
+};
+
+function hasRetryableCleanupDirectory(): boolean {
+  for (const directory of pendingCleanupDirectories) {
+    if ((cleanupRetryAttempts.get(directory) ?? 0) < MAX_CLEANUP_RETRY_ATTEMPTS) return true;
+  }
+  return false;
+}
+
+function schedulePendingCleanupRetry(): void {
+  if (pendingCleanupRetry || !hasRetryableCleanupDirectory()) return;
+  for (const directory of pendingCleanupDirectories) {
+    const attempts = cleanupRetryAttempts.get(directory) ?? 0;
+    if (attempts < MAX_CLEANUP_RETRY_ATTEMPTS) cleanupRetryAttempts.set(directory, attempts + 1);
+  }
+  pendingCleanupRetry = setTimeout(() => {
+    pendingCleanupRetry = undefined;
+    try {
+      drainPendingCleanupDirectories();
+    } catch {
+      // drainPendingCleanupDirectories already retained the paths and rescheduled another retry.
+    }
+  }, CLEANUP_RETRY_DELAY_MS);
+}
+
+function drainPendingCleanupDirectories(): void {
+  const failures: unknown[] = [];
+  for (const directory of Array.from(pendingCleanupDirectories)) {
+    try {
+      rmSync(directory, { recursive: true, force: true });
+      pendingCleanupDirectories.delete(directory);
+      cleanupRetryAttempts.delete(directory);
+    } catch (error) {
+      failures.push(error);
+    }
+  }
+  if (pendingCleanupDirectories.size === 0 && pendingCleanupRetry) {
+    clearTimeout(pendingCleanupRetry);
+    pendingCleanupRetry = undefined;
+  }
+  if (failures.length > 0) {
+    schedulePendingCleanupRetry();
+    throw new AggregateError(failures, "Failed to clean materialized MCP resources");
+  }
+}
+
+export function cleanupMaterializedBinaryResources(scope?: object): void {
+  const session = scope ? scopedMaterializedResourceSessions.get(scope) : defaultMaterializedResourceSession;
+  if (session?.directory) pendingCleanupDirectories.add(session.directory);
+  if (session) {
+    session.directory = undefined;
+    session.bytes = 0;
+    session.files = 0;
+    session.sequence = 0;
+    if (scope) scopedMaterializedResourceSessions.delete(scope);
+  }
+
+  drainPendingCleanupDirectories();
+}
+
+function replaceBlob(resource: BinaryResource, text: string): string {
+  delete (resource as Partial<BinaryResource>).blob;
+  resource.text = text;
+  return text;
+}
+
+function omitBinaryResource(resource: BinaryResource, reason: string): string {
+  return replaceBlob(resource, [
+    `[Resource: ${resource.uri ?? "(no URI)"}]`,
+    `Binary content omitted: ${reason}`,
+    `MIME type: ${resource.mimeType ?? "application/octet-stream"}`,
+  ].join("\n"));
+}
+
+function materializeBinaryResource(resource: BinaryResource, scope?: object): string {
+  const session = getMaterializedResourceSession(scope);
+  if (!session) return omitBinaryResource(resource, "runtime stopped");
+  const decodedBytes = Buffer.byteLength(resource.blob, "base64");
+  if (decodedBytes > MAX_BINARY_RESOURCE_BYTES) {
+    return omitBinaryResource(resource, "decoded size exceeds 10 MiB");
+  }
+  if (
+    session.bytes + decodedBytes > MAX_SESSION_RESOURCE_BYTES ||
+    session.files >= MAX_SESSION_RESOURCE_FILES
+  ) {
+    return omitBinaryResource(resource, "session resource limit reached");
+  }
+
+  try {
+    session.directory ??= mkdtempSync(join(tmpdir(), "pi-mcp-resource-"));
+  } catch {
+    return omitBinaryResource(resource, "could not be saved");
+  }
+
+  const filePath = join(session.directory, `resource-${++session.sequence}.bin`);
+  session.bytes += decodedBytes;
+  session.files += 1;
+  try {
+    writeFileSync(filePath, Buffer.from(resource.blob, "base64"), { flag: "wx", mode: 0o600 });
+  } catch {
+    try {
+      rmSync(filePath, { force: true });
+      session.bytes -= decodedBytes;
+      session.files -= 1;
+    } catch {
+      // Keep the reservation when a partial file cannot be removed.
+    }
+    return omitBinaryResource(resource, "could not be saved");
+  }
+
+  return replaceBlob(resource, [
+    `[Resource: ${resource.uri ?? "(no URI)"}]`,
+    `Binary content saved to ${filePath}`,
+    `MIME type: ${resource.mimeType ?? "application/octet-stream"}`,
+  ].join("\n"));
+}
+
 /**
  * Transform MCP content types to Pi content blocks.
  */
-export function transformMcpContent(content: McpContent[]): ContentBlock[] {
+export function transformMcpResourceContents(contents: McpResourceContent[], scope?: object): ContentBlock[] {
+  return contents.map(resource => {
+    if (typeof resource.text === "string") return { type: "text" as const, text: resource.text };
+    if (typeof resource.blob === "string") return { type: "text" as const, text: materializeBinaryResource(resource as BinaryResource, scope) };
+    return { type: "text" as const, text: JSON.stringify(resource) };
+  });
+}
+
+export function transformMcpContent(content: McpContent[], scope?: object): ContentBlock[] {
   return content.map(c => {
     if (c.type === "text") {
       return { type: "text" as const, text: c.text ?? "" };
@@ -21,6 +198,13 @@ export function transformMcpContent(content: McpContent[]): ContentBlock[] {
     }
     if (c.type === "resource") {
       const resourceUri = c.resource?.uri ?? "(no URI)";
+      if (c.resource && "blob" in c.resource && typeof c.resource.blob === "string") {
+        const binaryResource = c.resource as typeof c.resource & { mimeType?: string; blob: string };
+        return {
+          type: "text" as const,
+          text: materializeBinaryResource(binaryResource, scope),
+        };
+      }
       const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
       return {
         type: "text" as const,
@@ -49,8 +233,8 @@ export function transformMcpContent(content: McpContent[]): ContentBlock[] {
  * Resolve a tool result's content blocks, falling back to structuredContent
  * when content is empty.
  */
-export function resolveMcpResultContent(result: Record<string, unknown>): ContentBlock[] {
-  const blocks = transformMcpContent((Array.isArray(result.content) ? result.content : []) as McpContent[]);
+export function resolveMcpResultContent(result: Record<string, unknown>, scope?: object): ContentBlock[] {
+  const blocks = transformMcpContent((Array.isArray(result.content) ? result.content : []) as McpContent[], scope);
   if (blocks.length > 0) return blocks;
 
   if (result.structuredContent !== undefined && result.structuredContent !== null) {

package/types.ts

@@ -350,6 +350,8 @@ export interface OAuthConfig {
   clientName?: string;
   /** Client homepage URI for dynamic registration */
   clientUri?: string;
+  /** Client logo URL for dynamic registration; shown on consent screens */
+  logoUri?: string;
   /** Security-weakening escape hatch for known-misconfigured authorization servers. */
   skipIssuerMetadataValidation?: boolean;
 }