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 { logger } from '@librechat/data-schemas';
import {
Constants,
MCPOptionsSchema,
extractEnvVariable,
normalizeServerName,
normalizeMCPToolKey,
buildServerNameAliases,
} from 'librechat-data-provider';
import type { AgentToolOptions, MCPOptions } from 'librechat-data-provider';
import type { ParsedServerConfig } from '~/mcp/types';
import type { RequestBody } from '~/types';
import { capturePersistedToolOptions, retainToolOptionsLimits } from '~/agents/options';
import { isApiKeyHeaderOverridden, isGeneratedUserApiKeyVariable } from './headers';
import { isDirectOpenIDBearerRecoveryEnabled } from '~/mcp/openid';
import { ALLOWED_BODY_FIELDS, isPluginSourced } from '~/utils/env';
import { isEnabled } from '~/utils/common';
export const mcpToolPattern: RegExp = new RegExp(`^.+${Constants.mcp_delimiter}.+$`);
function isMCPServerConfig(config: unknown): config is ParsedServerConfig {
return MCPOptionsSchema.safeParse(config).success;
}
/** Validates an effective MCP config without stripping its server-managed metadata. */
export function validateMCPServerConfig(config: unknown): ParsedServerConfig {
if (!isMCPServerConfig(config)) {
throw new Error('Invalid effective MCP server configuration');
}
return config;
}
/**
* Prefix of the lazily-expanded MCP placeholder `mcp_all<delim><server>`,
* pushed into an agent's `tools` for overlay/user-connection servers whose
* tool names are not known until the definitions loader expands them.
*
* The name is reserved by that convention: the definitions loader treats ANY
* matching entry as "expand every tool on this server", so a remote tool
* literally named `mcp_all` cannot be addressed individually anywhere in the
* pipeline. Kept here as the one definition of the prefix.
*/
export const MCP_ALL_PLACEHOLDER_PREFIX: string = `${Constants.mcp_all}${Constants.mcp_delimiter}`;
/** Whether a tool entry is the lazily-expanded `mcp_all` placeholder. */
export function isMCPAllPlaceholder(toolName: string): boolean {
return toolName.startsWith(MCP_ALL_PLACEHOLDER_PREFIX);
}
/** Server-pin token (`sys__server__sys<delim><server>`) that keeps a server
* attached to an agent independent of its tool selection. */
const MCP_SERVER_TOKEN_PREFIX: string = `${Constants.mcp_server}${Constants.mcp_delimiter}`;
/**
* Later-configured server names whose normalized form is already claimed by an
* earlier different name. Such a pair produces IDENTICAL model-facing tool
* keys, so tool selection and execution cannot tell the servers apart —
* `buildServerNameAliases` deterministically routes to the first name, and
* the shadowed later server must be EXCLUDED from tool exposure entirely:
* offering its tools would let a user select a tool that silently executes
* against the first server's configuration.
*/
/**
* Whether a resolved server name is normalization-sensitive — its own name
* needs normalizing, or it EQUALS the normalized form of some configured
* special-character name. Under an incomplete collision audit these are the
* references whose routing cannot be proven unambiguous, so they fail closed.
*/
export function isNormalizationSensitiveName(
serverName: string,
rawServerNames: readonly string[],
): boolean {
if (normalizeServerName(serverName) !== serverName) {
return true;
}
return rawServerNames.some(
(raw) => raw !== serverName && normalizeServerName(raw) === serverName,
);
}
export function findShadowedServerNames(rawServerNames: readonly string[]): Set<string> {
/** Derived from `buildServerNameAliases` so shadow detection can never
* diverge from the tie-break routing actually uses (identity entries
* first, then configuration order). */
const aliases = buildServerNameAliases(rawServerNames);
const shadowed = new Set<string>();
for (const raw of rawServerNames) {
if (raw && aliases.get(normalizeServerName(raw)) !== raw) {
shadowed.add(raw);
}
}
return shadowed;
}
/**
* Heals legacy persisted agent data whose MCP tool keys embed a RAW server
* name: model-facing keys carry `normalizeServerName(server)` (matching cache
* keys, definition names, and runtime instance names), so an agent document
* saved before that convention — or through the old raw-keyed cache — would
* neither load its tools nor have its `tool_options` (defer / programmatic /
* background / intent) honored for a server whose name needs normalizing.
*
* Placeholder and server-pin tokens are left untouched: they are
* config-identity references consumed against raw config names (the client's
* selectors, the definitions loader's expansion), never model-facing names.
* Returns the same references when nothing needs rewriting, so the common
* path (every server name already normalized) allocates nothing.
*/
export function normalizeAgentToolKeys(params: {
tools: string[] | undefined;
toolOptions: AgentToolOptions | undefined;
rawServerNames: readonly string[];
}): { tools: string[] | undefined; toolOptions: AgentToolOptions | undefined } {
const { tools, toolOptions, rawServerNames } = params;
/**
* A SHADOWED server (its normalized form claimed by an earlier different
* name) must NOT be healed: rewriting its raw key would produce the first
* server's key exactly, silently executing the wrong server's action. Left
* raw, the key fails to match the (normalized-keyed) tool map and the tool
* errors visibly — broken beats misrouted.
*/
const shadowed = findShadowedServerNames(rawServerNames);
const rewritableNames = rawServerNames.filter(
(name) => normalizeServerName(name) !== name && !shadowed.has(name),
);
if (rewritableNames.length === 0) {
return { tools, toolOptions };
}
const rewriteKey = (key: string): string => {
if (
!key.includes(Constants.mcp_delimiter) ||
isMCPAllPlaceholder(key) ||
key.startsWith(MCP_SERVER_TOKEN_PREFIX)
) {
return key;
}
return normalizeMCPToolKey(key, rewritableNames);
};
let toolsChanged = false;
let nextTools = tools?.map((key) => {
const rewritten = rewriteKey(key);
if (rewritten !== key) {
toolsChanged = true;
}
return rewritten;
});
/** A document carrying BOTH spellings converges on one key after healing —
* collapse duplicates (order-preserving) so the loaders never build two
* instances with the same function name. */
if (toolsChanged && nextTools) {
const seen = new Set<string>();
nextTools = nextTools.filter((key) => {
if (seen.has(key)) {
return false;
}
seen.add(key);
return true;
});
}
let optionsChanged = false;
let nextOptions: AgentToolOptions | undefined;
if (toolOptions) {
capturePersistedToolOptions(toolOptions);
nextOptions = {};
for (const [key, options] of Object.entries(toolOptions)) {
const rewritten = rewriteKey(key);
if (rewritten !== key) {
optionsChanged = true;
}
/** When both spellings carry options, the CURRENT (normalized) entry
* wins regardless of object insertion order — a legacy entry must not
* clobber settings a client already wrote under the new spelling. */
nextOptions[rewritten] =
rewritten !== key
? { ...options, ...nextOptions[rewritten] }
: { ...nextOptions[key], ...options };
}
}
if (optionsChanged && nextOptions) retainToolOptionsLimits(nextOptions, toolOptions);
return {
tools: toolsChanged ? nextTools : tools,
toolOptions: optionsChanged ? nextOptions : toolOptions,
};
}
const RUNTIME_CONTEXT_PLACEHOLDER_PATTERN = /\{\{LIBRECHAT_(?:USER|OPENID|GRAPH)_[^}]+\}\}/;
const BODY_PLACEHOLDER_FIELDS = Object.fromEntries(
ALLOWED_BODY_FIELDS.map((field) => [field.toUpperCase(), field]),
) as Record<string, keyof RequestBody>;
const RUNTIME_BODY_FIELD_NAMES = Object.keys(BODY_PLACEHOLDER_FIELDS).join('|');
const RUNTIME_BODY_PLACEHOLDER_PATTERN = new RegExp(
`\\{\\{LIBRECHAT_BODY_(?:${RUNTIME_BODY_FIELD_NAMES})\\}\\}`,
);
const RUNTIME_BODY_PLACEHOLDER_CAPTURE_PATTERN = new RegExp(
`\\{\\{LIBRECHAT_BODY_(${RUNTIME_BODY_FIELD_NAMES})\\}\\}`,
'g',
);
type PlaceholderValue =
| string
| number
| boolean
| null
| undefined
| readonly PlaceholderValue[]
| { readonly [key: string]: PlaceholderValue };
export interface MCPRequestScope {
requestScoped: boolean;
requiredBodyFields: Array<keyof RequestBody>;
}
type UserScopedConnectionConfig = Pick<
ParsedServerConfig,
'requiresOAuth' | 'source' | 'dbId' | 'startup'
> & {
/** Loosened like the fields below: raw (pre-inspection) configs carry
* optional API-key fields, and the gating predicates only inspect them. */
apiKey?: Partial<NonNullable<ParsedServerConfig['apiKey']>> | null;
args?: string[];
/** Loosened from the parsed shapes so raw (pre-inspection) configs qualify;
* scoping predicates only check key presence */
obo?: { scopes?: string } | null;
customUserVars?: Record<
string,
{ description?: string; title?: string; sensitive?: boolean } | undefined
>;
env?: Record<string, string | undefined>;
headers?: Record<string, string | undefined>;
/** Operator-configured headers sent only on chat-time connections. */
requestHeaders?: Record<string, string | undefined>;
oauth?: PlaceholderValue;
oauth_headers?: Record<string, string | undefined>;
url?: string;
};
function mergeHeaderMaps<T extends string | undefined>(
headers: Record<string, T> | undefined,
requestHeaders: Record<string, T>,
): Record<string, T> {
const overridden = new Set(Object.keys(requestHeaders).map((name) => name.toLowerCase()));
const merged: Record<string, T> = {};
for (const [name, value] of Object.entries(headers ?? {})) {
if (!overridden.has(name.toLowerCase())) {
merged[name] = value;
}
}
return { ...merged, ...requestHeaders };
}
function placeholderBearingFields(config: UserScopedConnectionConfig): PlaceholderValue[] {
return [
isApiKeyHeaderOverridden(config.apiKey, config.requestHeaders) ? undefined : config.apiKey?.key,
config.args,
config.env,
config.requestHeaders == null
? config.headers
: mergeHeaderMaps(config.headers, config.requestHeaders),
config.oauth,
config.oauth_headers,
config.url,
];
}
/** Whether a server should use MCP OAuth handling. */
export function isOAuthServer(
config: Pick<ParsedServerConfig, 'requiresOAuth' | 'oauth'>,
): boolean {
if (config.requiresOAuth === false) {
return false;
}
return config.requiresOAuth === true || config.oauth != null;
}
/**
* Whether a server needs the OAuth-style connection wiring (flow manager,
* token methods, OBO/OAuth resolvers). Distinct from `isOAuthServer`: OBO
* servers reuse the same wiring even though they don't run an OAuth handshake,
* because the runtime needs `oboTokenResolver`/`oboTrustChecker` plumbed through.
*
* Without this, an OBO server with `requiresOAuth: false` would land in the
* non-OAuth branch of MCPManager.discoverServerTools / UserConnectionManager,
* which omits the OBO resolver — `usesObo` then evaluates to false in the
* factory and the connection sends a bare request that the upstream rejects.
*/
export function requiresOAuthMachinery(config: ParsedServerConfig): boolean {
if (isDirectOpenIDBearerRecoveryEnabled(config)) {
return false;
}
return isOAuthServer(config) || config.obo != null;
}
/** Required chat credentials, retaining explicit variables and any still-used generated key. */
function requiredCustomUserVars(config: UserScopedConnectionConfig): string[] {
const keys = Object.keys(config.customUserVars ?? {});
if (
config.apiKey?.source !== 'user' ||
!isApiKeyHeaderOverridden(config.apiKey, config.requestHeaders)
) {
return keys;
}
const fields = placeholderBearingFields(config);
return keys.filter((key) => {
if (!isGeneratedUserApiKeyVariable(key)) {
return true;
}
const pattern = new RegExp(`\\{\\{${key}\\}\\}`);
return fields.some((value) => hasPlaceholder(value, pattern));
});
}
/** Checks the effective chat requirements, without weakening catalog-only credentials. */
export function hasCustomUserVars(config: UserScopedConnectionConfig): boolean {
return requiredCustomUserVars(config).length > 0;
}
function hasRuntimeContextPlaceholder(value: PlaceholderValue): boolean {
return (
hasPlaceholder(value, RUNTIME_CONTEXT_PLACEHOLDER_PATTERN) ||
hasPlaceholder(value, RUNTIME_BODY_PLACEHOLDER_PATTERN)
);
}
function hasPlaceholder(value: PlaceholderValue, pattern: RegExp): boolean {
if (typeof value === 'string') {
return pattern.test(value) || pattern.test(extractEnvVariable(value));
}
if (Array.isArray(value)) {
return value.some((item) => hasPlaceholder(item, pattern));
}
if (value == null || typeof value !== 'object') {
return false;
}
return Object.values(value).some((item) => hasPlaceholder(item, pattern));
}
function addRuntimeBodyPlaceholderFields(
value: PlaceholderValue,
fields: Set<keyof RequestBody>,
): void {
if (typeof value === 'string') {
for (const candidate of new Set([value, extractEnvVariable(value)])) {
for (const match of candidate.matchAll(RUNTIME_BODY_PLACEHOLDER_CAPTURE_PATTERN)) {
const placeholderKey = match[1];
const field = placeholderKey ? BODY_PLACEHOLDER_FIELDS[placeholderKey] : undefined;
if (field) {
fields.add(field);
}
}
}
return;
}
if (Array.isArray(value)) {
for (const item of value) {
addRuntimeBodyPlaceholderFields(item, fields);
}
return;
}
if (value == null || typeof value !== 'object') {
return;
}
for (const item of Object.values(value)) {
addRuntimeBodyPlaceholderFields(item, fields);
}
}
function canResolveRuntimePlaceholders(config: UserScopedConnectionConfig): boolean {
return !isUserSourced(config) && !isPluginSourced(config);
}
/**
* Trusted YAML/config servers may use per-user/request placeholders that can
* only be resolved once a real request context exists. User-sourced DB servers
* deliberately stay sandboxed and only resolve customUserVars, while plugin
* configs preserve every placeholder literally as a security boundary.
*/
export function hasRuntimeContextPlaceholders(config: UserScopedConnectionConfig): boolean {
if (!canResolveRuntimePlaceholders(config)) {
return false;
}
return placeholderBearingFields(config).some(hasRuntimeContextPlaceholder);
}
export function hasRuntimeUrlPlaceholders(config: UserScopedConnectionConfig): boolean {
if (!canResolveRuntimePlaceholders(config)) {
return false;
}
return hasRuntimeContextPlaceholder(config.url);
}
export function getMCPRequestScope(config: UserScopedConnectionConfig): MCPRequestScope {
if (!canResolveRuntimePlaceholders(config)) {
return { requestScoped: false, requiredBodyFields: [] };
}
const requiredBodyFields = new Set<keyof RequestBody>();
for (const value of placeholderBearingFields(config)) {
addRuntimeBodyPlaceholderFields(value, requiredBodyFields);
}
const fields = Array.from(requiredBodyFields);
return { requestScoped: fields.length > 0, requiredBodyFields: fields };
}
/**
* Folds the operator's chat-only `requestHeaders` into `headers`, so everything
* downstream — direct-bearer detection, Graph preprocessing, `processMCPEnv`,
* the transports — keeps reading ONE header map and never has to learn about a
* second one. Called at the entry of each resolution pipeline, before any
* consumer inspects the config.
*
* HTTP header names are case-insensitive, so a base `Authorization` is dropped
* when the request map declares `authorization`: keeping both would let Undici
* join the values (`old, new`) instead of letting `requestHeaders` win.
*
* The field is consumed as it merges, making this idempotent for a config that
* passes through twice (checkout joiners, direct-bearer recovery).
*/
export function applyRequestHeaders<T extends MCPOptions>(config: T): T {
const carrier = config as T & {
headers?: Record<string, string>;
requestHeaders?: Record<string, string>;
};
if (carrier.requestHeaders == null) {
return config;
}
const merged = {
...carrier,
headers: mergeHeaderMaps(carrier.headers, carrier.requestHeaders),
};
if (carrier.apiKey && isApiKeyHeaderOverridden(carrier.apiKey, carrier.requestHeaders)) {
/** Keep the explicit auth mode, but disarm its lower-priority header injection. */
merged.apiKey = { ...carrier.apiKey, key: undefined };
}
if (carrier.customUserVars) {
const required = new Set(requiredCustomUserVars(carrier));
merged.customUserVars = Object.fromEntries(
Object.entries(carrier.customUserVars).filter(([key]) => required.has(key)),
);
}
delete merged.requestHeaders;
return merged;
}
/**
* Strips the operator's chat-only `requestHeaders` for a catalog (discovery)
* connection. Discovery has no conversation or message to resolve a
* `{{LIBRECHAT_BODY_*}}` placeholder against, so sending the map at all would
* either leak a literal placeholder upstream or resolve it to an empty value.
*
* Returns the same reference when there is nothing to strip.
*/
export function toCatalogConnectionConfig<T extends MCPOptions>(config: T): T {
const carrier = config as T & { requestHeaders?: Record<string, string> };
if (carrier.requestHeaders == null) {
return config;
}
const catalogConfig = { ...carrier };
delete catalogConfig.requestHeaders;
return catalogConfig;
}
export function getMissingRuntimeBodyPlaceholderFields(
config: UserScopedConnectionConfig,
requestBody?: RequestBody,
): string[] {
return getMCPRequestScope(config).requiredBodyFields.filter((field) => {
const value = requestBody?.[field];
return value == null || (typeof value === 'string' && value.trim() === '');
});
}
/**
* `BODY` placeholders vary by chat request, so the normal userId:serverName
* cache would reuse a connection built with stale request context.
*
* Ephemeral connections are created and torn down per tool call — configs using
* these placeholders pay a full connect + initialize on every invocation.
*
* User/OpenID/Graph placeholders still require user-scoped connections, but they
* are not request-scoped by themselves. HTTP transports refresh resolved headers
* before each tool call, so token/user headers can remain on the cached user
* connection without forcing a reconnect for every invocation.
*/
export function requiresEphemeralUserConnection(config: UserScopedConnectionConfig): boolean {
return getMCPRequestScope(config).requestScoped;
}
/**
* Whether a resolved server config may be reached from the chat MCP picker.
*
* Mirrors `selectableServers` in the client's `useMCPServerManager`, which is
* the list the dropdown offers: `chatMenu: false` is the operator hiding a
* server from chat, and `consumeOnly` marks a server the user reaches only
* through an agent that references it, never on its own.
*
* An unresolved config is selectable. A name the registry cannot resolve is
* either request-tier (declared on the request body and never registered) or
* genuinely unknown, and both already have their own handling downstream —
* failing closed here would silently drop request-scoped servers instead.
*/
export function isChatSelectableMCPServer(
config?: Pick<ParsedServerConfig, 'chatMenu' | 'consumeOnly'> | null,
): boolean {
if (config == null) {
return true;
}
return config.chatMenu !== false && config.consumeOnly !== true;
}
/**
* Narrows a chat picker selection to the servers that picker is allowed to
* offer, so a stale client, a replayed body, or a hand-written request cannot
* reach a server the menu hides.
*
* Pass only the picker's own selection. Servers a model spec pins
* (`modelSpec.mcpServers`) are the operator's choice and stay attached even
* when hidden, so they must be added after this call, not through it.
*
* The accessible set comes from the registry — the same resolution that feeds
* the client's catalog, with its own tier precedence already applied — rather
* than being re-derived from the request's config overlay. A user-tier or
* process-backed server outranks a config entry of the same name, and this must
* agree with whatever the picker was actually offered.
*
* Names are deduplicated before the lookup, since the selection is
* request-supplied, and are matched through the same normalized-name aliasing
* that tool loading uses, built over the whole accessible set so an exact name
* always wins over another server's normalized form. A name the registry does
* not know is request-tier — declared on the body, never registered — and is
* kept, as is every name if the lookup fails: this narrows an
* already-authenticated selection and is not the authorization boundary.
*
* Returns the names as they were sent, so callers keep addressing servers the
* way the rest of the request does.
*/
export async function filterChatSelectableMCPServers(
selectedServers: string[] | null | undefined,
{
userId,
role,
getAccessibleMCPServers,
}: {
userId: string;
role?: string;
getAccessibleMCPServers?: (
userId: string,
role?: string,
) => Promise<Record<string, Pick<ParsedServerConfig, 'chatMenu' | 'consumeOnly'>>>;
},
): Promise<string[]> {
if (!Array.isArray(selectedServers) || selectedServers.length === 0) {
return [];
}
const uniqueServers = [...new Set(selectedServers)];
if (getAccessibleMCPServers == null) {
return uniqueServers;
}
let accessible: Record<string, Pick<ParsedServerConfig, 'chatMenu' | 'consumeOnly'>>;
try {
accessible = await getAccessibleMCPServers(userId, role);
} catch (error) {
logger.warn('[MCP] Could not resolve accessible servers; keeping the chat selection', error);
return uniqueServers;
}
const accessibleNames = Object.keys(accessible ?? {});
if (accessibleNames.length === 0) {
return uniqueServers;
}
const aliases = buildServerNameAliases(accessibleNames);
return uniqueServers.filter((serverName) => {
const resolved =
accessible[serverName] ?? accessible[aliases.get(normalizeServerName(serverName)) ?? ''];
return isChatSelectableMCPServer(resolved);
});
}
/**
* Returns true when a server requires a per-user connection instead of an
* app-shared connection.
*/
export function requiresUserScopedConnection(config: UserScopedConnectionConfig): boolean {
return (
config.requiresOAuth === true ||
config.obo != null ||
hasCustomUserVars(config) ||
hasRuntimeContextPlaceholders(config)
);
}
/**
* Whether the config declares chat-only headers. Guards against a truthy `{}`
* the way `hasCustomUserVars` does.
*/
function hasChatOnlyHeaders(config: UserScopedConnectionConfig): boolean {
return !!config.requestHeaders && Object.keys(config.requestHeaders).length > 0;
}
/** Whether a server can share one operator-owned connection across all users. */
export function canUseAppConnection(config: UserScopedConnectionConfig): boolean {
return (
config.startup !== false &&
!isUserSourced(config) &&
!requiresUserScopedConnection(config) &&
/**
* One session cannot serve both sides of `requestHeaders`: an app-shared
* connection's own `initialize` and `tools/list` are catalog requests that
* must omit them, while its chat tool calls must send them. Placeholder
* values are already excluded through `requiresUserScopedConnection`; STATIC
* values reach here, and sharing would bake chat-only headers into the
* startup handshake every later catalog read reuses.
*/
!hasChatOnlyHeaders(config)
);
}
/**
* Whether a server defers sign-in to its first tool call, offering a user who has not signed in
* yet the tool catalog the operator declared. Limited to operator-owned servers whose tools
* cannot vary by request or user input. OAuth itself is not required up front: it is often only
* discovered when the connection is refused, and the caller only asks once a sign-in is pending.
* The declared catalog is required even for a user who holds a cached one from an earlier
* connection: one config then prompts every user at the same point, and a cache that may be stale
* against the server never decides on its own whether sign-in waits.
*/
export function canDeferOAuthSignIn(config: ParsedServerConfig): boolean {
return (
config.oauthPrompt === 'on_use' &&
(config.oauthToolCatalog?.length ?? 0) > 0 &&
!isUserSourced(config) &&
config.obo == null &&
!hasCustomUserVars(config) &&
!hasRuntimeContextPlaceholders(config) &&
!hasChatOnlyHeaders(config)
);
}
/**
* Server instructions fetched from a connection are safe to retain in the
* shared YAML registry only when the connection cannot vary by identity or
* request. `startup: false` is the one context-independent reason startup
* inspection leaves instructions unresolved; every other deferred case can
* expose authenticated or request-specific instructions to another user.
*/
export function canBackfillSharedServerInstructions(config: UserScopedConnectionConfig): boolean {
return (
config.startup === false &&
!hasChatOnlyHeaders(config) &&
!requiresUserScopedConnection(config) &&
/** A configured `oauth` block is identity-scoped even when `requiresOAuth`
* is unset or was stamped `false` by the skipped startup inspection —
* `requiresUserScopedConnection` alone would let it through while
* `isOAuthServer` still arms the OAuth machinery for the unstamped case. */
config.oauth == null &&
config.oauth_headers == null &&
config.apiKey?.source !== 'user'
);
}
/**
* Returns the names of `customUserVars` declared on the server config for which
* the user has not supplied a non-blank value (unset, empty, or whitespace-only
* values count as missing, since they still fail auth). An empty array means
* every declared variable is satisfied (or the server declares none).
*
* Used to gate tool exposure: a server that requires user-provided credentials
* should not surface its tools to the model until those values are set,
* otherwise every tool call fails authentication. See issue #10969.
*/
export function getMissingCustomUserVars(
config: UserScopedConnectionConfig,
providedVars?: Record<string, string> | null,
): string[] {
if (!hasCustomUserVars(config)) {
return [];
}
return requiredCustomUserVars(config).filter((key) => {
const value = providedVars?.[key];
return value == null || (typeof value === 'string' && value.trim() === '');
});
}
/**
* Determines whether a server config is user-sourced (sandboxed placeholder resolution).
* When `source` is set, it is authoritative. When absent (pre-upgrade cached configs),
* falls back to the legacy `dbId` heuristic for backward compatibility.
*/
export function isUserSourced(config: Pick<ParsedServerConfig, 'source' | 'dbId'>): boolean {
return config.source != null ? config.source === 'user' : !!config.dbId;
}
/**
* Resolves the instructions text for a server, mirroring how the inspector fills them:
* an enabled flag resolves to the text fetched from the server, while an operator-authored
* string is used verbatim. Anything else (`false`, unset) yields no instructions.
*/
export function resolveServerInstructions(config: ParsedServerConfig): string | undefined {
const declared = config.serverInstructions;
if (isEnabled(declared)) return config.resolvedInstructions;
return typeof declared === 'string' ? declared : undefined;
}
export type RedactedServerConfig = Partial<ParsedServerConfig> & {
/** True when this config needs chat request fields before it can connect. */
requestScoped?: boolean;
};
/**
* Allowlist-based sanitization for API responses. Only explicitly listed fields are included;
* new fields added to ParsedServerConfig are excluded by default until allowlisted here.
*
* `url` and the oauth flow URLs (`authorization_url`, `token_url`, `revocation_endpoint`) can
* encode internal infrastructure, so they are stripped unless `canEdit` is set: the same
* disclosure threshold the PATCH route enforces. Callers derive `canEdit` per server (operator
* YAML/config-tier servers from the MANAGE_MCP_SERVERS capability, user-sourced servers from
* per-resource ACL EDIT), so a user-sourced config shared view-only does not disclose its URL
* to the viewer.
* DB-stored configs reject ${VAR} patterns at validation time (MCPServerUserInputSchema);
* env variable resolution is handled at the schema/input boundary.
*/
export function redactServerSecrets(
config: ParsedServerConfig,
options?: { canEdit?: boolean },
): RedactedServerConfig {
const safe: RedactedServerConfig = {
type: config.type,
url: config.url,
title: config.title,
description: config.description,
iconPath: config.iconPath,
chatMenu: config.chatMenu,
requiresOAuth: config.requiresOAuth,
capabilities: config.capabilities,
tools: config.tools,
toolFunctions: config.toolFunctions,
initDuration: config.initDuration,
updatedAt: config.updatedAt,
dbId: config.dbId,
/** Trust tier (yaml/config/user) — safe to expose; used by the UI for display purposes. */
source: config.source,
consumeOnly: config.consumeOnly,
inspectionFailed: config.inspectionFailed,
customUserVars: config.customUserVars,
serverInstructions: config.serverInstructions,
/** Safe derived metadata: it exposes no placeholder-bearing value, but lets
* clients attach tools that can only be discovered during a chat turn. */
requestScoped: requiresEphemeralUserConnection(config) || undefined,
};
if (config.apiKey) {
safe.apiKey = {
source: config.apiKey.source,
authorization_type: config.apiKey.authorization_type,
...(config.apiKey.custom_header && { custom_header: config.apiKey.custom_header }),
};
}
if (config.oauth) {
const {
client_secret: _secret,
client_secretPreview: _secretPreview,
...safeOAuth
} = config.oauth;
safe.oauth = safeOAuth;
}
if (config.obo) {
safe.obo = config.obo;
}
if (!options?.canEdit) {
delete safe.url;
if (safe.oauth) {
const {
authorization_url: _au,
token_url: _tu,
revocation_endpoint: _re,
...restOAuth
} = safe.oauth;
safe.oauth = restOAuth;
}
}
return Object.fromEntries(
Object.entries(safe).filter(([, v]) => v !== undefined),
) as RedactedServerConfig;
}
/** Applies allowlist-based sanitization to a map of server configs. */
export function redactAllServerSecrets(
configs: Record<string, ParsedServerConfig>,
options?: { canEditByServer?: ReadonlyMap<string, boolean> },
): Record<string, RedactedServerConfig> {
const result: Record<string, RedactedServerConfig> = {};
for (const [key, config] of Object.entries(configs)) {
const canEdit = options?.canEditByServer?.get(key) ?? false;
result[key] = redactServerSecrets(config, { canEdit });
}
return result;
}
/**
* Builds the synthetic tool-call name used during MCP OAuth flows.
* Format: `oauth<mcp_delimiter><normalizedServerName>`
*
* Guards against the caller passing a pre-wrapped name (one that already
* starts with the oauth prefix in its original, un-normalized form) to
* prevent double-wrapping.
*/
export function buildOAuthToolCallName(serverName: string): string {
const oauthPrefix = `oauth${Constants.mcp_delimiter}`;
if (serverName.startsWith(oauthPrefix)) {
return normalizeServerName(serverName);
}
return `${oauthPrefix}${normalizeServerName(serverName)}`;
}
const INVALID_CLIENT_PATTERNS = [
'invalid_client',
'client_id mismatch',
'client not found',
'unknown client',
] as const;
/** Checks whether a message indicates the stored client registration is invalid/stale. */
export function isInvalidClientMessage(message: string): boolean {
const msg = message.toLowerCase();
return INVALID_CLIENT_PATTERNS.some((p) => msg.includes(p));
}
/**
* Checks whether a message indicates the OAuth client registration was rejected.
* Superset of `isInvalidClientMessage`: also matches `unauthorized_client`
* (grant-type refusal), which has different recovery semantics.
*/
export function isClientRejectionMessage(message: string): boolean {
return isInvalidClientMessage(message) || message.toLowerCase().includes('unauthorized_client');
}
/**
* Sanitizes a URL by removing query parameters to prevent credential leakage in logs.
* @param url - The URL to sanitize (string or URL object)
* @returns The sanitized URL string without query parameters
*/
export function sanitizeUrlForLogging(url: string | URL): string {
try {
const urlObj = typeof url === 'string' ? new URL(url) : url;
return `${urlObj.protocol}//${urlObj.host}${urlObj.pathname}`;
} catch {
return '[invalid URL]';
}
}
/**
* Escapes special regex characters in a string so they are treated literally.
* @param str - The string to escape
* @returns The escaped string safe for use in a regex pattern
*/
export function escapeRegex(str: string): string {
return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}
/**
* Generates a URL-friendly server name from a title.
* Converts to lowercase, replaces spaces with hyphens, removes special characters.
* @param title - The display title to convert
* @returns A slug suitable for use as serverName (e.g., "GitHub MCP Tool" → "github-mcp-tool")
*/
/**
* One cancellation signal for a budgeted operation: the remaining budget and the caller's own
* signal, whichever fires first. Undefined when neither bound exists, so unbudgeted callers pay
* nothing.
*/
export function createDeadlineAbortSignal(
deadlineMs?: number,
callerSignal?: AbortSignal,
): AbortSignal | undefined {
const budget =
deadlineMs != null ? AbortSignal.timeout(Math.max(1, deadlineMs - Date.now())) : undefined;
if (budget != null && callerSignal != null) {
return AbortSignal.any([budget, callerSignal]);
}
return budget ?? callerSignal;
}
export type DeadlineWaitResult<T> = { settled: true; value: T } | { settled: false };
/**
* Waits for `promise` only until `deadlineMs` passes or `signal` aborts, and never cancels it:
* shared work such as an OAuth token refresh keeps running for whoever depends on its outcome. A
* rejection that lands first is rethrown; one that lands after the wait ended stays observed, so
* abandoned work never surfaces as an unhandled rejection.
*/
export async function waitUntilDeadline<T>(
promise: Promise<T>,
deadlineMs?: number,
signal?: AbortSignal,
): Promise<DeadlineWaitResult<T>> {
if (deadlineMs == null && signal == null) {
return { settled: true, value: await promise };
}
const settlement = promise.then((value): DeadlineWaitResult<T> => ({ settled: true, value }));
if (signal?.aborted === true) {
settlement.catch(() => undefined);
return { settled: false };
}
let timer: NodeJS.Timeout | undefined;
let onAbort: (() => void) | undefined;
const interrupted = new Promise<DeadlineWaitResult<T>>((resolve) => {
if (deadlineMs != null) {
timer = setTimeout(() => resolve({ settled: false }), Math.max(0, deadlineMs - Date.now()));
timer.unref?.();
}
if (signal != null) {
onAbort = () => resolve({ settled: false });
signal.addEventListener('abort', onAbort, { once: true });
}
});
try {
return await Promise.race([settlement, interrupted]);
} finally {
clearTimeout(timer);
if (onAbort != null) {
signal?.removeEventListener('abort', onAbort);
}
}
}
export function generateServerNameFromTitle(title: string): string {
const slug = title
.toLowerCase()
.trim()
.replace(/[^a-z0-9\s-]/g, '') // Remove special chars except spaces and hyphens
.replace(/\s+/g, '-') // Replace spaces with hyphens
.replace(/-+/g, '-') // Remove consecutive hyphens
.replace(/^-|-$/g, ''); // Trim leading/trailing hyphens
return slug || 'mcp-server'; // Fallback if empty
}
export {
splitMCPToolKey,
normalizeServerName,
normalizeMCPToolKey,
buildServerNameAliases,
stripServerNamePrefix,
stripServerNamePrefixes,
} from 'librechat-data-provider';