// @effect-diagnostics globalTimers:off - The bridge runs in the client, outside an Effect runtime.
import { MCP_APP_PROTOCOL_VERSION, type McpAppReference } from "@t3tools/shared/mcpApp";
import * as Base64 from "effect/encoding/Base64";
import * as Predicate from "effect/Predicate";
import * as Result from "effect/Result";
import * as Schema from "effect/Schema";
const MAX_MESSAGE_BYTES = 256 * 1024;
const MAX_PENDING_REQUESTS = 16;
const TEARDOWN_TIMEOUT_MS = 2000;
const encoder = new TextEncoder();
type JsonRpcId = string | number;
export type McpAppDisplayMode = "inline" | "fullscreen" | "pip";
export interface McpAppHostContext {
readonly theme: "light" | "dark";
readonly styles: { readonly variables: Readonly<Record<string, string>> };
readonly displayMode: McpAppDisplayMode;
readonly availableDisplayModes: ReadonlyArray<McpAppDisplayMode>;
/**
* `maxHeight` when the host sizes the frame to the app's reported height,
* `height` when the frame is a fixed box the app must fit (spec
* "Container Dimensions").
*/
readonly containerDimensions:
| { readonly width: number; readonly maxHeight: number }
| { readonly width: number; readonly height: number };
readonly platform: "web" | "desktop" | "mobile";
readonly locale?: string;
readonly timeZone?: string;
readonly userAgent?: string;
readonly deviceCapabilities?: { readonly touch?: boolean; readonly hover?: boolean };
readonly safeAreaInsets?: {
readonly top: number;
readonly right: number;
readonly bottom: number;
readonly left: number;
};
readonly toolInfo?: { readonly tool: unknown };
}
export type McpAppDownload =
| {
readonly _tag: "embedded";
readonly name: string;
readonly mimeType: string;
readonly bytes: Uint8Array;
}
| {
readonly _tag: "link";
readonly name: string;
readonly uri: string;
readonly mimeType?: string;
};
export function mcpResourceBytes(content: unknown): Uint8Array | undefined {
if (!Predicate.isObject(content)) return undefined;
if (typeof content.text === "string") return encoder.encode(content.text);
if (typeof content.blob === "string") {
const decoded = Base64.decode(content.blob);
return Result.isSuccess(decoded) ? decoded.success : undefined;
}
return undefined;
}
export interface McpAppCallToolResult {
readonly content: ReadonlyArray<unknown>;
readonly structuredContent?: unknown;
readonly isError?: boolean | undefined;
readonly _meta?: unknown;
}
export class McpAppHostRefusal extends Schema.TaggedError<McpAppHostRefusal>()(
"McpAppHostRefusal",
{ message: Schema.String },
) {}
const isMcpAppHostRefusal = Schema.is(McpAppHostRefusal);
export interface McpAppHostOptions {
readonly app: McpAppReference;
readonly hostVersion: string;
readonly post: (message: unknown) => void;
readonly hostContext: () => McpAppHostContext;
readonly callTool: (input: {
readonly name: string;
readonly arguments: Record<string, unknown>;
}) => Promise<McpAppCallToolResult>;
readonly readResource: (input: { readonly uri: string }) => Promise<unknown>;
readonly openLink: (url: string) => Promise<void>;
readonly sendMessage: (text: string) => Promise<void>;
/** Replaces what this app tells the agent on its next turn; undefined content clears it. */
readonly updateModelContext: (context: {
readonly content?: ReadonlyArray<unknown>;
readonly structuredContent?: Record<string, unknown>;
}) => Promise<void>;
readonly requestDisplayMode: (mode: McpAppDisplayMode) => Promise<McpAppDisplayMode>;
readonly downloadFile: (files: ReadonlyArray<McpAppDownload>) => Promise<void>;
readonly onRequestTeardown: () => void;
readonly onSizeChanged: (size: { readonly width?: number; readonly height?: number }) => void;
}
export interface McpAppHost {
/** Handles one message the app posted; the caller has already checked its source. */
readonly receive: (data: unknown) => void;
readonly setToolCall: (call: {
readonly arguments: unknown;
readonly result: McpAppCallToolResult | undefined;
}) => void;
readonly updateHostContext: () => void;
/**
* Asks the app to wrap up before its document goes away (`ui/resource-teardown`),
* resolving once it answers or after a short timeout, then disposes the host.
*/
readonly teardown: () => Promise<void>;
readonly dispose: () => void;
}
function jsonBytes(value: unknown): number {
try {
return encoder.encode(JSON.stringify(value) ?? "").byteLength;
} catch {
return Number.POSITIVE_INFINITY;
}
}
function isId(value: unknown): value is JsonRpcId {
return typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
}
/**
* Providers can report absent fields as null (Codex sends `_meta: null`), which
* the MCP Apps SDK rejects, dropping the whole notification or response.
*/
function normalizeMcpAppToolResult(result: McpAppCallToolResult): McpAppCallToolResult {
return {
content: Array.isArray(result.content) ? result.content : [],
...(Predicate.isObject(result.structuredContent)
? { structuredContent: result.structuredContent }
: {}),
...(result.isError === true ? { isError: true } : {}),
...(Predicate.isObject(result._meta) ? { _meta: result._meta } : {}),
};
}
const errorMessage = (error: unknown) =>
isMcpAppHostRefusal(error)
? error.message
: error instanceof Error && error.message.trim() !== ""
? error.message
: "Request failed.";
export function makeMcpAppHost(options: McpAppHostOptions): McpAppHost {
let initialized = false;
let disposed = false;
let toolCall:
| { readonly arguments: unknown; readonly result: McpAppCallToolResult | undefined }
| undefined;
let toolCallSent = false;
let pending = 0;
let sentContext: McpAppHostContext | undefined;
let appDisplayModes: ReadonlyArray<string> | undefined;
let nextHostRequestId = 0;
const hostRequests = new Map<string, () => void>();
const post = (message: unknown) => {
if (!disposed) options.post(message);
};
const notify = (method: string, params: unknown) => post({ jsonrpc: "2.0", method, params });
const respond = (id: JsonRpcId, result: unknown) => post({ jsonrpc: "2.0", id, result });
const fail = (id: JsonRpcId, code: number, message: string) =>
post({ jsonrpc: "2.0", id, error: { code, message } });
const sendToolCall = () => {
if (!initialized || toolCall === undefined || toolCallSent) return;
toolCallSent = true;
notify("ui/notifications/tool-input", {
arguments: Predicate.isObject(toolCall.arguments) ? toolCall.arguments : {},
});
if (toolCall.result !== undefined) {
notify("ui/notifications/tool-result", normalizeMcpAppToolResult(toolCall.result));
}
};
const answer = (id: JsonRpcId, run: () => Promise<unknown>) => {
if (pending >= MAX_PENDING_REQUESTS) {
fail(id, -32000, "Too many requests in flight.");
return;
}
pending += 1;
void run().then(
(result) => {
pending -= 1;
respond(id, result);
},
(error: unknown) => {
pending -= 1;
fail(id, -32000, errorMessage(error));
},
);
};
const handleRequest = (id: JsonRpcId, method: string, params: Record<PropertyKey, unknown>) => {
switch (method) {
case "ui/initialize": {
const requested = params.protocolVersion;
const declared = Predicate.isObject(params.appCapabilities)
? params.appCapabilities.availableDisplayModes
: undefined;
appDisplayModes = Array.isArray(declared)
? declared.filter((mode): mode is string => typeof mode === "string")
: undefined;
sentContext = options.hostContext();
respond(id, {
protocolVersion:
requested === MCP_APP_PROTOCOL_VERSION ? requested : MCP_APP_PROTOCOL_VERSION,
hostInfo: { name: "t3-code", version: options.hostVersion },
hostCapabilities: {
openLinks: {},
serverTools: {},
serverResources: {},
logging: {},
message: { text: {} },
updateModelContext: { text: {}, structuredContent: {} },
downloadFile: {},
sandbox: {
...(options.app.csp === undefined ? {} : { csp: options.app.csp }),
...(options.app.permissions === undefined
? {}
: { permissions: options.app.permissions }),
},
},
hostContext: sentContext,
});
return;
}
case "ping":
respond(id, {});
return;
case "tools/call": {
const name = params.name;
const args = params.arguments ?? {};
if (typeof name !== "string" || name.trim() === "" || !Predicate.isObject(args)) {
fail(id, -32602, "tools/call needs a tool name and object arguments.");
return;
}
answer(id, () =>
options
.callTool({ name, arguments: args as Record<string, unknown> })
.then(normalizeMcpAppToolResult),
);
return;
}
case "resources/read": {
const uri = params.uri;
if (typeof uri !== "string" || uri.trim() === "") {
fail(id, -32602, "resources/read needs a uri.");
return;
}
answer(id, () => options.readResource({ uri }));
return;
}
case "ui/open-link": {
const url = params.url;
if (typeof url !== "string" || !/^https?:\/\//i.test(url)) {
fail(id, -32602, "Only http(s) links can be opened.");
return;
}
answer(id, () => options.openLink(url).then(() => ({})));
return;
}
case "ui/message": {
// The SDK sends an array of content blocks; the spec text shows one block.
const blocks = Array.isArray(params.content) ? params.content : [params.content];
const texts = blocks.map((block) =>
Predicate.isObject(block) && block.type === "text" && typeof block.text === "string"
? block.text
: undefined,
);
if (params.role !== "user" || texts.length === 0 || texts.includes(undefined)) {
fail(id, -32602, "Only text messages from the user role are supported.");
return;
}
const text = texts.join("\n").trim();
if (text === "") {
fail(id, -32602, "ui/message needs non-empty text.");
return;
}
answer(id, () => options.sendMessage(text).then(() => ({})));
return;
}
case "ui/request-display-mode": {
const current = options.hostContext().displayMode;
const mode = params.mode;
// A mode the host lacks, or the app did not declare, leaves the
// current one; the spec has the host answer with whichever applies.
const allowed =
typeof mode === "string" &&
options.hostContext().availableDisplayModes.includes(mode as McpAppDisplayMode) &&
(appDisplayModes === undefined || appDisplayModes.includes(mode));
if (!allowed || mode === current) {
respond(id, { mode: current });
return;
}
answer(id, () =>
options
.requestDisplayMode(mode as McpAppDisplayMode)
.then((result) => ({ mode: result })),
);
return;
}
case "ui/update-model-context": {
const content = params.content;
const structured = params.structuredContent;
if (
(content !== undefined && !Array.isArray(content)) ||
(structured !== undefined && !Predicate.isObject(structured))
) {
fail(
id,
-32602,
"Model context needs content blocks or an object of structured content.",
);
return;
}
answer(id, () =>
options
.updateModelContext({
...(content === undefined ? {} : { content }),
...(structured === undefined
? {}
: { structuredContent: structured as Record<string, unknown> }),
})
.then(() => ({})),
);
return;
}
case "ui/download-file": {
const files = readDownloads(params.contents);
if (files === undefined) {
fail(id, -32602, "ui/download-file needs embedded resources or resource links.");
return;
}
answer(id, () =>
options.downloadFile(files).then(
() => ({}),
(error: unknown) =>
isMcpAppHostRefusal(error) ? { isError: true } : Promise.reject(error),
),
);
return;
}
default:
fail(id, -32601, `Method not found: ${method}`);
}
};
const handleNotification = (method: string, params: Record<PropertyKey, unknown>) => {
switch (method) {
case "ui/notifications/initialized": {
if (initialized) return;
initialized = true;
sendToolCall();
hostHandle.updateHostContext();
return;
}
case "ui/notifications/size-changed": {
const width = typeof params.width === "number" ? params.width : undefined;
const height = typeof params.height === "number" ? params.height : undefined;
if (width !== undefined || height !== undefined) {
options.onSizeChanged({
...(width === undefined ? {} : { width }),
...(height === undefined ? {} : { height }),
});
}
return;
}
case "ui/notifications/request-teardown":
options.onRequestTeardown();
return;
default:
}
};
const handleResponse = (id: JsonRpcId) => {
const settle = hostRequests.get(String(id));
if (settle === undefined) return;
hostRequests.delete(String(id));
settle();
};
const hostHandle: McpAppHost = {
receive: (data) => {
if (disposed || !Predicate.isObject(data) || data.jsonrpc !== "2.0") return;
if (jsonBytes(data) > MAX_MESSAGE_BYTES) {
if (isId(data.id) && typeof data.method === "string") {
fail(data.id, -32600, "Message too large.");
}
return;
}
const method = data.method;
if (typeof method !== "string") {
if (isId(data.id) && ("result" in data || "error" in data)) handleResponse(data.id);
return;
}
const params = Predicate.isObject(data.params) ? data.params : {};
if (isId(data.id)) handleRequest(data.id, method, params);
else handleNotification(method, params);
},
setToolCall: (call) => {
// A running call has no result yet; only its completion may replace it.
if (toolCall === undefined || !toolCallSent) {
if (toolCall?.result === undefined) toolCall = call;
sendToolCall();
return;
}
if (toolCall.result !== undefined || call.result === undefined) return;
// The app already has this call's input; it only needs the result.
toolCall = { arguments: toolCall.arguments, result: call.result };
notify("ui/notifications/tool-result", normalizeMcpAppToolResult(call.result));
},
updateHostContext: () => {
// The spec forbids messages before the app finishes initializing; it
// reads the then-current context from the initialize response anyway.
if (!initialized || sentContext === undefined) return;
const next = options.hostContext();
const changes: Record<string, unknown> = {};
for (const key of Object.keys(next) as Array<keyof McpAppHostContext>) {
if (JSON.stringify(next[key]) !== JSON.stringify(sentContext[key])) {
changes[key] = next[key];
}
}
sentContext = next;
if (Object.keys(changes).length > 0) {
notify("ui/notifications/host-context-changed", changes);
}
},
teardown: () =>
new Promise<void>((resolve) => {
let timer: ReturnType<typeof setTimeout> | undefined;
const finish = () => {
clearTimeout(timer);
disposed = true;
resolve();
};
// Before initialization the app has nothing to save and may not be
// listening; the spec only asks for teardown after it.
if (disposed || !initialized) {
finish();
return;
}
const id = `t3-host-${nextHostRequestId++}`;
hostRequests.set(id, finish);
timer = setTimeout(() => {
hostRequests.delete(id);
finish();
}, TEARDOWN_TIMEOUT_MS);
post({ jsonrpc: "2.0", id, method: "ui/resource-teardown", params: {} });
}),
dispose: () => {
disposed = true;
},
};
return hostHandle;
}
const MAX_DOWNLOAD_NAME = 200;
function downloadName(uri: unknown, name: unknown): string {
const raw =
typeof name === "string" && name.trim() !== ""
? name
: typeof uri === "string"
? (uri.split(/[/?#]/).findLast(Boolean) ?? "download")
: "download";
const safe = Array.from(raw, (char) =>
/[\\/:*?"<>|]/.test(char) || char.charCodeAt(0) < 32 ? "-" : char,
).join("");
return safe.slice(0, MAX_DOWNLOAD_NAME) || "download";
}
function readDownloads(contents: unknown): ReadonlyArray<McpAppDownload> | undefined {
if (!Array.isArray(contents) || contents.length === 0) return undefined;
const files: Array<McpAppDownload> = [];
for (const entry of contents) {
if (!Predicate.isObject(entry)) return undefined;
if (entry.type === "resource" && Predicate.isObject(entry.resource)) {
const resource = entry.resource;
const bytes = mcpResourceBytes(resource);
if (bytes === undefined) return undefined;
files.push({
_tag: "embedded",
name: downloadName(resource.uri, resource.name),
mimeType:
typeof resource.mimeType === "string" ? resource.mimeType : "application/octet-stream",
bytes,
});
} else if (entry.type === "resource_link" && typeof entry.uri === "string") {
files.push({
_tag: "link",
name: downloadName(entry.uri, entry.name),
uri: entry.uri,
...(typeof entry.mimeType === "string" ? { mimeType: entry.mimeType } : {}),
});
} else {
return undefined;
}
}
return files;
}
export function mcpAppStyleVariables(
theme: Readonly<Record<string, string>>,
): Record<string, string> {
const pick = (name: string) => theme[name];
const pairs: ReadonlyArray<readonly [string, string | undefined]> = [
["--color-background-primary", pick("--background")],
["--color-background-secondary", pick("--card")],
["--color-background-tertiary", pick("--muted")],
["--color-background-inverse", pick("--foreground")],
["--color-background-info", pick("--info")],
["--color-background-danger", pick("--destructive-surface")],
["--color-background-warning", pick("--warning-surface")],
["--color-text-primary", pick("--foreground")],
["--color-text-secondary", pick("--muted-foreground")],
["--color-text-tertiary", pick("--muted-foreground")],
["--color-text-inverse", pick("--background")],
["--color-text-info", pick("--info-foreground")],
["--color-text-danger", pick("--destructive-foreground")],
["--color-text-success", pick("--success-foreground")],
["--color-text-warning", pick("--warning-foreground")],
["--color-border-primary", pick("--border")],
["--color-border-secondary", pick("--input")],
["--color-border-danger", pick("--destructive")],
["--color-ring-primary", pick("--ring")],
["--font-sans", pick("--font-sans")],
["--font-mono", pick("--font-mono")],
["--border-radius-md", pick("--radius")],
];
const variables: Record<string, string> = {};
for (const [name, value] of pairs) {
if (value !== undefined && value !== "") variables[name] = value;
}
return variables;
}