@ulearning/ai-sdk 0.0.0-stage → 1.0.0-next.0

package/src/mcp-apps/bridge.ts

@@ -0,0 +1,538 @@
+import type { SandboxHostFrame } from "../sandbox-host/SandboxHost";
+import { invokeUserCallback } from "@ulearning/ai-core/internal";
+import {
+  MCP_APP_PROTOCOL_VERSION,
+  type McpAppBridgeHandlers,
+  type McpAppDisplayMode,
+  type McpAppHostContext,
+  type McpAppHostInfo,
+  type McpAppInitializeParams,
+  type McpAppJsonRpcMessage,
+  type McpAppJsonRpcNotification,
+  type McpAppJsonRpcRequest,
+  type McpAppJsonRpcResponse,
+} from "./types";
+import { isRecord } from "@ulearning/ai-core/internal";
+
+const VALID_DISPLAY_MODES = [
+  "inline",
+  "fullscreen",
+  "pip",
+] as const satisfies readonly McpAppDisplayMode[];
+
+function isMcpAppDisplayMode(value: unknown): value is McpAppDisplayMode {
+  return VALID_DISPLAY_MODES.some((mode) => mode === value);
+}
+
+function isAppInfo(
+  value: unknown,
+): value is NonNullable<McpAppInitializeParams["appInfo"]> {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    typeof value.version === "string"
+  );
+}
+
+function getAppCapabilities(
+  value: unknown,
+): McpAppInitializeParams["appCapabilities"] {
+  if (!isRecord(value)) return undefined;
+  const { availableDisplayModes, ...rest } = value;
+  return {
+    ...rest,
+    // Object.values reads only the entries present, so a sparse list claiming a huge length stays cheap, and the list's own methods are never called.
+    ...(Array.isArray(availableDisplayModes)
+      ? {
+          availableDisplayModes: Object.values(availableDisplayModes).filter(
+            isMcpAppDisplayMode,
+          ),
+        }
+      : {}),
+  };
+}
+
+function getInitializeParams(params: unknown): McpAppInitializeParams {
+  if (!isRecord(params)) return {};
+  const appCapabilities = getAppCapabilities(params.appCapabilities);
+  return {
+    ...(isAppInfo(params.appInfo) ? { appInfo: params.appInfo } : {}),
+    ...(appCapabilities ? { appCapabilities } : {}),
+    ...(typeof params.protocolVersion === "string"
+      ? { protocolVersion: params.protocolVersion }
+      : {}),
+  };
+}
+
+export type McpAppBridgeFrame = SandboxHostFrame;
+
+export type CreateMcpAppBridgeOptions = {
+  frame: McpAppBridgeFrame;
+  handlers?: McpAppBridgeHandlers | undefined;
+  hostInfo?: McpAppHostInfo | undefined;
+  hostContext?: McpAppHostContext | undefined;
+};
+
+export type McpAppBridge = {
+  onMessage: (event: MessageEvent) => void;
+  dispose: () => void;
+  notifyToolInput: (input: unknown) => void;
+  notifyToolResult: (result: unknown) => void;
+  notifyHostContextChanged: (hostContext: McpAppHostContext) => void;
+};
+
+const DEFAULT_HOST_INFO: McpAppHostInfo = {
+  name: "assistant-ui",
+  version: "0.1",
+};
+
+// Accept both the legacy method names and the MCP-UI 2026-01-26 names that
+// `ui/*` capable widgets (e.g. xmcp's host-bridge) emit. Normalize on input
+// so downstream switch statements only need to know the legacy names.
+const METHOD_ALIASES: Record<string, string> = {
+  "ui/notifications/initialized": "notifications/initialized",
+  "ui/notifications/size-changed": "notifications/size_changed",
+  "ui/request-display-mode": "requestDisplayMode",
+  "ui/open-link": "openLink",
+  "ui/update-model-context": "updateModelContext",
+  "ui/message": "sendMessage",
+  "notifications/message": "notifications/log",
+};
+
+const normalizeMethod = (method: string): string =>
+  METHOD_ALIASES[method] ?? method;
+
+const JSONRPC_ERROR = {
+  parseError: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internalError: -32603,
+} as const;
+
+function isJsonRpcMessage(value: unknown): value is McpAppJsonRpcMessage {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return v.jsonrpc === "2.0" && typeof v.method === "string";
+}
+
+function isRequest(msg: McpAppJsonRpcMessage): msg is McpAppJsonRpcRequest {
+  return "id" in msg;
+}
+
+function isNotification(
+  msg: McpAppJsonRpcMessage,
+): msg is McpAppJsonRpcNotification {
+  return !("id" in msg);
+}
+
+export function createMcpAppBridge(
+  opts: CreateMcpAppBridgeOptions,
+): McpAppBridge {
+  const {
+    frame,
+    handlers = {},
+    hostInfo = DEFAULT_HOST_INFO,
+    hostContext = {},
+  } = opts;
+  let disposed = false;
+  let initializeParams: McpAppInitializeParams = {};
+
+  const post = (msg: McpAppJsonRpcMessage) => {
+    if (disposed) return;
+    frame.sendMessage(msg);
+  };
+
+  const respond = (
+    id: McpAppJsonRpcRequest["id"],
+    payload:
+      | { result: unknown }
+      | { error: { code: number; message: string; data?: unknown } },
+  ) => {
+    const res: McpAppJsonRpcResponse = {
+      jsonrpc: "2.0",
+      id,
+      ...payload,
+    };
+    post(res);
+  };
+
+  const errorResponse = (
+    id: McpAppJsonRpcRequest["id"],
+    code: number,
+    message: string,
+    data?: unknown,
+  ) => {
+    respond(id, {
+      error: {
+        code,
+        message,
+        ...(data !== undefined ? { data } : {}),
+      },
+    });
+  };
+
+  const reportError = (error: Error) => {
+    if (disposed) return;
+    invokeUserCallback(
+      "assistant-ui",
+      "MCP App onError",
+      handlers.onError?.bind(handlers),
+      error,
+    );
+  };
+
+  const handleRequest = async (req: McpAppJsonRpcRequest) => {
+    try {
+      const params = req.params;
+
+      switch (normalizeMethod(req.method)) {
+        case "ui/initialize": {
+          initializeParams = getInitializeParams(params);
+          const requestedProtocolVersion =
+            initializeParams.protocolVersion ?? MCP_APP_PROTOCOL_VERSION;
+          respond(req.id, {
+            result: {
+              protocolVersion: requestedProtocolVersion,
+              host: hostInfo,
+              hostInfo,
+              hostContext,
+              capabilities: {
+                tools: handlers.callTool ? {} : undefined,
+                resources:
+                  handlers.readResource || handlers.listResources
+                    ? {}
+                    : undefined,
+                ui: {
+                  sendMessage: !!handlers.sendMessage,
+                  openLink: !!handlers.openLink,
+                  requestDisplayMode: !!handlers.requestDisplayMode,
+                  updateModelContext: !!handlers.updateModelContext,
+                },
+              },
+              hostCapabilities: {
+                ...(handlers.openLink ? { openLinks: {} } : {}),
+                ...(handlers.callTool ? { serverTools: {} } : {}),
+                ...(handlers.readResource || handlers.listResources
+                  ? { serverResources: {} }
+                  : {}),
+                ...(handlers.updateModelContext
+                  ? { updateModelContext: { text: {} } }
+                  : {}),
+                ...(handlers.sendMessage ? { message: { text: {} } } : {}),
+                ...(handlers.onLog ? { logging: {} } : {}),
+              },
+            },
+          });
+          return;
+        }
+
+        case "tools/call": {
+          if (!handlers.callTool) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.methodNotFound,
+              "tools/call is not supported by this host",
+            );
+            return;
+          }
+          const callParams = (params ?? {}) as {
+            name?: unknown;
+            arguments?: unknown;
+          };
+          if (typeof callParams.name !== "string") {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.invalidParams,
+              "tools/call requires a string 'name'",
+            );
+            return;
+          }
+          if (
+            handlers.allowedTools &&
+            !handlers.allowedTools.includes(callParams.name)
+          ) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.invalidParams,
+              `tool '${callParams.name}' is not allowed for this app`,
+            );
+            return;
+          }
+          let callArgs: Record<string, unknown> | undefined;
+          if (callParams.arguments !== undefined) {
+            if (
+              callParams.arguments === null ||
+              typeof callParams.arguments !== "object" ||
+              Array.isArray(callParams.arguments)
+            ) {
+              errorResponse(
+                req.id,
+                JSONRPC_ERROR.invalidParams,
+                "tools/call 'arguments' must be an object",
+              );
+              return;
+            }
+            callArgs = callParams.arguments as Record<string, unknown>;
+          }
+          const result = await handlers.callTool({
+            name: callParams.name,
+            ...(callArgs !== undefined ? { arguments: callArgs } : {}),
+          });
+          respond(req.id, { result });
+          return;
+        }
+
+        case "resources/read": {
+          if (!handlers.readResource) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.methodNotFound,
+              "resources/read is not supported by this host",
+            );
+            return;
+          }
+          const readParams = (params ?? {}) as { uri?: unknown };
+          if (typeof readParams.uri !== "string") {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.invalidParams,
+              "resources/read requires a string 'uri'",
+            );
+            return;
+          }
+          respond(req.id, {
+            result: await handlers.readResource({ uri: readParams.uri }),
+          });
+          return;
+        }
+
+        case "resources/list": {
+          if (!handlers.listResources) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.methodNotFound,
+              "resources/list is not supported by this host",
+            );
+            return;
+          }
+          respond(req.id, {
+            result: (await handlers.listResources(params)) ?? null,
+          });
+          return;
+        }
+
+        case "openLink": {
+          if (!handlers.openLink) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.methodNotFound,
+              "openLink is not supported by this host",
+            );
+            return;
+          }
+          const linkParams = (params ?? {}) as { url?: unknown };
+          if (typeof linkParams.url !== "string") {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.invalidParams,
+              "openLink requires a string 'url'",
+            );
+            return;
+          }
+          let linkProtocol: string;
+          try {
+            linkProtocol = new URL(linkParams.url).protocol;
+          } catch {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.invalidParams,
+              "openLink requires a valid URL",
+            );
+            return;
+          }
+          if (linkProtocol !== "https:" && linkProtocol !== "http:") {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.invalidParams,
+              "openLink only accepts http(s) URLs",
+            );
+            return;
+          }
+          respond(req.id, {
+            result: await handlers.openLink({ url: linkParams.url }),
+          });
+          return;
+        }
+
+        case "sendMessage": {
+          if (!handlers.sendMessage) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.methodNotFound,
+              "sendMessage is not supported by this host",
+            );
+            return;
+          }
+          respond(req.id, {
+            result: (await handlers.sendMessage(params)) ?? null,
+          });
+          return;
+        }
+
+        case "updateModelContext": {
+          if (!handlers.updateModelContext) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.methodNotFound,
+              "updateModelContext is not supported by this host",
+            );
+            return;
+          }
+          respond(req.id, {
+            result: (await handlers.updateModelContext(params)) ?? null,
+          });
+          return;
+        }
+
+        case "requestDisplayMode": {
+          if (!handlers.requestDisplayMode) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.methodNotFound,
+              "requestDisplayMode is not supported by this host",
+            );
+            return;
+          }
+          const modeParams = (params ?? {}) as { mode?: unknown };
+          if (!isMcpAppDisplayMode(modeParams.mode)) {
+            errorResponse(
+              req.id,
+              JSONRPC_ERROR.invalidParams,
+              "requestDisplayMode requires a valid 'mode'",
+            );
+            return;
+          }
+          respond(req.id, {
+            result: await handlers.requestDisplayMode({
+              mode: modeParams.mode,
+            }),
+          });
+          return;
+        }
+
+        default: {
+          errorResponse(
+            req.id,
+            JSONRPC_ERROR.methodNotFound,
+            `Unknown method: ${req.method}`,
+          );
+        }
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      reportError(error);
+      errorResponse(req.id, JSONRPC_ERROR.internalError, error.message);
+    }
+  };
+
+  const handleNotification = (note: McpAppJsonRpcNotification) => {
+    try {
+      switch (normalizeMethod(note.method)) {
+        case "notifications/initialized": {
+          handlers.onInitialized?.(initializeParams);
+          return;
+        }
+        case "notifications/size_changed": {
+          const p = (note.params ?? {}) as { width?: number; height?: number };
+          handlers.onSizeChange?.({
+            ...(typeof p.width === "number" ? { width: p.width } : {}),
+            ...(typeof p.height === "number" ? { height: p.height } : {}),
+          });
+          return;
+        }
+        case "notifications/log": {
+          handlers.onLog?.(note.params);
+          return;
+        }
+        case "notifications/request_teardown": {
+          handlers.onRequestTeardown?.(note.params);
+          return;
+        }
+        case "notifications/error": {
+          const p = (note.params ?? {}) as { message?: string };
+          reportError(
+            new Error(
+              typeof p.message === "string" ? p.message : "Widget error",
+            ),
+          );
+          return;
+        }
+        default:
+          return;
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      reportError(error);
+    }
+  };
+
+  // The host applies the cross-origin guard before delegating; this only
+  // validates the JSON-RPC envelope.
+  const onMessage = (event: MessageEvent) => {
+    if (disposed) return;
+    if (!isJsonRpcMessage(event.data)) return;
+
+    const msg = event.data;
+    if (isRequest(msg)) {
+      void handleRequest(msg);
+    } else if (isNotification(msg)) {
+      handleNotification(msg);
+    }
+  };
+
+  return {
+    onMessage,
+    dispose: () => {
+      disposed = true;
+    },
+    notifyToolInput: (input: unknown) => {
+      post({
+        jsonrpc: "2.0",
+        method: "notifications/tools/call/input",
+        params: { input },
+      });
+      post({
+        jsonrpc: "2.0",
+        method: "ui/notifications/tool-input",
+        params: isRecord(input) ? { arguments: input } : {},
+      });
+    },
+    notifyToolResult: (result: unknown) => {
+      post({
+        jsonrpc: "2.0",
+        method: "notifications/tools/call/result",
+        params: { result },
+      });
+      post({
+        jsonrpc: "2.0",
+        method: "ui/notifications/tool-result",
+        params: isRecord(result)
+          ? result
+          : { content: [{ type: "text", text: String(result) }] },
+      });
+    },
+    notifyHostContextChanged: (ctx: McpAppHostContext) => {
+      post({
+        jsonrpc: "2.0",
+        method: "notifications/host_context/changed",
+        params: ctx,
+      });
+      post({
+        jsonrpc: "2.0",
+        method: "ui/notifications/host-context-changed",
+        params: ctx,
+      });
+    },
+  };
+}

