pi-mcp-adapter 2.1.2 → 2.2.0

package/errors.ts

@@ -0,0 +1,219 @@
+/**
+ * Custom error types for MCP UI operations.
+ * Provides structured errors with context and recovery hints.
+ */
+
+export interface McpUiErrorContext {
+  server?: string;
+  tool?: string;
+  uri?: string;
+  session?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Base error class for MCP UI errors.
+ */
+export class McpUiError extends Error {
+  readonly code: string;
+  readonly context: McpUiErrorContext;
+  readonly recoveryHint?: string;
+  readonly cause?: Error;
+
+  constructor(
+    message: string,
+    options: {
+      code: string;
+      context?: McpUiErrorContext;
+      recoveryHint?: string;
+      cause?: Error;
+    }
+  ) {
+    super(message);
+    this.name = "McpUiError";
+    this.code = options.code;
+    this.context = options.context ?? {};
+    this.recoveryHint = options.recoveryHint;
+    this.cause = options.cause;
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      context: this.context,
+      recoveryHint: this.recoveryHint,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Error fetching a UI resource from the MCP server.
+ */
+export class ResourceFetchError extends McpUiError {
+  constructor(
+    uri: string,
+    reason: string,
+    options?: { server?: string; cause?: Error }
+  ) {
+    super(`Failed to fetch UI resource "${uri}": ${reason}`, {
+      code: "RESOURCE_FETCH_ERROR",
+      context: { uri, server: options?.server },
+      recoveryHint: "Check that the MCP server is connected and the resource URI is valid.",
+      cause: options?.cause,
+    });
+    this.name = "ResourceFetchError";
+  }
+}
+
+/**
+ * Error parsing or validating UI resource content.
+ */
+export class ResourceParseError extends McpUiError {
+  constructor(
+    uri: string,
+    reason: string,
+    options?: { server?: string; mimeType?: string }
+  ) {
+    super(`Invalid UI resource "${uri}": ${reason}`, {
+      code: "RESOURCE_PARSE_ERROR",
+      context: { uri, server: options?.server, mimeType: options?.mimeType },
+      recoveryHint: "Ensure the resource returns valid HTML with the correct MIME type.",
+    });
+    this.name = "ResourceParseError";
+  }
+}
+
+/**
+ * Error connecting to the AppBridge.
+ */
+export class BridgeConnectionError extends McpUiError {
+  constructor(reason: string, options?: { session?: string; cause?: Error }) {
+    super(`AppBridge connection failed: ${reason}`, {
+      code: "BRIDGE_CONNECTION_ERROR",
+      context: { session: options?.session },
+      recoveryHint: "Check browser console for detailed errors. The iframe may have failed to load.",
+      cause: options?.cause,
+    });
+    this.name = "BridgeConnectionError";
+  }
+}
+
+/**
+ * Error related to user consent for tool calls.
+ */
+export class ConsentError extends McpUiError {
+  readonly denied: boolean;
+
+  constructor(
+    server: string,
+    options: { denied?: boolean; requiresApproval?: boolean }
+  ) {
+    const message = options.denied
+      ? `Tool calls for "${server}" were denied for this session`
+      : `Tool call approval required for "${server}"`;
+
+    super(message, {
+      code: options.denied ? "CONSENT_DENIED" : "CONSENT_REQUIRED",
+      context: { server },
+      recoveryHint: options.denied
+        ? "The user denied tool access. Start a new session to try again."
+        : "Prompt the user for consent before calling tools.",
+    });
+    this.name = "ConsentError";
+    this.denied = options.denied ?? false;
+  }
+}
+
+/**
+ * Error with UI server session management.
+ */
+export class SessionError extends McpUiError {
+  constructor(
+    reason: string,
+    options?: { session?: string; cause?: Error }
+  ) {
+    super(`Session error: ${reason}`, {
+      code: "SESSION_ERROR",
+      context: { session: options?.session },
+      recoveryHint: "The session may have expired or been closed. Try opening the UI again.",
+      cause: options?.cause,
+    });
+    this.name = "SessionError";
+  }
+}
+
+/**
+ * Error starting or operating the UI server.
+ */
+export class ServerError extends McpUiError {
+  constructor(
+    reason: string,
+    options?: { port?: number; cause?: Error }
+  ) {
+    super(`UI server error: ${reason}`, {
+      code: "SERVER_ERROR",
+      context: { port: options?.port },
+      recoveryHint: "Check if the port is available. Another process may be using it.",
+      cause: options?.cause,
+    });
+    this.name = "ServerError";
+  }
+}
+
+/**
+ * Error communicating with the MCP server.
+ */
+export class McpServerError extends McpUiError {
+  constructor(
+    server: string,
+    reason: string,
+    options?: { tool?: string; cause?: Error }
+  ) {
+    super(`MCP server "${server}" error: ${reason}`, {
+      code: "MCP_SERVER_ERROR",
+      context: { server, tool: options?.tool },
+      recoveryHint: "Check that the MCP server is running and responsive.",
+      cause: options?.cause,
+    });
+    this.name = "McpServerError";
+  }
+}
+
+/**
+ * Wrap an unknown error into an McpUiError.
+ */
+export function wrapError(error: unknown, context?: McpUiErrorContext): McpUiError {
+  if (error instanceof McpUiError) {
+    // Merge contexts
+    return new McpUiError(error.message, {
+      code: error.code,
+      context: { ...error.context, ...context },
+      recoveryHint: error.recoveryHint,
+      cause: error.cause,
+    });
+  }
+
+  const cause = error instanceof Error ? error : undefined;
+  const message = error instanceof Error ? error.message : String(error);
+
+  return new McpUiError(message, {
+    code: "UNKNOWN_ERROR",
+    context,
+    cause,
+  });
+}
+
+/**
+ * Check if an error is a specific MCP UI error type.
+ */
+export function isErrorCode(error: unknown, code: string): boolean {
+  return error instanceof McpUiError && error.code === code;
+}

package/glimpse-ui.ts

@@ -0,0 +1,80 @@
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { platform } from "node:os";
+import { createRequire } from "node:module";
+
+let glimpseAvailable: boolean | null = null;
+let resolvedBinaryPath: string | null = null;
+
+export function isGlimpseAvailable(): boolean {
+  if (glimpseAvailable !== null) return glimpseAvailable;
+
+  if (platform() !== "darwin") {
+    glimpseAvailable = false;
+    return false;
+  }
+
+  resolvedBinaryPath = getGlimpseBinaryPath();
+  glimpseAvailable = resolvedBinaryPath !== null;
+  return glimpseAvailable;
+}
+
+function getGlimpseBinaryPath(): string | null {
+  if (process.env.GLIMPSE_BINARY && existsSync(process.env.GLIMPSE_BINARY)) {
+    return process.env.GLIMPSE_BINARY;
+  }
+
+  // Local node_modules
+  try {
+    const require = createRequire(import.meta.url);
+    const glimpseuiPath = require.resolve("glimpseui");
+    const binaryPath = join(dirname(glimpseuiPath), "glimpse");
+    if (existsSync(binaryPath)) return binaryPath;
+  } catch {}
+
+  // Global npm install
+  try {
+    const globalRoot = execFileSync("npm", ["root", "-g"], { encoding: "utf-8" }).trim();
+    const binaryPath = join(globalRoot, "glimpseui", "src", "glimpse");
+    if (existsSync(binaryPath)) return binaryPath;
+  } catch {}
+
+  return null;
+}
+
+export async function openGlimpseWindow(
+  html: string,
+  options: {
+    title: string;
+    width?: number;
+    height?: number;
+    onClosed: () => void;
+  },
+) {
+  const modulePath = resolvedBinaryPath
+    ? join(dirname(resolvedBinaryPath), "glimpse.mjs")
+    : "glimpseui";
+  const glimpse = await import(modulePath);
+
+  let active = true;
+  const win = glimpse.open(html, {
+    width: options.width ?? 900,
+    height: options.height ?? 700,
+    title: options.title,
+  });
+
+  win.on("closed", () => {
+    if (!active) return;
+    active = false;
+    options.onClosed();
+  });
+
+  return {
+    close: () => {
+      if (!active) return;
+      active = false;
+      win.close();
+    },
+  };
+}