pi-mcp-adapter 2.1.2 → 2.2.0

package/server-manager.ts

@@ -1,11 +1,19 @@
-// server-manager.ts - MCP connection management (stdio + HTTP)
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
-import type { McpTool, McpResource, ServerDefinition, Transport } from "./types.js";
+import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import type {
+  McpTool,
+  McpResource,
+  ServerDefinition,
+  ServerStreamResultPatchNotification,
+  Transport,
+} from "./types.js";
+import { serverStreamResultPatchNotificationSchema } from "./types.js";
 import { getStoredTokens } from "./oauth-handler.js";
 import { resolveNpxBinary } from "./npx-resolver.js";
+import { logger } from "./logger.js";
 
 interface ServerConnection {
   client: Client;
@@ -18,9 +26,12 @@ interface ServerConnection {
   status: "connected" | "closed";
 }
 
+type UiStreamListener = (serverName: string, notification: ServerStreamResultPatchNotification["params"]) => void;
+
 export class McpServerManager {
   private connections = new Map<string, ServerConnection>();
   private connectPromises = new Map<string, Promise<ServerConnection>>();
+  private uiStreamListeners = new Map<string, UiStreamListener>();
   
   async connect(name: string, definition: ServerDefinition): Promise<ServerConnection> {
     // Dedupe concurrent connection attempts
@@ -64,7 +75,7 @@ export class McpServerManager {
         if (resolved) {
           command = resolved.isJs ? "node" : resolved.binPath;
           args = resolved.isJs ? [resolved.binPath, ...resolved.extraArgs] : resolved.extraArgs;
-          console.log(`MCP: ${name} resolved to ${resolved.binPath} (skipping npm parent)`);
+          logger.debug(`${name} resolved to ${resolved.binPath} (skipping npm parent)`);
         }
       }
 
@@ -84,6 +95,7 @@ export class McpServerManager {
     
     try {
       await client.connect(transport);
+      this.attachAdapterNotificationHandlers(name, client);
       
       // Discover tools and resources
       const [tools, resources] = await Promise.all([
@@ -190,6 +202,38 @@ export class McpServerManager {
       return [];
     }
   }
+
+  private attachAdapterNotificationHandlers(serverName: string, client: Client): void {
+    client.setNotificationHandler(serverStreamResultPatchNotificationSchema, (notification) => {
+      const listener = this.uiStreamListeners.get(notification.params.streamToken);
+      if (!listener) return;
+      listener(serverName, notification.params);
+    });
+  }
+
+  registerUiStreamListener(streamToken: string, listener: UiStreamListener): void {
+    this.uiStreamListeners.set(streamToken, listener);
+  }
+
+  removeUiStreamListener(streamToken: string): void {
+    this.uiStreamListeners.delete(streamToken);
+  }
+
+  async readResource(name: string, uri: string): Promise<ReadResourceResult> {
+    const connection = this.connections.get(name);
+    if (!connection || connection.status !== "connected") {
+      throw new Error(`Server "${name}" is not connected`);
+    }
+
+    try {
+      this.touch(name);
+      this.incrementInFlight(name);
+      return await connection.client.readResource({ uri });
+    } finally {
+      this.decrementInFlight(name);
+      this.touch(name);
+    }
+  }
   
   async close(name: string): Promise<void> {
     const connection = this.connections.get(name);
@@ -241,7 +285,7 @@ export class McpServerManager {
   isIdle(name: string, timeoutMs: number): boolean {
     const connection = this.connections.get(name);
     if (!connection || connection.status !== "connected") return false;
-    if (connection.inFlight && connection.inFlight > 0) return false;
+    if (connection.inFlight > 0) return false;
     return (Date.now() - connection.lastUsedAt) > timeoutMs;
   }
 }

package/state.ts

@@ -0,0 +1,41 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ConsentManager } from "./consent-manager.js";
+import type { McpLifecycleManager } from "./lifecycle.js";
+import type { McpServerManager } from "./server-manager.js";
+import type { ToolMetadata, McpConfig, UiSessionMessages, UiStreamSummary } from "./types.js";
+import type { UiResourceHandler } from "./ui-resource-handler.js";
+import type { UiServerHandle } from "./ui-server.js";
+
+export interface CompletedUiSession {
+  serverName: string;
+  toolName: string;
+  completedAt: Date;
+  reason: string;
+  messages: UiSessionMessages;
+  stream?: UiStreamSummary;
+}
+
+export type SendMessageFn = (
+  message: {
+    customType: string;
+    content: Array<{ type: string; text: string }>;
+    display?: string;
+    details?: unknown;
+  },
+  options?: { triggerTurn?: boolean }
+) => void;
+
+export interface McpExtensionState {
+  manager: McpServerManager;
+  lifecycle: McpLifecycleManager;
+  toolMetadata: Map<string, ToolMetadata[]>;
+  config: McpConfig;
+  failureTracker: Map<string, number>;
+  uiResourceHandler: UiResourceHandler;
+  consentManager: ConsentManager;
+  uiServer: UiServerHandle | null;
+  completedUiSessions: CompletedUiSession[];
+  openBrowser: (url: string) => Promise<void>;
+  ui?: ExtensionContext["ui"];
+  sendMessage?: SendMessageFn;
+}

package/tool-metadata.ts

@@ -0,0 +1,144 @@
+import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import type { McpExtensionState } from "./state.js";
+import type { ToolMetadata, McpTool, McpResource, ServerEntry } from "./types.js";
+import { formatToolName } from "./types.js";
+import { resourceNameToToolName } from "./resource-tools.js";
+import { extractToolUiStreamMode } from "./utils.js";
+
+export function buildToolMetadata(
+  tools: McpTool[],
+  resources: McpResource[],
+  definition: ServerEntry,
+  serverName: string,
+  prefix: "server" | "none" | "short"
+): { metadata: ToolMetadata[]; failedTools: string[] } {
+  const metadata: ToolMetadata[] = [];
+  const failedTools: string[] = [];
+
+  for (const tool of tools) {
+    if (!tool?.name) {
+      failedTools.push("(unnamed)");
+      continue;
+    }
+    let uiResourceUri: string | undefined;
+    try {
+      uiResourceUri = getToolUiResourceUri({ _meta: tool._meta });
+    } catch {
+      failedTools.push(tool.name);
+    }
+    metadata.push({
+      name: formatToolName(tool.name, serverName, prefix),
+      originalName: tool.name,
+      description: tool.description ?? "",
+      inputSchema: tool.inputSchema,
+      uiResourceUri,
+      uiStreamMode: extractToolUiStreamMode(tool._meta),
+    });
+  }
+
+  if (definition.exposeResources !== false) {
+    for (const resource of resources) {
+      const baseName = `get_${resourceNameToToolName(resource.name)}`;
+      metadata.push({
+        name: formatToolName(baseName, serverName, prefix),
+        originalName: baseName,
+        description: resource.description ?? `Read resource: ${resource.uri}`,
+        resourceUri: resource.uri,
+      });
+    }
+  }
+
+  return { metadata, failedTools };
+}
+
+export function getToolNames(state: McpExtensionState, serverName: string): string[] {
+  return state.toolMetadata.get(serverName)?.map(m => m.name) ?? [];
+}
+
+export function totalToolCount(state: McpExtensionState): number {
+  let count = 0;
+  for (const metadata of state.toolMetadata.values()) {
+    count += metadata.length;
+  }
+  return count;
+}
+
+export function findToolByName(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | undefined {
+  if (!metadata) return undefined;
+  const exact = metadata.find(m => m.name === toolName);
+  if (exact) return exact;
+  const normalized = toolName.replace(/-/g, "_");
+  return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
+}
+
+export function formatSchema(schema: unknown, indent = "  "): string {
+  if (!schema || typeof schema !== "object") {
+    return `${indent}(no schema)`;
+  }
+
+  const s = schema as Record<string, unknown>;
+
+  if (s.type === "object" && s.properties && typeof s.properties === "object") {
+    const props = s.properties as Record<string, unknown>;
+    const required = Array.isArray(s.required) ? s.required as string[] : [];
+
+    if (Object.keys(props).length === 0) {
+      return `${indent}(no parameters)`;
+    }
+
+    const lines: string[] = [];
+    for (const [name, propSchema] of Object.entries(props)) {
+      const isRequired = required.includes(name);
+      const propLine = formatProperty(name, propSchema, isRequired, indent);
+      lines.push(propLine);
+    }
+    return lines.join("\n");
+  }
+
+  if (s.type) {
+    return `${indent}(${s.type})`;
+  }
+
+  return `${indent}(complex schema)`;
+}
+
+function formatProperty(name: string, schema: unknown, required: boolean, indent: string): string {
+  if (!schema || typeof schema !== "object") {
+    return `${indent}${name}${required ? " *required*" : ""}`;
+  }
+
+  const s = schema as Record<string, unknown>;
+  const parts: string[] = [];
+
+  let typeStr = "";
+  if (s.type) {
+    if (Array.isArray(s.type)) {
+      typeStr = s.type.join(" | ");
+    } else {
+      typeStr = String(s.type);
+    }
+  } else if (s.enum) {
+    typeStr = "enum";
+  } else if (s.anyOf || s.oneOf) {
+    typeStr = "union";
+  }
+
+  if (Array.isArray(s.enum)) {
+    const enumVals = s.enum.map(v => JSON.stringify(v)).join(", ");
+    typeStr = `enum: ${enumVals}`;
+  }
+
+  parts.push(`${indent}${name}`);
+  if (typeStr) parts.push(`(${typeStr})`);
+  if (required) parts.push("*required*");
+
+  if (s.description && typeof s.description === "string") {
+    parts.push(`- ${s.description}`);
+  }
+
+  if (s.default !== undefined) {
+    parts.push(`[default: ${JSON.stringify(s.default)}]`);
+  }
+
+  return parts.join(" ");
+}

package/types.ts

@@ -25,6 +25,7 @@ export interface McpTool {
   title?: string;
   description?: string;
   inputSchema?: unknown; // JSON Schema
+  _meta?: Record<string, unknown>;
 }
 
 // Resource definition from MCP server
@@ -33,6 +34,212 @@ export interface McpResource {
   name: string;
   description?: string;
   mimeType?: string;
+  _meta?: Record<string, unknown>;
+}
+
+export interface UiResourceMeta {
+  csp?: UiResourceCsp;
+  permissions?: UiResourcePermissions;
+  domain?: string;
+  prefersBorder?: boolean;
+}
+
+export interface UiResourceContent {
+  uri: string;
+  html: string;
+  mimeType?: string;
+  meta: UiResourceMeta;
+}
+
+export interface UiProxyRequestBody<TParams> {
+  token: string;
+  params: TParams;
+}
+
+export interface UiProxyResult<T = Record<string, unknown>> {
+  ok: boolean;
+  result?: T;
+  error?: string;
+}
+
+export interface UiResourceCsp {
+  connectDomains?: string[];
+  scriptDomains?: string[];
+  styleDomains?: string[];
+  fontDomains?: string[];
+  imgDomains?: string[];
+  mediaDomains?: string[];
+  frameDomains?: string[];
+  workerDomains?: string[];
+  baseUriDomains?: string[];
+}
+
+export interface UiResourcePermissions {
+  camera?: {};
+  microphone?: {};
+  geolocation?: {};
+  clipboardWrite?: {};
+}
+
+export interface UiToolInfo {
+  id?: string | number;
+  tool: {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+  };
+}
+
+export interface UiHostContext {
+  toolInfo?: UiToolInfo;
+  theme?: "light" | "dark";
+  styles?: Record<string, unknown>;
+  displayMode?: UiDisplayMode;
+  availableDisplayModes?: UiDisplayMode[];
+  containerDimensions?: {
+    width?: number;
+    maxWidth?: number;
+    height?: number;
+    maxHeight?: number;
+  };
+  [key: string]: unknown;
+}
+
+export type UiDisplayMode = "inline" | "fullscreen" | "pip";
+
+// Re-export stream types from the shared lightweight module.
+// This allows the example package to import stream schemas without pulling the full types.ts dependency graph.
+export {
+  UI_STREAM_HOST_CONTEXT_KEY,
+  UI_STREAM_REQUEST_META_KEY,
+  UI_STREAM_RESULT_PATCH_METHOD,
+  SERVER_STREAM_RESULT_PATCH_METHOD,
+  UI_STREAM_STRUCTURED_CONTENT_KEY,
+  uiStreamModeSchema,
+  visualizationStreamPhaseSchema,
+  visualizationStreamFrameTypeSchema,
+  visualizationStreamStatusSchema,
+  uiStreamHostContextSchema,
+  visualizationStreamEnvelopeSchema,
+  uiStreamCallToolResultSchema,
+  uiStreamResultPatchNotificationSchema,
+  serverStreamResultPatchNotificationSchema,
+  getUiStreamHostContext,
+  getVisualizationStreamEnvelope,
+  type UiStreamMode,
+  type VisualizationStreamPhase,
+  type VisualizationStreamFrameType,
+  type VisualizationStreamStatus,
+  type UiStreamHostContext,
+  type VisualizationStreamEnvelope,
+  type UiStreamCallToolResult,
+  type UiStreamResultPatchNotification,
+  type ServerStreamResultPatchNotification,
+  type UiStreamSummary,
+} from "./ui-stream-types.js";
+
+export interface UiMessageParams {
+  role?: string;
+  content?: unknown[];
+  type?: "prompt" | "notify" | "intent" | "message";
+  message?: string;
+  prompt?: string;
+  intent?: string;
+  params?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Extract prompt text from either legacy MCP UI message shapes or native AppBridge user messages.
+ */
+export function extractUiPromptText(params: UiMessageParams): string | undefined {
+  if (params.type === "prompt" || params.prompt) {
+    const prompt = params.prompt ?? String(params.message ?? "");
+    return prompt || undefined;
+  }
+
+  if (params.role === "user" && Array.isArray(params.content)) {
+    const text = params.content
+      .map((block) => (block && typeof block === "object" && "text" in block ? String((block as { text?: unknown }).text ?? "") : ""))
+      .filter(Boolean)
+      .join("\n\n");
+    return text || undefined;
+  }
+
+  return undefined;
+}
+
+/**
+ * Structured UI handoff recovered from a canonical prompt envelope.
+ */
+export interface UiPromptHandoff {
+  intent: string;
+  params: Record<string, unknown>;
+  raw: string;
+}
+
+/**
+ * Parse a canonical named UI handoff encoded as `intent\n{json}`.
+ */
+export function parseUiPromptHandoff(prompt: string): UiPromptHandoff | undefined {
+  const newlineIndex = prompt.indexOf("\n");
+  if (newlineIndex <= 0) {
+    return undefined;
+  }
+
+  const intent = prompt.slice(0, newlineIndex).trim();
+  const payloadText = prompt.slice(newlineIndex + 1).trim();
+  if (!intent || !payloadText) {
+    return undefined;
+  }
+
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(intent)) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(payloadText);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return undefined;
+    }
+    return {
+      intent,
+      params: parsed as Record<string, unknown>,
+      raw: prompt,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Accumulated messages from a UI session.
+ * Collected during the session and available when it ends.
+ */
+export interface UiSessionMessages {
+  prompts: string[];
+  notifications: string[];
+  intents: Array<{ intent: string; params?: Record<string, unknown> }>;
+}
+
+export interface UiModelContextParams {
+  content?: unknown[];
+  structuredContent?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface UiOpenLinkResult {
+  isError?: boolean;
+  [key: string]: unknown;
+}
+
+export interface UiDisplayModeRequest {
+  mode?: UiDisplayMode;
+}
+
+export interface UiDisplayModeResult {
+  mode: UiDisplayMode;
+  [key: string]: unknown;
 }
 
 // Content types from MCP
@@ -98,7 +305,9 @@ export interface ToolMetadata {
   originalName: string;   // Original MCP tool name (e.g., "list_sims")
   description: string;
   resourceUri?: string;   // For resource tools: the URI to read
+  uiResourceUri?: string; // For app-enabled tools: the UI resource URI
   inputSchema?: unknown;  // JSON Schema for parameters (stored for describe/errors)
+  uiStreamMode?: UiStreamMode;
 }
 
 export interface DirectToolSpec {
@@ -108,6 +317,8 @@ export interface DirectToolSpec {
   description: string;
   inputSchema?: unknown;
   resourceUri?: string;
+  uiResourceUri?: string;
+  uiStreamMode?: UiStreamMode;
 }
 
 export interface ServerProvenance {

package/ui-resource-handler.ts

@@ -0,0 +1,145 @@
+import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/app-bridge";
+import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import { ResourceFetchError, ResourceParseError } from "./errors.js";
+import { logger } from "./logger.js";
+import type { McpServerManager } from "./server-manager.js";
+import type { UiResourceContent, UiResourceMeta } from "./types.js";
+
+interface ResourceContentRecord {
+  uri?: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+  _meta?: Record<string, unknown>;
+}
+
+export class UiResourceHandler {
+  private log = logger.child({ component: "UiResourceHandler" });
+
+  constructor(private manager: McpServerManager) {}
+
+  async readUiResource(serverName: string, uri: string): Promise<UiResourceContent> {
+    const log = this.log.child({ server: serverName, uri });
+
+    if (!uri.startsWith("ui://")) {
+      throw new ResourceParseError(uri, "URI must start with ui://", { server: serverName });
+    }
+
+    log.debug("Fetching UI resource");
+
+    let result: ReadResourceResult;
+    try {
+      result = await this.manager.readResource(serverName, uri);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log.error("Failed to read resource", error instanceof Error ? error : undefined);
+      throw new ResourceFetchError(uri, message, {
+        server: serverName,
+        cause: error instanceof Error ? error : undefined,
+      });
+    }
+
+    const content = selectContent(result, uri);
+    const mimeType = content.mimeType;
+
+    if (mimeType && !isHtmlMimeType(mimeType)) {
+      log.warn("Unsupported MIME type", { mimeType });
+      throw new ResourceParseError(
+        uri,
+        `unsupported MIME type "${mimeType}" (expected text/html or ${RESOURCE_MIME_TYPE})`,
+        { server: serverName, mimeType }
+      );
+    }
+
+    const html = toHtml(content);
+    if (!html.trim()) {
+      log.warn("Resource content is empty");
+      throw new ResourceParseError(uri, "content is empty", { server: serverName });
+    }
+
+    const contentMeta = extractUiMeta(content._meta);
+    const listMeta = extractUiMeta(this.getListResourceMeta(serverName, uri));
+
+    log.debug("Resource loaded successfully", { 
+      contentLength: html.length,
+      hasCsp: !!contentMeta.csp || !!listMeta.csp,
+    });
+
+    return {
+      uri: content.uri ?? uri,
+      html,
+      mimeType: mimeType ?? RESOURCE_MIME_TYPE,
+      meta: {
+        csp: contentMeta.csp ?? listMeta.csp,
+        permissions: contentMeta.permissions ?? listMeta.permissions,
+        domain: contentMeta.domain ?? listMeta.domain,
+        prefersBorder: contentMeta.prefersBorder ?? listMeta.prefersBorder,
+      },
+    };
+  }
+
+  private getListResourceMeta(serverName: string, uri: string): Record<string, unknown> | undefined {
+    const connection = this.manager.getConnection(serverName);
+    if (!connection?.resources?.length) return undefined;
+    const resource = connection.resources.find((entry) => entry.uri === uri);
+    if (!resource || !resource._meta || typeof resource._meta !== "object") return undefined;
+    return resource._meta;
+  }
+}
+
+function selectContent(result: ReadResourceResult, preferredUri: string): ResourceContentRecord {
+  const contents = (result.contents ?? []) as ResourceContentRecord[];
+  if (contents.length === 0) {
+    throw new Error(`No contents returned for UI resource: ${preferredUri}`);
+  }
+
+  const byUri = contents.find((content) => content.uri === preferredUri);
+  if (byUri) return byUri;
+
+  const byHtmlMime = contents.find(
+    (content) => content.mimeType && isHtmlMimeType(content.mimeType)
+  );
+  if (byHtmlMime) return byHtmlMime;
+
+  return contents[0];
+}
+
+function isHtmlMimeType(mimeType: string): boolean {
+  const normalized = mimeType.toLowerCase();
+  return normalized.startsWith("text/html") || normalized === RESOURCE_MIME_TYPE.toLowerCase();
+}
+
+function toHtml(content: ResourceContentRecord): string {
+  if (typeof content.text === "string") {
+    return content.text;
+  }
+
+  if (typeof content.blob === "string") {
+    return Buffer.from(content.blob, "base64").toString("utf-8");
+  }
+
+  throw new Error(`UI resource ${content.uri ?? "(unknown)"} did not include text or blob content`);
+}
+
+function extractUiMeta(meta: Record<string, unknown> | undefined): UiResourceMeta {
+  if (!meta || typeof meta !== "object") return {};
+  const ui = meta.ui as Record<string, unknown> | undefined;
+  if (!ui || typeof ui !== "object") return {};
+
+  const out: UiResourceMeta = {};
+
+  if (ui.csp && typeof ui.csp === "object") {
+    out.csp = ui.csp as UiResourceMeta["csp"];
+  }
+  if (ui.permissions && typeof ui.permissions === "object") {
+    out.permissions = ui.permissions as UiResourceMeta["permissions"];
+  }
+  if (typeof ui.domain === "string") {
+    out.domain = ui.domain;
+  }
+  if (typeof ui.prefersBorder === "boolean") {
+    out.prefersBorder = ui.prefersBorder;
+  }
+
+  return out;
+}