Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import { useEffect, useId, useRef } from 'react';
import { useQueryClient } from '@tanstack/react-query';
import { JSONRPCMessageSchema } from '@modelcontextprotocol/sdk/types.js';
import { QueryKeys, DEFAULT_MCP_APP_ACTION_PREVIEW_CHARS } from 'librechat-data-provider';
import { AppBridge, buildAllowAttribute } from '@modelcontextprotocol/ext-apps/app-bridge';
import type {
Transport,
TransportSendOptions,
} from '@modelcontextprotocol/sdk/shared/transport.js';
import type { McpUiStyles, McpUiStyleVariableKey } from '@modelcontextprotocol/ext-apps/app-bridge';
import type { JSONRPCMessage, MessageExtraInfo } from '@modelcontextprotocol/sdk/types.js';
import type { UIResource } from 'librechat-data-provider';
import type { AppToolResult } from '~/utils/mcpApps';
import type { MCPAppAction } from './approval';
import {
callMCPAppTool,
fetchMCPResourceHtml,
readMCPResource,
listMCPResources,
listMCPResourceTemplates,
validateMCPAppBinding,
getSupportedMCPAppPermissions,
getInlineResourceHtml,
isAllowedAppLink,
withSandboxCsp,
MAX_APP_VIEW_HEIGHT,
} from '~/utils/mcpApps';
import {
useOptionalMessagesOperations,
useIsMessagesViewReadOnly,
useMCPAppsPolicy,
} from '~/Providers';
import { logger } from '~/utils';
type MessageContentBlock = { type?: string; text?: string };
type SizeParams = { width?: number; height?: number };
type ResolvedResource = {
html: string;
csp: UIResource['csp'];
permissions: UIResource['permissions'];
};
/** A source- and origin-validated transport that resolves the live iframe WindowProxy per event. */
class IframePostMessageTransport implements Transport {
onclose?: () => void;
onerror?: (error: Error) => void;
onmessage?: (message: JSONRPCMessage, extra?: MessageExtraInfo) => void;
sessionId?: string;
setProtocolVersion?: (version: string) => void;
constructor(private readonly getIframe: () => HTMLIFrameElement | null) {}
private getTarget(): { window: Window; origin: string } | null {
const iframe = this.getIframe();
const target = iframe?.contentWindow;
const src = iframe?.getAttribute('src');
if (!target || !src) {
return null;
}
try {
return { window: target, origin: new URL(src, window.location.href).origin };
} catch {
return null;
}
}
private readonly messageListener = (event: MessageEvent) => {
const target = this.getTarget();
if (!target || event.source !== target.window || event.origin !== target.origin) {
return;
}
const parsed = JSONRPCMessageSchema.safeParse(event.data);
if (parsed.success) {
this.onmessage?.(parsed.data);
} else if (event.data?.jsonrpc === '2.0') {
this.onerror?.(new Error(`Invalid JSON-RPC message received: ${parsed.error.message}`));
}
};
async start(): Promise<void> {
window.addEventListener('message', this.messageListener);
}
async send(message: JSONRPCMessage, _options?: TransportSendOptions): Promise<void> {
const target = this.getTarget();
if (!target) {
throw new Error('MCP App iframe is unavailable');
}
target.window.postMessage(message, target.origin);
}
async close(): Promise<void> {
window.removeEventListener('message', this.messageListener);
this.onclose?.();
}
}
export type UseAppBridgeParams = {
iframeRef: React.RefObject<HTMLIFrameElement | null>;
resource: UIResource;
toolArgs: Record<string, unknown> | undefined;
toolResult: AppToolResult | undefined;
userId?: string;
/** Only a host-owned approval control may resolve this; missing control denies actions. */
onRequestAction?: (action: MCPAppAction, signal: AbortSignal) => Promise<boolean>;
onCancelAction?: () => void;
/** View-owned retry generation. Each attempt gets an isolated bridge and resource query. */
attempt: number;
onSizeChanged: (params: SizeParams) => void;
/** False once the app requested teardown, so the effect disposes instead of re-mounting a bridge. */
active?: boolean;
onLoaded?: () => void;
onTeardown?: () => void;
onFailed?: () => void;
};
/** Maps the MCP Apps standard host style tokens onto LibreChat's theme CSS variables. Apps keep
* their own fallbacks for anything omitted, so a partial set is intentional. */
const HOST_STYLE_VAR_MAP: Partial<Record<McpUiStyleVariableKey, string>> = {
'--color-background-primary': '--surface-primary',
'--color-background-secondary': '--surface-secondary',
'--color-background-tertiary': '--surface-tertiary',
'--color-background-danger': '--surface-destructive',
'--color-text-primary': '--text-primary',
'--color-text-secondary': '--text-secondary',
'--color-text-tertiary': '--text-tertiary',
'--color-text-danger': '--text-destructive',
'--color-text-warning': '--text-warning',
'--color-border-primary': '--border-medium',
'--color-border-secondary': '--border-light',
'--color-border-danger': '--border-destructive',
};
function readHostTheme(): 'light' | 'dark' {
return document.documentElement.classList.contains('dark') ? 'dark' : 'light';
}
function buildHostStyleVariables(): McpUiStyles {
const computed = getComputedStyle(document.documentElement);
const variables: Partial<Record<McpUiStyleVariableKey, string>> = {};
for (const [specVar, lcVar] of Object.entries(HOST_STYLE_VAR_MAP)) {
const value = computed.getPropertyValue(lcVar).trim();
if (value) {
variables[specVar as McpUiStyleVariableKey] = value;
}
}
// The token record is optional/partial by design (apps fall back on any we omit); the generated
// type requires every key, so assert the mapped subset.
return variables as McpUiStyles;
}
export function useAppBridge({
iframeRef,
resource,
toolArgs,
toolResult,
userId,
onRequestAction,
onCancelAction,
attempt,
onSizeChanged,
active = true,
onLoaded,
onTeardown,
onFailed,
}: UseAppBridgeParams) {
const { ask } = useOptionalMessagesOperations();
// Read-only views (shared transcripts, /search) must not let the embedded app proxy tool calls
// or resource reads against the viewer's MCP servers with the viewer's auth.
const readOnly = useIsMessagesViewReadOnly();
const { cspLimits, maxActionPreviewChars } = useMCPAppsPolicy();
const queryClient = useQueryClient();
const viewId = useId();
const effectGenerationRef = useRef(0);
const activeEffectRef = useRef<{ generation: number; queryKey: string } | null>(null);
// The csp actually delivered to the sandbox document, which is what bounds the app's own egress.
// Host-opened links are authorized against this rather than the tool-result copy, so the host can
// never open a link the sandbox policy did not grant.
const effectiveCspRef = useRef<UIResource['csp']>(undefined);
// The bridge mounts once per resource and reads these only inside its handlers, so a changed
// callback or tool-call snapshot never tears down the live AppBridge. Synced at render time
// (idempotent under Strict Mode) rather than via an effect that would only mirror props.
const askRef = useRef(ask);
const requestActionRef = useRef(onRequestAction);
const cancelActionRef = useRef(onCancelAction);
const maxActionPreviewCharsRef = useRef(maxActionPreviewChars);
const onSizeChangedRef = useRef(onSizeChanged);
const onLoadedRef = useRef(onLoaded);
const onTeardownRef = useRef(onTeardown);
const onFailedRef = useRef(onFailed);
askRef.current = ask;
requestActionRef.current = onRequestAction;
cancelActionRef.current = onCancelAction;
maxActionPreviewCharsRef.current = maxActionPreviewChars;
onSizeChangedRef.current = onSizeChanged;
onLoadedRef.current = onLoaded;
onTeardownRef.current = onTeardown;
onFailedRef.current = onFailed;
useEffect(() => {
const iframe = iframeRef.current;
const serverName = resource.serverName;
if (!iframe || !serverName || !active) return;
const serverBinding = resource.serverBinding;
if (!serverBinding) {
iframe.removeAttribute('src');
iframe.removeAttribute('allow');
onFailedRef.current?.();
return;
}
// A retry or binding change must unload the prior document before validating its replacement.
// Do not remove a missing src from a freshly mounted iframe: Chromium may emit a synthetic
// about:blank load for that mutation. On fast inline resources, that load can consume the
// one-shot sandbox listener before the cross-origin sandbox document finishes navigating.
if (iframe.hasAttribute('src')) {
iframe.removeAttribute('src');
}
iframe.removeAttribute('allow');
effectiveCspRef.current = undefined;
// Unmount, a resource switch, or a teardown can run cleanup while a read or bridge.connect() is
// still pending; this flag stops the pending continuation from touching a disposed bridge.
let cancelled = false;
const viewAbort = new AbortController();
let resourceSent = false;
let sendingResource = false;
let initialized = false;
let resolved: ResolvedResource | null = null;
let srcCsp: UIResource['csp'] = undefined;
const resourceQueryKey = [
QueryKeys.mcpAppResourceHtml,
serverName,
serverBinding,
resource.uri,
resource.resourceId,
userId,
viewId,
attempt,
] as const;
const effectGeneration = ++effectGenerationRef.current;
const resourceQueryKeyIdentity = JSON.stringify(resourceQueryKey);
activeEffectRef.current = {
generation: effectGeneration,
queryKey: resourceQueryKeyIdentity,
};
const assignSandboxSrc = (csp: UIResource['csp']) => {
const { url, applied } = withSandboxCsp(
iframe.getAttribute('data-sandbox-url') ?? '',
csp,
cspLimits,
);
// srcCsp records what was requested (it guards against reloading the document in a loop);
// effectiveCspRef records what the sandbox response was actually given.
srcCsp = csp;
effectiveCspRef.current = applied;
if (csp && !applied) {
logger.warn('[MCP App] Declared csp could not be delivered to the sandbox response');
}
iframe.src = url;
};
const applyOuterPermissions = (permissions: UIResource['permissions']) => {
const allowAttr = buildAllowAttribute(
permissions as Parameters<typeof buildAllowAttribute>[0],
);
if (allowAttr) {
iframe.setAttribute('allow', allowAttr);
} else {
iframe.removeAttribute('allow');
}
};
const { locale, timeZone } = Intl.DateTimeFormat().resolvedOptions();
const bounds = iframe.getBoundingClientRect();
let hostContext = {
theme: readHostTheme(),
platform: 'web' as const,
locale,
timeZone,
displayMode: 'inline' as const,
availableDisplayModes: ['inline' as const],
containerDimensions: { width: Math.round(bounds.width), maxHeight: MAX_APP_VIEW_HEIGHT },
styles: { variables: buildHostStyleVariables() },
};
const bridge = new AppBridge(
null,
{ name: 'LibreChat', version: '1.0.0' },
{
openLinks: {},
logging: {},
// Display-only views advertise no host-bound action capabilities so a well-behaved app
// disables those affordances rather than issuing calls the host ignores.
...(!readOnly
? {
serverTools: {},
serverResources: {},
message: { text: {} },
}
: {}),
},
{
hostContext,
},
);
const resizeObserver = new ResizeObserver(() => {
if (cancelled) return;
const width = Math.round(iframe.getBoundingClientRect().width);
if (width === hostContext.containerDimensions.width) return;
hostContext = {
...hostContext,
containerDimensions: { width, maxHeight: MAX_APP_VIEW_HEIGHT },
};
bridge.setHostContext(hostContext);
});
resizeObserver.observe(iframe);
let lastTheme = readHostTheme();
const themeObserver = new MutationObserver(() => {
if (cancelled) {
return;
}
const nextTheme = readHostTheme();
if (nextTheme === lastTheme) {
return;
}
lastTheme = nextTheme;
hostContext = {
...hostContext,
theme: nextTheme,
styles: { variables: buildHostStyleVariables() },
};
bridge.setHostContext(hostContext);
});
let disposed = false;
const dispose = () => {
if (disposed) return;
disposed = true;
cancelled = true;
viewAbort.abort();
cancelActionRef.current?.();
themeObserver.disconnect();
resizeObserver.disconnect();
bridge.close();
// React Strict Mode immediately replays effects in development. Let an equivalent successor
// share the in-flight resource read instead of cancelling the query it has just joined. A real
// unmount, retry, or resource change has no same-key successor and still cancels promptly.
queueMicrotask(() => {
const successor = activeEffectRef.current;
const isEquivalentReplay =
successor != null &&
successor.generation !== effectGeneration &&
successor.queryKey === resourceQueryKeyIdentity;
if (!isEquivalentReplay) {
void queryClient.cancelQueries({ queryKey: resourceQueryKey, exact: true });
}
});
};
const interactive = !readOnly;
// SDK callbacks may already be queued when a View closes or a peer starts teardown.
// Deny new work and propagate View disposal to in-flight authenticated reads/lists.
const liveRequestSignal = (signal: AbortSignal): AbortSignal => {
if (cancelled || viewAbort.signal.aborted || signal.aborted) {
throw new DOMException('MCP App View is closed', 'AbortError');
}
return AbortSignal.any([signal, viewAbort.signal]);
};
bridge.onopenlink = async ({ url }, { signal }) => {
if (signal.aborted || viewAbort.signal.aborted || cancelled) {
return { isError: true };
}
if (!isAllowedAppLink(url, effectiveCspRef.current, cspLimits)) {
logger.warn('[MCP App] Blocked open-link outside the declared egress domains');
return { isError: true };
}
try {
window.open(url, '_blank', 'noopener,noreferrer');
return {};
} catch (error) {
logger.error('[MCP App] Failed to open link', error);
return { isError: true };
}
};
// Host-bound actions (tool calls, resource reads/lists, model messages) run with the viewer's
// auth, so they are only wired in interactive views, never in shared transcripts or /search.
if (interactive) {
bridge.oncalltool = async (params, { signal }) => {
if (signal.aborted || viewAbort.signal.aborted || cancelled || !requestActionRef.current)
return { content: [], isError: true };
// Snapshot the arguments shown to the user: the App must not mutate them while waiting.
let argumentsText: string;
let args: Record<string, unknown>;
try {
argumentsText = JSON.stringify(params.arguments ?? {});
if (
!argumentsText ||
argumentsText.length >
(maxActionPreviewCharsRef.current ?? DEFAULT_MCP_APP_ACTION_PREVIEW_CHARS)
)
return { content: [], isError: true };
args = JSON.parse(argumentsText) as Record<string, unknown>;
if (!args || typeof args !== 'object' || Array.isArray(args))
return { content: [], isError: true };
} catch {
return { content: [], isError: true };
}
const toolName = params.name;
try {
const actionSignal = AbortSignal.any([signal, viewAbort.signal]);
const allowed = await requestActionRef.current(
{ kind: 'tool', serverName, toolName, argumentsText },
actionSignal,
);
if (!allowed || actionSignal.aborted || cancelled) return { content: [], isError: true };
return await callMCPAppTool(serverName, serverBinding, toolName, args, actionSignal);
} catch (error) {
logger.error('[MCP App] Tool action failed', error);
return { content: [], isError: true };
}
};
bridge.onreadresource = async (params, { signal }) =>
readMCPResource(serverName, serverBinding, params.uri, liveRequestSignal(signal));
bridge.onlistresources = async (params, { signal }) =>
listMCPResources(serverName, serverBinding, params?.cursor, liveRequestSignal(signal));
bridge.onlistresourcetemplates = async (params, { signal }) =>
listMCPResourceTemplates(
serverName,
serverBinding,
params?.cursor,
liveRequestSignal(signal),
);
bridge.onmessage = async ({ content }, { signal }) => {
const text = (content as MessageContentBlock[])
.filter((block) => block.type === 'text' && typeof block.text === 'string')
.map((block) => block.text)
.join('\n');
if (
!text.trim() ||
text.length >
(maxActionPreviewCharsRef.current ?? DEFAULT_MCP_APP_ACTION_PREVIEW_CHARS) ||
signal.aborted ||
viewAbort.signal.aborted ||
cancelled ||
!requestActionRef.current
) {
return { isError: true };
}
try {
const actionSignal = AbortSignal.any([signal, viewAbort.signal]);
const allowed = await requestActionRef.current(
{ kind: 'message', serverName, text },
actionSignal,
);
if (!allowed || actionSignal.aborted || cancelled) return { isError: true };
// The selected agent and MCP servers belong to the conversation. Only the
// next composer's staged files, manual skill picks, quotes and reasoning
// level are excluded.
const accepted = askRef.current(
{ text },
{
overrideFiles: [],
overrideManualSkills: [],
overrideQuotes: [],
overrideReasoning: null,
},
);
if (accepted === false) {
return { isError: true };
}
// ask accepted the turn synchronously. A later App abort cannot undo it;
// claiming failure here encourages the App to retry and duplicate the turn.
return {};
} catch (error) {
logger.error('[MCP App] Failed to deliver message', error);
return { isError: true };
}
};
}
const resolveResource = async (): Promise<ResolvedResource | null> => {
const inlineHtml = getInlineResourceHtml(resource);
// Inline mcp-app resources already carry their HTML, so use it directly instead of a
// resources/read round trip, but validate their persisted server binding before loading it.
if (inlineHtml) {
await queryClient.fetchQuery({
queryKey: resourceQueryKey,
queryFn: async ({ signal }) => {
await validateMCPAppBinding(serverName, serverBinding, signal);
return true;
},
staleTime: 0,
});
return {
html: inlineHtml,
csp: resource.csp,
permissions: getSupportedMCPAppPermissions(resource.permissions),
};
}
// Read-only views must not resolve app HTML from the viewer's MCP server.
if (readOnly) {
logger.debug(
'[MCP App] Read-only view: skipping server HTML fetch for resourceUri-only app',
);
return null;
}
const fetched = await queryClient.fetchQuery({
// The same ui:// URI can carry revised HTML on a later turn, and nothing invalidates this
// cache entry. The View ID owns cancellation, while the remaining fields retain server,
// resource, persisted-call, and user scope; zero stale time makes every later mount re-read.
queryKey: resourceQueryKey,
queryFn: ({ signal }) =>
fetchMCPResourceHtml(serverName, serverBinding, resource.uri, signal),
staleTime: 0,
});
return {
html: fetched.html,
csp: fetched.csp,
permissions: getSupportedMCPAppPermissions(fetched.permissions),
};
};
const sendResource = async () => {
if (resourceSent || sendingResource || cancelled) {
return;
}
sendingResource = true;
try {
const next = resolved ?? (await resolveResource());
if (cancelled || !next) {
return;
}
if (!next.html) {
throw new Error('Resource returned no HTML');
}
resolved = next;
applyOuterPermissions(next.permissions);
// A retry that resolved a csp the current sandbox document was not served with would run the
// app under the restrictive default policy; reload the document with the declared domains
// and let its own announcement deliver the resource.
if (next.csp && next.csp !== srcCsp) {
assignSandboxSrc(next.csp);
return;
}
resourceSent = true;
await bridge.sendSandboxResourceReady({
html: next.html,
csp: next.csp as never,
permissions: next.permissions as never,
sandbox: 'allow-scripts allow-forms',
});
} catch (err) {
resourceSent = false;
logger.error('[MCP App] Failed to send sandbox resource', err);
if (!cancelled) {
onFailedRef.current?.();
}
} finally {
sendingResource = false;
}
};
// The proxy re-announces itself until it receives a resource, which is the only retry signal a
// failed read gets; a latch here strands the frame behind the spinner forever.
bridge.addEventListener('sandboxready', () => {
void sendResource();
});
bridge.oninitialized = async () => {
if (cancelled || initialized) {
return;
}
initialized = true;
// The app handshake completed: treat this as the load signal so apps that never emit a
// size-change (auto-resize disabled) are still revealed instead of stuck behind the spinner.
onLoadedRef.current?.();
// MCP Apps expect tool input exactly once before the result, even for no-argument tools,
// so apps that initialize from ontoolinput always receive it.
await bridge
.sendToolInput({ arguments: toolArgs ?? {} })
.catch((err: unknown) => logger.error('[MCP App] sendToolInput failed', err));
if (toolResult && !cancelled) {
await bridge
.sendToolResult(toolResult as never)
.catch((err: unknown) => logger.error('[MCP App] sendToolResult failed', err));
}
};
bridge.addEventListener('sizechange', (params) => {
if (!cancelled) {
onSizeChangedRef.current(params);
}
});
bridge.addEventListener('requestteardown', async () => {
if (cancelled) return;
// A peer-controlled teardown handshake can stall. Revoke action authority before awaiting it.
viewAbort.abort();
cancelActionRef.current?.();
if (initialized) {
await bridge.teardownResource({}).catch(() => {});
}
if (cancelled) {
return;
}
dispose();
onTeardownRef.current?.();
});
bridge.addEventListener('loggingmessage', (event) => {
const { level, data } = event as { level: string; data: unknown };
logger.debug('[MCP App]', level, data);
});
themeObserver.observe(document.documentElement, {
attributes: true,
attributeFilter: ['class'],
});
const start = async () => {
// Both sandbox policies are built from this URL before the document loads. The content-level
// _meta.ui.csp is authoritative, which requires resolving the resource before navigation.
const next = await resolveResource().catch((err: unknown) => {
logger.error('[MCP App] Failed to read app resource', err);
if (!cancelled) {
onFailedRef.current?.();
}
return null;
});
if (cancelled) {
return;
}
resolved = next;
applyOuterPermissions(next?.permissions);
// A failed read still loads the sandbox document: its re-announcements are the only retry
// signal, and a later resolve reloads it with the declared domains.
if (next || !readOnly) {
// Start listening before navigation so a fresh iframe's synthetic about:blank load cannot
// consume or race a one-shot load handler. The transport resolves and validates the live
// iframe WindowProxy and exact sandbox origin for every message, so cross-origin navigation
// cannot leave it bound to a stale window.
await bridge
.connect(new IframePostMessageTransport(() => iframeRef.current))
.catch((err) => {
logger.error('[MCP App] bridge.connect failed', err);
if (!cancelled) {
onFailedRef.current?.();
}
dispose();
});
if (cancelled) {
return;
}
assignSandboxSrc(next?.csp);
}
};
void start();
return () => {
cancelled = true;
cancelActionRef.current?.();
if (initialized) {
bridge.teardownResource({}).catch(() => {});
}
dispose();
};
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [
resource.resourceId,
resource.serverBinding,
resource.uri,
resource.serverName,
active,
readOnly,
userId,
viewId,
attempt,
cspLimits?.maxSourcesPerDirective,
cspLimits?.maxSerializedLength,
]);
}