package/src/mcp-apps/csp.test.ts

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { applyMcpAppCsp, buildMcpAppCsp } from "./csp";
+
+const getPolicyMeta = (html: string) =>
+  new DOMParser()
+    .parseFromString(applyMcpAppCsp(html), "text/html")
+    .head.querySelector('meta[http-equiv="Content-Security-Policy"]');
+
+const expectPolicyBeforeScript = (html: string) => {
+  const policyIndex = html.indexOf("Content-Security-Policy");
+  const scriptIndex = html.indexOf("<script");
+  expect(policyIndex).toBeGreaterThanOrEqual(0);
+  expect(scriptIndex).toBeGreaterThanOrEqual(0);
+  expect(policyIndex).toBeLessThan(scriptIndex);
+};
+
+describe("MCP App CSP", () => {
+  it("uses restrictive defaults when the resource omits CSP metadata", () => {
+    expect(buildMcpAppCsp()).toBe(
+      "default-src 'none'; " +
+        "script-src 'self' 'unsafe-inline'; " +
+        "style-src 'self' 'unsafe-inline'; " +
+        "connect-src 'none'; " +
+        "img-src 'self' data:; " +
+        "font-src 'self'; " +
+        "media-src 'self' data:; " +
+        "frame-src 'none'; " +
+        "base-uri 'self'; " +
+        "object-src 'none'; " +
+        "form-action 'none'",
+    );
+  });
+
+  it("allows only valid declared origins", () => {
+    const policy = buildMcpAppCsp({
+      connectDomains: [
+        "https://api.example",
+        "wss://events.example:8443",
+        "https://api.example; default-src *",
+      ],
+      resourceDomains: ["https://*.cdn.example", "wss://assets.example"],
+      frameDomains: ["https://video.example/path"],
+      baseUriDomains: ["https://base.example"],
+    });
+
+    expect(policy.split("; ")).toContain(
+      "connect-src 'self' https://api.example wss://events.example:8443",
+    );
+    expect(
+      buildMcpAppCsp({
+        resourceDomains: ["https://*.cdn.example", "wss://assets.example"],
+      }),
+    ).toContain("script-src 'self' 'unsafe-inline' https://*.cdn.example");
+    expect(
+      buildMcpAppCsp({ resourceDomains: ["wss://assets.example"] }),
+    ).toContain("script-src 'self' 'unsafe-inline';");
+    expect(
+      buildMcpAppCsp({ frameDomains: ["https://video.example/path"] }),
+    ).toContain("frame-src 'none'");
+    expect(
+      buildMcpAppCsp({ baseUriDomains: ["https://base.example"] }),
+    ).toContain("base-uri https://base.example");
+  });
+
+  it("falls back to the restrictive policy for malformed metadata", () => {
+    expect(
+      buildMcpAppCsp({
+        connectDomains: "https://api.example" as unknown as string[],
+      }),
+    ).toContain("connect-src 'none'");
+  });
+
+  it("places the policy after a doctype and before executable content", () => {
+    const html =
+      '\uFEFF<!-- license --><!doctype html><script src="https://cdn.example/app.js"></script>';
+    const secured = applyMcpAppCsp(html);
+
+    expect(secured.startsWith("<!-- license --><!doctype html><meta ")).toBe(
+      true,
+    );
+    expectPolicyBeforeScript(secured);
+  });
+
+  it.each([
+    "<!--><script>run()</script>-->",
+    "<!---><script>run()</script>",
+    "<!-- license --!><script>run()</script>",
+  ])("places the policy before scripts after HTML comment closers", (html) => {
+    expectPolicyBeforeScript(applyMcpAppCsp(html));
+  });
+
+  it.each([
+    '<?xml version="1.0"?><!doctype html><script>run()</script>',
+    "<!foo><!doctype html><script>run()</script>",
+  ])("preserves standards mode after leading bogus comments", (html) => {
+    const secured = applyMcpAppCsp(html);
+    const document = new DOMParser().parseFromString(secured, "text/html");
+
+    expect(secured.indexOf("<!doctype html><meta ")).toBeGreaterThan(0);
+    expect(document.compatMode).toBe("CSS1Compat");
+    expectPolicyBeforeScript(secured);
+  });
+
+  it.each([
+    "\u00a0<script>run()</script>",
+    "\uFEFF\uFEFF<script>run()</script>",
+  ])("keeps the policy in head before non-HTML whitespace", (html) => {
+    expect(getPolicyMeta(html)).not.toBeNull();
+  });
+});