@herbertgao/pi-extensions 2026.8.1 → 2026.8.3

package/node_modules/pi-mcp-adapter/tool-approval.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import { abortable } from "./abort.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import type { McpExtensionState } from "./state.ts";
@@ -5,7 +6,12 @@ import {
   getToolNameCandidates,
   matchesToolPattern,
   resolveToolPrefix,
+  MCP_TOOL_APPROVAL_REQUEST_EVENT,
   type McpConfig,
+  type McpToolApprovalDecision,
+  type McpToolApprovalHandler,
+  type McpToolApprovalOrigin,
+  type McpToolApprovalRequest,
   type ToolMetadata,
 } from "./types.ts";
 import { sanitizeTerminalText } from "./utils.ts";
@@ -34,19 +40,76 @@ export function isToolCallApprovalRequired(
   );
 }
 
+function isMcpToolApprovalDecision(value: unknown): value is McpToolApprovalDecision {
+  return value === "allow_once"
+    || value === "allow_for_session"
+    || value === "deny"
+    || value === "abstain";
+}
+
+async function requestBrokerApproval(
+  state: McpExtensionState,
+  serverName: string,
+  toolMeta: ToolMetadata,
+  args: Record<string, unknown> | undefined,
+  origin: McpToolApprovalOrigin,
+  signal?: AbortSignal,
+): Promise<McpToolApprovalDecision> {
+  if (!state.approvalEvents) return "abstain";
+
+  let acceptingClaim = true;
+  let handler: McpToolApprovalHandler | undefined;
+  const request: McpToolApprovalRequest = {
+    requestId: randomUUID(),
+    serverName,
+    originalToolName: toolMeta.originalName,
+    prefixedToolName: toolMeta.name,
+    args: args ?? {},
+    origin,
+    ...(signal !== undefined ? { signal } : {}),
+    claim(candidate: McpToolApprovalHandler) {
+      if (!acceptingClaim || handler) return false;
+      handler = candidate;
+      return true;
+    },
+  };
+
+  state.approvalEvents.emit(MCP_TOOL_APPROVAL_REQUEST_EVENT, request);
+  acceptingClaim = false;
+  if (!handler) return "abstain";
+
+  try {
+    const decision = await abortable(Promise.resolve().then(handler), signal);
+    return isMcpToolApprovalDecision(decision) ? decision : "deny";
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    return "deny";
+  }
+}
+
 export async function ensureToolCallApproved(
   state: McpExtensionState,
   serverName: string,
   toolMeta: ToolMetadata,
   args: Record<string, unknown> | undefined,
   signal?: AbortSignal,
+  origin: McpToolApprovalOrigin = toolMeta.resourceUri ? "resource" : "proxy",
 ): Promise<ToolCallApprovalResult> {
-  if (!isToolCallApprovalRequired(state.config, serverName, toolMeta)) {
+  const cacheKey = `${serverName}\u0000${toolMeta.originalName}`;
+  const approvedToolCalls = state.approvedToolCalls ??= new Map<string, true>();
+  if (approvedToolCalls.has(cacheKey)) {
     return { ok: true };
   }
 
-  const cacheKey = `${serverName}\u0000${toolMeta.originalName}`;
-  if (state.approvedToolCalls.has(cacheKey)) {
+  const brokerDecision = await requestBrokerApproval(state, serverName, toolMeta, args, origin, signal);
+  if (brokerDecision === "allow_once") return { ok: true };
+  if (brokerDecision === "allow_for_session") {
+    approvedToolCalls.set(cacheKey, true);
+    return { ok: true };
+  }
+  if (brokerDecision === "deny") return { ok: false, reason: "denied" };
+
+  if (!isToolCallApprovalRequired(state.config, serverName, toolMeta)) {
     return { ok: true };
   }
 
@@ -71,7 +134,7 @@ export async function ensureToolCallApproved(
     return { ok: true };
   }
   if (decision === "Allow for session") {
-    state.approvedToolCalls.set(cacheKey, true);
+    approvedToolCalls.set(cacheKey, true);
     return { ok: true };
   }
   return { ok: false, reason: "denied" };

package/node_modules/pi-mcp-adapter/tool-metadata.ts

@@ -1,4 +1,4 @@
-import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { getToolUiResourceUri } from "./ui-app-bridge-helpers.ts";
 import type { McpExtensionState } from "./state.ts";
 import type { ToolMetadata, McpTool, McpResource, ServerEntry, ToolPrefix } from "./types.ts";
 import { formatToolName, isToolAllowed, resolveToolPrefix } from "./types.ts";
@@ -44,14 +44,15 @@ export function buildToolMetadata(
     } catch {
       failedTools.push(tool.name);
     }
+    const uiStreamMode = extractToolUiStreamMode(tool._meta);
     metadata.push({
       name,
       originalName: tool.name,
       description: tool.description ?? "",
-      inputSchema: tool.inputSchema,
-      uiResourceUri,
-      uiVisibility,
-      uiStreamMode: extractToolUiStreamMode(tool._meta),
+      ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+      ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
+      ...(uiVisibility !== undefined ? { uiVisibility } : {}),
+      ...(uiStreamMode !== undefined ? { uiStreamMode } : {}),
     });
   }
 

package/node_modules/pi-mcp-adapter/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/node_modules/pi-mcp-adapter/tool-result-renderer.ts

@@ -41,6 +41,7 @@ class CollapsibleText implements Component {
   private readonly fullText: Text;
   private readonly footerText: Text;
   private collapsedText: { charBudget: number; fullyIncluded: boolean; text: Text } | null = null;
+  private collapsedRender: { width: number; charBudget: number; lines: string[] } | null = null;
 
   constructor(
     private readonly text: string,
@@ -70,18 +71,29 @@ class CollapsibleText implements Component {
         fullyIncluded: prefix === this.text,
         text: new Text(prefix, 0, 0),
       };
+      this.collapsedRender = null;
     }
 
     const lines = this.collapsedText.text.render(width);
     if (!this.preTruncated && this.collapsedText.fullyIncluded && lines.length <= this.maxCollapsedLines) return lines;
+    if (this.collapsedRender?.width === width && this.collapsedRender.charBudget === charBudget) {
+      return this.collapsedRender.lines;
+    }
 
-    return [
+    const rendered = [
       ...lines.slice(0, this.maxCollapsedLines),
       ...this.footerText.render(width),
     ];
+    this.collapsedRender = { width, charBudget, lines: rendered };
+    return rendered;
   }
 
-  invalidate(): void {}
+  invalidate(): void {
+    this.fullText.invalidate();
+    this.footerText.invalidate();
+    this.collapsedText?.text.invalidate();
+    this.collapsedRender = null;
+  }
 }
 
 function truncateText(value: string, maxChars: number): string {

package/node_modules/pi-mcp-adapter/ts-shape.ts

@@ -39,7 +39,10 @@ export function renderTsShape(inputSchema: unknown): string | null {
         if (typeof schema.$ref !== "string") return null;
         const match = schema.$ref.match(/^#\/(\$defs|definitions)\/([^/]+)$/);
         if (!match) return null;
-        const definitionKey = `${match[1]}/${decodePointerToken(match[2])}`;
+        const definitionGroup = match[1];
+        const definitionName = match[2];
+        if (definitionGroup === undefined || definitionName === undefined) return null;
+        const definitionKey = `${definitionGroup}/${decodePointerToken(definitionName)}`;
         if (!definitions.has(definitionKey)) return null;
         return aliasFor(definitionKey);
       }
@@ -108,7 +111,11 @@ function isSchema(value: unknown): value is Schema {
 }
 
 function hasUnsupportedKeyword(schema: Schema): boolean {
-  return UNSUPPORTED_KEYWORDS.some(keyword => Object.hasOwn(schema, keyword));
+  return UNSUPPORTED_KEYWORDS.some(keyword => {
+    if (!Object.hasOwn(schema, keyword)) return false;
+    // `additionalProperties: false` is a closed-object constraint, not a shape that this renderer needs to understand.
+    return keyword !== "additionalProperties" || schema.additionalProperties !== false;
+  });
 }
 
 function decodePointerToken(token: string): string {

package/node_modules/pi-mcp-adapter/types.ts

@@ -1,6 +1,11 @@
 // types.ts - Core type definitions
-import type { Transport as McpTransport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { ContentBlock as McpContentBlock } from "@modelcontextprotocol/sdk/types.js";
+import type {
+  ContentBlock as McpContentBlock,
+  ListPromptsResult,
+  ListResourcesResult,
+  ListToolsResult,
+  Transport as McpTransport,
+} from "@modelcontextprotocol/client";
 import type { TextContent, ImageContent } from "@earendil-works/pi-ai";
 import type { UiStreamMode } from "./ui-stream-types.ts";
 import type { UiToolVisibility } from "./ui-tool-visibility.ts";
@@ -48,36 +53,41 @@ export type ImportKind =
   | "windsurf" 
   | "vscode";
 
-// Tool definition from MCP server
+type SdkTool = ListToolsResult["tools"][number];
+type SdkResource = ListResourcesResult["resources"][number];
+type SdkPrompt = ListPromptsResult["prompts"][number];
+type SdkPromptArgument = NonNullable<SdkPrompt["arguments"]>[number];
+
+// MCP wire definitions derive their field types from the installed SDK while
+// retaining the adapter's deliberately smaller public surface.
 export interface McpTool {
-  name: string;
-  title?: string;
-  description?: string;
-  inputSchema?: unknown; // JSON Schema
-  _meta?: Record<string, unknown>;
+  name: SdkTool["name"];
+  title?: SdkTool["title"];
+  description?: SdkTool["description"];
+  inputSchema?: SdkTool["inputSchema"]; // JSON Schema
+  _meta?: SdkTool["_meta"];
 }
 
-// Resource definition from MCP server
 export interface McpResource {
-  uri: string;
-  name: string;
-  description?: string;
-  mimeType?: string;
-  _meta?: Record<string, unknown>;
+  uri: SdkResource["uri"];
+  name: SdkResource["name"];
+  description?: SdkResource["description"];
+  mimeType?: SdkResource["mimeType"];
+  _meta?: SdkResource["_meta"];
 }
 
 export interface McpPromptArgument {
-  name: string;
-  description?: string;
-  required?: boolean;
+  name: SdkPromptArgument["name"];
+  description?: SdkPromptArgument["description"];
+  required?: SdkPromptArgument["required"];
 }
 
 export interface McpPrompt {
-  name: string;
-  title?: string;
-  description?: string;
-  arguments?: McpPromptArgument[];
-  _meta?: Record<string, unknown>;
+  name: SdkPrompt["name"];
+  title?: SdkPrompt["title"];
+  description?: SdkPrompt["description"];
+  arguments?: SdkPrompt["arguments"];
+  _meta?: SdkPrompt["_meta"];
 }
 
 export interface UiResourceMeta {
@@ -340,6 +350,10 @@ 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;
 }
 
 // Server configuration
@@ -387,6 +401,20 @@ export interface ServerEntry {
   debug?: boolean;  // Show server stderr (default: false)
   /** Enable metadata-only JSONL protocol tracing for this server. */
   trace?: boolean;
+  /** Force a specific HTTP MCP transport. Used by Agent Plugins, whose `type` declares the transport and forbids client fallback. */
+  httpTransport?: "streamable-http" | "sse";
+  /** Client-managed persistent data directory for Agent Plugin stdio servers. */
+  pluginDataDir?: string;
+  /** Treat env values as already resolved literals. Used for Agent Plugin env rules. */
+  literalEnv?: boolean;
+  /**
+   * MCP protocol era negotiation for this server. Defaults to `"legacy"`
+   * (byte-equivalent to pre-2026 behavior — no `versionNegotiation` is sent).
+   * `"auto"` offers the SDK's default 2026-07-28+ modern versions with
+   * legacy fallback; `"2026-07-28"` pins the connection to that revision
+   * with no fallback. `auto` and `2026-07-28` must be set explicitly.
+   */
+  protocolVersion?: "legacy" | "auto" | "2026-07-28";
   // Keep configuration visible without allowing connections or execution.
   disabled?: boolean;
 }
@@ -422,6 +450,23 @@ export interface McpTraceSettings {
   maxEvents?: number;
 }
 
+export const MCP_TOOL_APPROVAL_REQUEST_EVENT = "pi-mcp-adapter:tool-approval-request" as const;
+
+export type McpToolApprovalOrigin = "proxy" | "direct" | "script" | "resource" | "iframe";
+export type McpToolApprovalDecision = "allow_once" | "allow_for_session" | "deny" | "abstain";
+export type McpToolApprovalHandler = () => McpToolApprovalDecision | Promise<McpToolApprovalDecision>;
+
+export interface McpToolApprovalRequest {
+  requestId: string;
+  serverName: string;
+  originalToolName: string;
+  prefixedToolName: string;
+  args: Record<string, unknown>;
+  origin: McpToolApprovalOrigin;
+  signal?: AbortSignal;
+  claim(handler: McpToolApprovalHandler): boolean;
+}
+
 export interface McpSettings {
   toolPrefix?: ToolPrefix;
   /** Show the plug prefix in MCP status and connection text (default: true). Set to false to disable it. */
@@ -430,6 +475,8 @@ export interface McpSettings {
   mcpFooterStatus?: McpFooterStatus;
   /** Discover detected host-specific MCP configs only when explicitly enabled. */
   hostConfigDiscovery?: HostConfigDiscovery;
+  /** Agent Plugin package directories to load MCP servers from. */
+  agentPluginPaths?: string[];
   idleTimeout?: number; // minutes, default 10, 0 to disable
   requestTimeoutMs?: number; // milliseconds, overrides the SDK request timeout when > 0
   directTools?: boolean;
@@ -622,6 +669,48 @@ export function resolveToolPrefix(
   return definition?.toolPrefix ?? globalPrefix ?? "server";
 }
 
+
+/**
+ * Resolve a configured MCP server name from a prefixed tool name.
+ *
+ * When the proxy tool is addressed with a fully-qualified name such as
+ * `searxng_searxng_web_search`, downstream policy systems (for example a
+ * permission gate) need to recover the owning server so they can evaluate
+ * server-scoped rules against the bare server name. This performs the inverse
+ * of {@link getServerPrefix}: it finds the longest configured server prefix
+ * that the tool name starts with and returns that server's name.
+ *
+ * @param toolName - the tool name as passed to the proxy `mcp({ tool })` call.
+ * @param serverNames - the configured MCP server names (keys of `mcpServers`).
+ * @param prefix - the active tool-prefix mode.
+ * @returns the resolved server name, or `undefined` when no prefix matches or
+ *   the prefix mode is `"none"`.
+ */
+export function resolveServerFromToolName(
+  toolName: string,
+  serverNames: Iterable<string>,
+  prefix: ToolPrefix,
+): string | undefined {
+  if (prefix === "none") return undefined;
+  const candidates: { name: string; prefix: string }[] = [];
+  for (const name of serverNames) {
+    const p = getServerPrefix(name, prefix);
+    if (p && toolName.startsWith(p + "_")) candidates.push({ name, prefix: p });
+  }
+  if (candidates.length === 0) return undefined;
+  candidates.sort((a, b) => b.prefix.length - a.prefix.length);
+  const best = candidates[0];
+  // Fail safe: two distinct server names can normalize to the same prefix
+  // (e.g. my-server and my_server both -> my_server under "server" mode).
+  // When that happens the owning server is ambiguous; return undefined so a
+  // downstream permission gate falls back to its existing wildcard path rather
+  // than enforcing a rule against the wrong server.
+  if (candidates.some((c) => c.prefix === best!.prefix && c.name !== best!.name)) {
+    return undefined;
+  }
+  return best?.name;
+}
+
 export function sanitizePromptName(name: string): string {
   const cleaned = name.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^[_-]+|[_-]+$/g, "");
   if (!cleaned) return "prompt";

package/node_modules/pi-mcp-adapter/ui-app-bridge-helpers.ts

@@ -0,0 +1,40 @@
+import type { UiResourcePermissions } from "./types.ts";
+
+export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+
+const RESOURCE_URI_META_KEY = "ui/resourceUri";
+
+export function getToolUiResourceUri(tool: { _meta?: Record<string, unknown> | undefined }): string | undefined {
+  const meta = tool._meta;
+  let resourceUri = getNestedResourceUri(meta);
+  if (resourceUri === undefined) {
+    resourceUri = meta?.[RESOURCE_URI_META_KEY];
+  }
+
+  if (typeof resourceUri === "string" && resourceUri.startsWith("ui://")) {
+    return resourceUri;
+  }
+
+  if (resourceUri !== undefined) {
+    throw new Error(`Invalid UI resource URI: ${JSON.stringify(resourceUri)}`);
+  }
+
+  return undefined;
+}
+
+export function buildAllowAttribute(permissions: UiResourcePermissions | undefined): string {
+  if (!permissions) return "";
+
+  const allowed: string[] = [];
+  if (permissions.camera) allowed.push("camera");
+  if (permissions.microphone) allowed.push("microphone");
+  if (permissions.geolocation) allowed.push("geolocation");
+  if (permissions.clipboardWrite) allowed.push("clipboard-write");
+  return allowed.join("; ");
+}
+
+function getNestedResourceUri(meta: Record<string, unknown> | undefined): unknown {
+  const ui = meta?.ui;
+  if (!ui || typeof ui !== "object") return undefined;
+  return (ui as Record<string, unknown>).resourceUri;
+}