pi-mcp-adapter 2.21.1 → 2.22.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Reported MCP servers still connecting after a zero-result tool search, so agents retry instead of treating the result as definitive. Thanks @Leon69924 for issue #316.
+- Rejected malformed MCP config server entries and persisted OAuth credential records at their trust boundaries, so invalid local state fails before it reaches runtime connection or token code.
+- Sized OAuth credential chunks below the Windows Credential Manager per-value limit, so oversized OAuth records persist on Windows instead of failing at every payload size. The previous 1800-character chunk size exceeded the 1280-character ceiling, which left the chunking added in #246 ineffective on Windows. Thanks @CrazyCoder for PR #318.
+
 ## [2.21.1] - 2026-08-08
 
 ### Changed

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"` |
@@ -372,9 +384,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 +397,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/config.ts

@@ -638,22 +638,32 @@ function readValidatedConfig(path: string, label: string): McpConfig | null {
 }
 
 function validateConfig(raw: unknown): McpConfig {
-  if (!raw || typeof raw !== "object") {
+  if (!isRecord(raw)) {
     return { mcpServers: {} };
   }
 
-  const obj = raw as Record<string, unknown>;
-  const servers = obj.mcpServers ?? obj["mcp-servers"] ?? {};
+  return {
+    mcpServers: toServerEntries(raw.mcpServers ?? raw["mcp-servers"]),
+    ...(Array.isArray(raw.imports) ? { imports: raw.imports as ImportKind[] } : {}),
+    ...(raw.settings !== undefined ? { settings: raw.settings as McpSettings } : {}),
+  };
+}
 
-  if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
-    return { mcpServers: {} };
+function toServerEntries(servers: unknown): Record<string, ServerEntry> {
+  if (!isRecord(servers)) return {};
+  const entries: Record<string, ServerEntry> = {};
+  for (const [name, entry] of Object.entries(servers)) {
+    if (isServerEntry(entry)) entries[name] = entry;
   }
+  return entries;
+}
 
-  return {
-    mcpServers: servers as Record<string, ServerEntry>,
-    ...(Array.isArray(obj.imports) ? { imports: obj.imports as ImportKind[] } : {}),
-    ...(obj.settings !== undefined ? { settings: obj.settings as McpSettings } : {}),
-  };
+function isServerEntry(value: unknown): value is ServerEntry {
+  return isRecord(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function mergeOpenCodeConfigs(base: Record<string, unknown>, next: Record<string, unknown>): Record<string, unknown> {
@@ -787,12 +797,13 @@ function extractServers(config: unknown, kind: ImportKind): Record<string, Serve
       continue;
     }
 
-    if (kind !== "codex" || !entry || typeof entry !== "object" || Array.isArray(entry)) {
-      mappedServers[name] = entry as ServerEntry;
+    if (!isRecord(entry)) continue;
+    if (kind !== "codex") {
+      mappedServers[name] = entry;
       continue;
     }
 
-    const mapped = { ...(entry as Record<string, unknown>) };
+    const mapped = { ...entry };
     const bearerTokenEnv = mapped.bearer_token_env_var;
     const httpHeaders = mapped.http_headers;
     const envHttpHeaders = mapped.env_http_headers;

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 {
@@ -275,6 +276,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
         ? {

package/mcp-auth-flow.ts

@@ -31,6 +31,7 @@ import {
   getOAuthState,
   clearOAuthState,
   getAuthBaseDir,
+  OAuthCredentialStoreError,
   type AuthStorageOptions,
   type StoredTokens,
 } from "./mcp-auth.ts"
@@ -211,6 +212,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")
@@ -667,14 +689,12 @@ export async function authenticate(
   }
 
   const operation = (async (): Promise<AuthStatus> => {
-    // Start auth flow
     const { authorizationUrl } = await startAuth(serverName, serverUrl, definition, {
       ...options,
       ...(signal ? { signal } : {}),
       runtime,
     })
 
-    // If no auth URL needed, already authenticated
     if (!authorizationUrl) {
       return "authenticated"
     }
@@ -708,13 +728,11 @@ export async function authenticate(
         console.warn(`MCP Auth: Failed to open browser for ${serverName}; waiting for manual callback`, { error })
       }
 
-      // Wait for callback
       const callbackResult = await abortable(callbackPromise, signal)
 
       // The callback server accepted only the flow-local reserved state.
       throwIfAborted(signal)
 
-      // Complete the auth
       return await completeAuth(serverName, callbackResult, {
         ...options,
         ...(signal ? { signal } : {}),
@@ -758,25 +776,21 @@ export async function getValidToken(
   const authStorageOptions = options.authStorageOptions ?? {}
   const signal = combineAbortSignals(runtime.signal, options.signal)
   throwIfAborted(signal)
-  // Check if we have valid tokens
   const entry = await getAuthForUrl(serverName, serverUrl, authStorageOptions)
   throwIfAborted(signal)
   if (!entry?.tokens) {
     return null
   }
 
-  // Check expiration
   const expired = await isTokenExpired(serverName, authStorageOptions)
   if (expired === false) {
     return entry.tokens
   }
 
   if (expired === true && entry.tokens.refreshToken) {
-    // Token is expired, try to refresh
     console.log(`MCP Auth: Token expired for ${serverName}, attempting refresh`)
 
     try {
-      // Create auth provider for token refresh
       const authProvider = new McpOAuthProvider(serverName, serverUrl, {}, {
         onRedirect: async () => {},
       }, authStorageOptions, runtime.signal)
@@ -807,7 +821,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-auth.ts

@@ -22,7 +22,16 @@ import { resolveConfiguredOAuthDir } from './config.ts';
 const require = createRequire(import.meta.url);
 const AUTH_SECRET_SERVICE = 'pi-mcp-adapter.oauth';
 const TEST_AUTH_STORE_ENV = 'PI_MCP_ADAPTER_TEST_AUTH_STORE';
-const AUTH_SECRET_CHUNK_SIZE = 1800;
+/**
+ * Windows Credential Manager caps one value at CRED_MAX_CREDENTIAL_BLOB_SIZE
+ * (2560 bytes) and stores it as UTF-16, so the real ceiling is
+ * AUTH_SECRET_VALUE_LIMIT characters. Chunks must stay below that, and so must
+ * the threshold that decides whether to chunk at all, or oversized records still
+ * fail to persist on Windows.
+ */
+const AUTH_SECRET_CHUNK_SIZE = 1000;
+/** Largest single value the strictest supported credential store accepts. */
+const AUTH_SECRET_VALUE_LIMIT = 1280;
 const KEYRING_RECOVERY_DISABLED_ENV = 'PI_MCP_ADAPTER_DISABLE_KEYRING_RECOVERY';
 const KEYRING_RECOVERY_KEYCTL_ENV = 'PI_MCP_ADAPTER_KEYRING_RECOVERY_KEYCTL';
 const KEYRING_RECOVERY_NODE_ENV = 'PI_MCP_ADAPTER_KEYRING_RECOVERY_NODE';
@@ -163,6 +172,22 @@ const keyringAuthSecretStore: AuthSecretStore = {
   },
 };
 
+/** Mimics the Windows Credential Manager per-value ceiling for tests. */
+const sizeLimitedAuthSecretStore: AuthSecretStore = {
+  read(account) {
+    return memoryAuthEntries.get(account);
+  },
+  write(account, payload) {
+    if (payload.length > AUTH_SECRET_VALUE_LIMIT) {
+      throw new Error(`Value of 'password encoded as UTF-16' is longer than the platform limit of ${AUTH_SECRET_VALUE_LIMIT * 2} chars`);
+    }
+    memoryAuthEntries.set(account, payload);
+  },
+  remove(account) {
+    memoryAuthEntries.delete(account);
+  },
+};
+
 const unavailableAuthSecretStore: AuthSecretStore = {
   read() {
     throw new Error('simulated secure credential store unavailable');
@@ -205,6 +230,7 @@ export function removeTestAuthSecretStoreEntry(account: string): void {
 
 function getAuthSecretStore(): AuthSecretStore {
   if (process.env[TEST_AUTH_STORE_ENV] === 'memory') return memoryAuthSecretStore;
+  if (process.env[TEST_AUTH_STORE_ENV] === 'sizelimited') return sizeLimitedAuthSecretStore;
   if (process.env[TEST_AUTH_STORE_ENV] === 'unavailable') return unavailableAuthSecretStore;
   if (process.env[TEST_AUTH_STORE_ENV] === 'keyrevoked') return keyRevokedAuthSecretStore;
   return keyringAuthSecretStore;
@@ -401,7 +427,99 @@ function parseJsonPayload(serverName: string, payload: string, source: string):
 }
 
 function parseAuthEntryPayload(serverName: string, payload: string, source: string): AuthEntry {
-  return parseJsonPayload(serverName, payload, source) as AuthEntry;
+  const parsed = parseJsonPayload(serverName, payload, source);
+  const entry = toAuthEntry(parsed);
+  if (!entry) {
+    throw new Error(`Failed to parse OAuth credentials for ${serverName} from ${source}: invalid credential shape`);
+  }
+  return entry;
+}
+
+function toAuthEntry(value: unknown): AuthEntry | undefined {
+  const entry = toRecord(value);
+  if (!entry) return undefined;
+
+  const codeVerifier = optionalString(entry.codeVerifier);
+  const oauthState = optionalString(entry.oauthState);
+  const serverUrl = optionalString(entry.serverUrl);
+  if (codeVerifier === null || oauthState === null || serverUrl === null) return undefined;
+
+  const tokens = entry.tokens === undefined ? undefined : toStoredTokens(entry.tokens);
+  const clientInfo = entry.clientInfo === undefined ? undefined : toStoredClientInfo(entry.clientInfo);
+  if ((entry.tokens !== undefined && !tokens) || (entry.clientInfo !== undefined && !clientInfo)) return undefined;
+
+  const authEntry: AuthEntry = {};
+  if (tokens) authEntry.tokens = tokens;
+  if (clientInfo) authEntry.clientInfo = clientInfo;
+  if (codeVerifier !== undefined) authEntry.codeVerifier = codeVerifier;
+  if (oauthState !== undefined) authEntry.oauthState = oauthState;
+  if (serverUrl !== undefined) authEntry.serverUrl = serverUrl;
+  return authEntry;
+}
+
+function toStoredTokens(value: unknown): StoredTokens | undefined {
+  const tokens = toRecord(value);
+  if (!tokens || typeof tokens.accessToken !== 'string') return undefined;
+
+  const refreshToken = optionalString(tokens.refreshToken);
+  const scope = optionalString(tokens.scope);
+  const issuer = optionalString(tokens.issuer);
+  const expiresAt = optionalNumber(tokens.expiresAt);
+  if (refreshToken === null || scope === null || issuer === null || expiresAt === null) return undefined;
+
+  const storedTokens: StoredTokens = { accessToken: tokens.accessToken };
+  if (refreshToken !== undefined) storedTokens.refreshToken = refreshToken;
+  if (expiresAt !== undefined) storedTokens.expiresAt = expiresAt;
+  if (scope !== undefined) storedTokens.scope = scope;
+  if (issuer !== undefined) storedTokens.issuer = issuer;
+  return storedTokens;
+}
+
+function toStoredClientInfo(value: unknown): StoredClientInfo | undefined {
+  const clientInfo = toRecord(value);
+  if (!clientInfo || typeof clientInfo.clientId !== 'string') return undefined;
+
+  const clientSecret = optionalString(clientInfo.clientSecret);
+  const issuer = optionalString(clientInfo.issuer);
+  const clientIdIssuedAt = optionalNumber(clientInfo.clientIdIssuedAt);
+  const clientSecretExpiresAt = optionalNumber(clientInfo.clientSecretExpiresAt);
+  const configPreRegistered = optionalBoolean(clientInfo.configPreRegistered);
+  if (clientSecret === null || issuer === null || clientIdIssuedAt === null || clientSecretExpiresAt === null || configPreRegistered === null) return undefined;
+
+  const storedClient: StoredClientInfo = { clientId: clientInfo.clientId };
+  const redirectUris = stringArray(clientInfo.redirectUris);
+  if (clientSecret !== undefined) storedClient.clientSecret = clientSecret;
+  if (clientIdIssuedAt !== undefined) storedClient.clientIdIssuedAt = clientIdIssuedAt;
+  if (clientSecretExpiresAt !== undefined) storedClient.clientSecretExpiresAt = clientSecretExpiresAt;
+  if (redirectUris !== undefined) storedClient.redirectUris = redirectUris;
+  if (issuer !== undefined) storedClient.issuer = issuer;
+  if (configPreRegistered !== undefined) storedClient.configPreRegistered = configPreRegistered;
+  return storedClient;
+}
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function optionalString(value: unknown): string | null | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === 'string' ? value : null;
+}
+
+function optionalNumber(value: unknown): number | null | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === 'number' ? value : null;
+}
+
+function optionalBoolean(value: unknown): boolean | null | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === 'boolean' ? value : null;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every(uri => typeof uri === 'string') ? value : undefined;
 }
 
 function isAuthEntryChunkManifest(value: unknown): value is AuthEntryChunkManifest {

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.1",
+  "version": "2.22.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;
@@ -525,10 +526,28 @@ export function executeSearch(
 
   const page = paginate(matches, offset, limit);
   if (page.total === 0) {
+    const connectingServers = server
+      ? state.config.mcpServers[server] && state.manager.isConnecting(server) ? [server] : []
+      : Object.keys(state.config.mcpServers)
+        .filter(name => !isServerDisabled(state.config.mcpServers[name]) && state.manager.isConnecting(name))
+        .sort((a, b) => a.localeCompare(b));
     const msg = server ? `No tools matching "${query}" in "${server}"` : `No tools matching "${query}"`;
+    const connectingMessage = connectingServers.length === 1
+      ? ` Server "${connectingServers[0]}" is still connecting; retry in a moment.`
+      : connectingServers.length > 1
+        ? ` Servers ${connectingServers.map(name => `"${name}"`).join(", ")} are still connecting; retry in a moment.`
+        : "";
     return {
-      content: [{ type: "text" as const, text: msg }],
-      details: { mode: "search", matches: [], count: 0, hasMore: false, nextOffset: null, query },
+      content: [{ type: "text" as const, text: `${msg}${connectingMessage}` }],
+      details: {
+        mode: "search",
+        matches: [],
+        count: 0,
+        hasMore: false,
+        nextOffset: null,
+        query,
+        ...(connectingServers.length > 0 ? { connectingServers } : {}),
+      },
     };
   }
 
@@ -1094,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,
@@ -1104,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,
@@ -1147,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 });
@@ -1157,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 });
@@ -1176,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 });
@@ -1186,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/server-manager.ts

@@ -1030,6 +1030,10 @@ export class McpServerManager {
     return false;
   }
 
+  isConnecting(name: string): boolean {
+    return this.connectPromises.has(name);
+  }
+
   getConnection(name: string): ServerConnection | undefined {
     return this.connections.get(name);
   }

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;
 }

package/ui-resource-handler.ts

@@ -179,10 +179,10 @@ function extractUiMeta(meta: Record<string, unknown> | undefined): UiResourceMet
 
   const ui = isRecord(meta.ui) ? meta.ui : undefined;
   const out: UiResourceMeta = {};
-  const openAiCsp = hasOwnProperty(meta, "openai/widgetCSP")
+  const openAiCsp = Object.hasOwn(meta, "openai/widgetCSP")
     ? normalizeOpenAiWidgetCsp(meta["openai/widgetCSP"])
     : undefined;
-  const hasStandardCsp = !!ui && hasOwnProperty(ui, "csp");
+  const hasStandardCsp = !!ui && Object.hasOwn(ui, "csp");
   const standardCspValue = hasStandardCsp ? ui.csp : undefined;
 
   if (hasStandardCsp && !isRecord(standardCspValue)) {
@@ -196,7 +196,7 @@ function extractUiMeta(meta: Record<string, unknown> | undefined): UiResourceMet
       out.csp = { ...openAiCsp, ...standardCsp };
       if (isRecord(standardCspValue)) {
         for (const [, standardField] of OPENAI_CSP_FIELD_MAPPINGS) {
-          if (hasOwnProperty(standardCspValue, standardField) && !copyStringArray(standardCspValue[standardField])) {
+          if (Object.hasOwn(standardCspValue, standardField) && !copyStringArray(standardCspValue[standardField])) {
             delete out.csp[standardField];
           }
         }
@@ -245,10 +245,6 @@ function copyStringArray(value: unknown): string[] | undefined {
     : undefined;
 }
 
-function hasOwnProperty(record: Record<string, unknown>, property: string): boolean {
-  return Object.prototype.hasOwnProperty.call(record, property);
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }