sailfork / t3code-github / packages/ shared/ src/ mcpApp.ts

import * as Predicate from "effect/Predicate";

export const MCP_APP_PROTOCOL_VERSION = "2026-01-26";
export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
export const MCP_APP_EXTENSION_ID = "io.modelcontextprotocol/ui";
export const MCP_APP_RESOURCE_SCHEME = "ui://";
export const MCP_APP_OUTPUT_KEY = "t3McpApp";

const MCP_APP_MIN_HEIGHT = 80;
export const MCP_APP_DEFAULT_HEIGHT = 320;
export const MCP_APP_MAX_HEIGHT = 2000;
export const MCP_APP_MAX_HTML_BYTES = 5 * 1024 * 1024;
const MAX_DOMAINS = 32;
const MAX_DOMAIN_LENGTH = 256;
const MAX_NAME_LENGTH = 256;
const MAX_RESOURCE_URI_LENGTH = 4096;

export interface McpAppCsp {
  readonly connectDomains?: ReadonlyArray<string>;
  readonly resourceDomains?: ReadonlyArray<string>;
  readonly frameDomains?: ReadonlyArray<string>;
  readonly baseUriDomains?: ReadonlyArray<string>;
}

export interface McpAppPermissions {
  readonly camera?: Record<string, never>;
  readonly microphone?: Record<string, never>;
  readonly geolocation?: Record<string, never>;
  readonly clipboardWrite?: Record<string, never>;
}

export interface McpAppReference {
  readonly attachmentId: string;
  readonly server: string;
  readonly tool: string;
  readonly resourceUri: string;
  readonly csp?: McpAppCsp;
  readonly permissions?: McpAppPermissions;
  readonly prefersBorder?: boolean;
}

// Accept only scheme-qualified origins with optional subdomain wildcards to prevent policy widening.
const DOMAIN_PATTERN = /^(?:https?|wss?):\/\/(?:\*\.)?[a-z0-9-]+(?:\.[a-z0-9-]+)*(?::\d{1,5})?$/i;

function readDomains(value: unknown): ReadonlyArray<string> | undefined {
  if (!Array.isArray(value)) return undefined;
  const domains = value
    .filter(
      (domain): domain is string =>
        typeof domain === "string" &&
        domain.length <= MAX_DOMAIN_LENGTH &&
        DOMAIN_PATTERN.test(domain),
    )
    .slice(0, MAX_DOMAINS);
  return domains.length === 0 ? undefined : domains;
}

export function readMcpAppCsp(value: unknown): McpAppCsp | undefined {
  if (!Predicate.isObject(value)) return undefined;
  const csp: {
    connectDomains?: ReadonlyArray<string>;
    resourceDomains?: ReadonlyArray<string>;
    frameDomains?: ReadonlyArray<string>;
    baseUriDomains?: ReadonlyArray<string>;
  } = {};
  for (const key of [
    "connectDomains",
    "resourceDomains",
    "frameDomains",
    "baseUriDomains",
  ] as const) {
    const domains = readDomains(value[key]);
    if (domains !== undefined) csp[key] = domains;
  }
  return Object.keys(csp).length === 0 ? undefined : csp;
}

const PERMISSION_KEYS = ["camera", "microphone", "geolocation", "clipboardWrite"] as const;

export function readMcpAppPermissions(value: unknown): McpAppPermissions | undefined {
  if (!Predicate.isObject(value)) return undefined;
  const permissions: Partial<Record<(typeof PERMISSION_KEYS)[number], Record<string, never>>> = {};
  for (const key of PERMISSION_KEYS) {
    if (Predicate.isObject(value[key])) permissions[key] = {};
  }
  return Object.keys(permissions).length === 0 ? undefined : permissions;
}

const boundedName = (value: unknown) =>
  typeof value === "string" && value.trim() !== "" && value.length <= MAX_NAME_LENGTH
    ? value
    : undefined;

export function readMcpAppReference(value: unknown): McpAppReference | undefined {
  if (!Predicate.isObject(value)) return undefined;
  const attachmentId = boundedName(value.attachmentId);
  const server = boundedName(value.server);
  const tool = boundedName(value.tool);
  const resourceUri =
    typeof value.resourceUri === "string" && value.resourceUri.length <= MAX_RESOURCE_URI_LENGTH
      ? value.resourceUri
      : undefined;
  if (
    attachmentId === undefined ||
    server === undefined ||
    tool === undefined ||
    resourceUri === undefined ||
    !resourceUri.startsWith(MCP_APP_RESOURCE_SCHEME)
  ) {
    return undefined;
  }
  const csp = readMcpAppCsp(value.csp);
  const permissions = readMcpAppPermissions(value.permissions);
  return {
    attachmentId,
    server,
    tool,
    resourceUri,
    ...(csp === undefined ? {} : { csp }),
    ...(permissions === undefined ? {} : { permissions }),
    ...(typeof value.prefersBorder === "boolean" ? { prefersBorder: value.prefersBorder } : {}),
  };
}

export function mcpAppReferencesEqual(left: McpAppReference, right: McpAppReference): boolean {
  return (
    left.attachmentId === right.attachmentId &&
    left.server === right.server &&
    left.tool === right.tool &&
    left.resourceUri === right.resourceUri
  );
}

/** Reads a tool's `_meta.ui.resourceUri`, or the deprecated flat `ui/resourceUri`. */
export function mcpAppToolResourceUri(meta: unknown): string | undefined {
  if (!Predicate.isObject(meta)) return undefined;
  const uri =
    (Predicate.isObject(meta.ui) ? meta.ui.resourceUri : undefined) ?? meta["ui/resourceUri"];
  return typeof uri === "string" &&
    uri.length <= MAX_RESOURCE_URI_LENGTH &&
    uri.startsWith(MCP_APP_RESOURCE_SCHEME)
    ? uri
    : undefined;
}

