@docyrus/docyrus 0.0.19 → 0.0.21

package/resources/pi-agent/extensions/pi-mcp-adapter/types.ts

@@ -0,0 +1,367 @@
+// types.ts - Core type definitions
+import type { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { TextContent, ImageContent } from "@mariozechner/pi-ai";
+
+// Transport type (stdio + HTTP)
+export type Transport = 
+  | StdioClientTransport 
+  | SSEClientTransport 
+  | StreamableHTTPClientTransport;
+
+// Import sources for config
+export type ImportKind = 
+  | "cursor" 
+  | "claude-code" 
+  | "claude-desktop" 
+  | "codex" 
+  | "windsurf" 
+  | "vscode";
+
+// Tool definition from MCP server
+export interface McpTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown; // JSON Schema
+  _meta?: Record<string, unknown>;
+}
+
+// Resource definition from MCP server
+export interface McpResource {
+  uri: string;
+  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
+export interface McpContent {
+  type: "text" | "image" | "audio" | "resource" | "resource_link";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  resource?: {
+    uri: string;
+    text?: string;
+    blob?: string;
+  };
+  uri?: string;
+  name?: string;
+  description?: string;
+}
+
+// Pi content block type
+export type ContentBlock = TextContent | ImageContent;
+
+// Server configuration
+export interface ServerEntry {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  // HTTP fields
+  url?: string;
+  headers?: Record<string, string>;
+  auth?: "oauth" | "bearer";
+  bearerToken?: string;
+  bearerTokenEnv?: string;
+  lifecycle?: "keep-alive" | "lazy" | "eager";
+  idleTimeout?: number; // minutes, overrides global setting
+  // Resource handling
+  exposeResources?: boolean;
+  // Direct tool registration
+  directTools?: boolean | string[];
+  // Debug
+  debug?: boolean;  // Show server stderr (default: false)
+}
+
+// Settings
+export interface McpSettings {
+  toolPrefix?: "server" | "none" | "short";
+  idleTimeout?: number; // minutes, default 10, 0 to disable
+  directTools?: boolean;
+}
+
+// Root config
+export interface McpConfig {
+  mcpServers: Record<string, ServerEntry>;
+  imports?: ImportKind[];
+  settings?: McpSettings;
+}
+
+// Alias for clarity
+export type ServerDefinition = ServerEntry;
+
+export interface ToolMetadata {
+  name: string;           // Prefixed tool name (e.g., "xcodebuild_list_sims")
+  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 {
+  serverName: string;
+  originalName: string;
+  prefixedName: string;
+  description: string;
+  inputSchema?: unknown;
+  resourceUri?: string;
+  uiResourceUri?: string;
+  uiStreamMode?: UiStreamMode;
+}
+
+export interface ServerProvenance {
+  path: string;
+  kind: "user" | "project" | "import";
+  importKind?: string;
+}
+
+export interface McpPanelCallbacks {
+  reconnect: (serverName: string) => Promise<boolean>;
+  getConnectionStatus: (serverName: string) => "connected" | "idle" | "failed" | "needs-auth";
+  refreshCacheAfterReconnect: (serverName: string) => import("./metadata-cache.js").ServerCacheEntry | null;
+}
+
+export interface McpPanelResult {
+  changes: Map<string, true | string[] | false>;
+  cancelled: boolean;
+}
+
+/**
+ * Get server prefix based on tool prefix mode.
+ */
+export function getServerPrefix(
+  serverName: string,
+  mode: "server" | "none" | "short"
+): string {
+  if (mode === "none") return "";
+  if (mode === "short") {
+    let short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+    if (!short) short = "mcp";
+    return short;
+  }
+  return serverName.replace(/-/g, "_");
+}
+
+/**
+ * Format a tool name with server prefix.
+ */
+export function formatToolName(
+  toolName: string,
+  serverName: string,
+  prefix: "server" | "none" | "short"
+): string {
+  const p = getServerPrefix(serverName, prefix);
+  return p ? `${p}_${toolName}` : toolName;
+}

package/resources/pi-agent/extensions/pi-mcp-adapter/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;
+}