export const claudeMcpToolNamePart = (name: string) => name.replace(/[^a-zA-Z0-9_-]/g, "_");

/** Claude Code's `mcp__<server>__` prefix; it also collapses and trims `_` in `claude.ai ` connector names. */
export function claudeMcpToolPrefix(server: string): string {
  const part = claudeMcpToolNamePart(server);
  return `mcp__${server.startsWith("claude.ai ") ? part.replace(/_+/g, "_").replace(/^_|_$/g, "") : part}__`;
}

/** Claude Code names MCP tools `mcp__<server>__<tool>`, replacing characters outside `[a-zA-Z0-9_-]`. */
export function claudeMcpToolName(server: string, tool: string): string {
  return `${claudeMcpToolPrefix(server)}${claudeMcpToolNamePart(tool)}`;
}

export function mcpAppToolCallableByApp(meta: unknown): boolean {
  const visibility =
    Predicate.isObject(meta) && Predicate.isObject(meta.ui) ? meta.ui.visibility : undefined;
  return !Array.isArray(visibility) || visibility.includes("app");
}

/** Block undeclared origins, including self, which would expose T3's API. */
export function mcpAppContentSecurityPolicy(csp: McpAppCsp | undefined): string {
  const resources = csp?.resourceDomains?.join(" ") ?? "";
  const list = (domains: ReadonlyArray<string> | undefined, fallback: string) =>
    domains === undefined || domains.length === 0 ? fallback : domains.join(" ");
  return [
    "default-src 'none'",
    `script-src 'unsafe-inline' ${resources}`.trim(),
    `style-src 'unsafe-inline' ${resources}`.trim(),
    `img-src data: blob: ${resources}`.trim(),
    `font-src data: ${resources}`.trim(),
    `media-src data: blob: ${resources}`.trim(),
    `connect-src ${list(csp?.connectDomains, "'none'")}`,
    `frame-src ${list(csp?.frameDomains, "'none'")}`,
    "object-src 'none'",
    `base-uri ${list(csp?.baseUriDomains, "'none'")}`,
    "form-action 'none'",
  ].join("; ");
}

const escapeAttribute = (value: string) =>
  value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");

/** The route's sandbox header keeps origins opaque; the document CSP can only tighten it. */
export function injectMcpAppCsp(html: string, csp: McpAppCsp | undefined): string {
  const meta = `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(
    mcpAppContentSecurityPolicy(csp),
  )}">`;
  // Insert after the doctype to preserve standards mode; the parser moves it into the head.
  const doctype = /^\uFEFF?\s*<!doctype[^>]*>/i.exec(html);
  return doctype
    ? `${doctype[0]}${meta}${html.slice(doctype[0].length)}`
    : `<!doctype html>${meta}${html}`;
}

/** Opaque origins require authenticating bridge messages by parent window. */
export function injectMcpAppThemeBootstrap(html: string): string {
  const script = `<script>
(() => {
  window.addEventListener("message", (event) => {
    if (event.source !== window.parent) return;
    const message = event.data;
    if (!message || message.jsonrpc !== "2.0") return;
    const theme = message.method === "ui/notifications/host-context-changed"
      ? message.params?.theme
      : message.id !== undefined && message.method === undefined
        ? message.result?.hostContext?.theme
        : undefined;
    if (theme === "light" || theme === "dark") {
      document.documentElement.style.colorScheme = theme;
    }
  });
})();
</script>`;
  const prefix =
    /^\uFEFF?\s*<!doctype[^>]*>\s*(?:<meta\s+http-equiv="Content-Security-Policy"[^>]*>)?/i.exec(
      html,
    );
  return prefix
    ? `${prefix[0]}${script}${html.slice(prefix[0].length)}`
    : `<!doctype html>${script}${html}`;
}

/** Opaque documents throw on cookie reads; analytics startup often expects an empty string instead. */
export function injectMcpAppCookieBootstrap(html: string): string {
  const bootstrap = `<script>(function(){try{void document.cookie;}catch(error){if(error&&error.name==="SecurityError"){Object.defineProperty(document,"cookie",{configurable:true,get:function(){return "";},set:function(){}});}}})();</script>`;
  // Preserve captured CSP ahead of executable code, including this bootstrap.
  const prefix =
    /^(?:\uFEFF?\s*<!doctype[^>]*>\s*)?(?:<meta http-equiv="Content-Security-Policy" content="[^"]*">)?/i.exec(
      html,
    )![0];
  return `${prefix}${bootstrap}${html.slice(prefix.length)}`;
}

export function mcpAppAllowAttribute(permissions: McpAppPermissions | undefined): string {
  const features: Array<string> = [];
  if (permissions?.camera) features.push("camera");
  if (permissions?.microphone) features.push("microphone");
  if (permissions?.geolocation) features.push("geolocation");
  if (permissions?.clipboardWrite) features.push("clipboard-write");
  return features.join("; ");
}

export function clampMcpAppHeight(height: number): number {
  if (!Number.isFinite(height)) return MCP_APP_DEFAULT_HEIGHT;
  return Math.round(Math.min(MCP_APP_MAX_HEIGHT, Math.max(MCP_APP_MIN_HEIGHT, height)));
}

export function mcpAppFileName(reference: McpAppReference): string {
  const name = reference.tool.replace(/[^\w.-]+/g, "-").slice(0, 80) || "app";
  return `${name}.html`;
}