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 { EventEmitter } from 'events';
import { logger } from '@librechat/data-schemas';
import {
CallToolResultSchema,
ReadResourceResultSchema,
ListResourcesResultSchema,
ListResourceTemplatesResultSchema,
McpError,
ErrorCode,
} from '@modelcontextprotocol/sdk/types.js';
import type { TMCPAppsPolicy } from 'librechat-data-provider';
import type { IUser } from '@librechat/data-schemas';
import type { GraphTokenResolver } from '~/utils/graph';
import type * as t from '~/mcp/types';
import {
getMCPConnectionPoolKey,
getMCPUserConnectionPoolKey,
MCP_APPS_CAPABILITY_PROFILE,
STANDARD_MCP_CAPABILITY_PROFILE,
} from '~/mcp/capabilities';
import { OboTokenResolutionError, detectOAuthRequirement, resolveOboToken } from '~/mcp/oauth';
import { withToolApprovalExecution, withToolApprovalTransport } from '~/tools/approval';
import { executionFixture, readTool } from '~/schedules/authorization/execution.helper';
import { createMCPRequestContext, cleanupMCPRequestContext } from '~/mcp/request';
import { MCPServersInitializer } from '~/mcp/registry/MCPServersInitializer';
import { MCPServerInspector } from '~/mcp/registry/MCPServerInspector';
import { ConnectionsRepository } from '~/mcp/ConnectionsRepository';
import { MCPConnectionFactory } from '~/mcp/MCPConnectionFactory';
import { attachScheduledMCPBearer } from '~/schedules/bearer';
import { MCPAuthenticationRejectedError } from '~/mcp/errors';
import { getMCPToolApprovalAuthKind } from '~/mcp/approval';
import { OpenIDReauthRequiredError } from '~/utils/oidc';
import { isMCPDomainAllowed } from '~/auth/domain';
import * as toolsChanged from '~/mcp/toolsChanged';
import { MCPConnection } from '~/mcp/connection';
import { MCPManager } from '~/mcp/MCPManager';
import * as graphUtils from '~/utils/graph';
import { processMCPEnv } from '~/utils/env';
// Mock external dependencies
jest.mock('@librechat/data-schemas', () => ({
logger: {
info: jest.fn(),
warn: jest.fn(),
error: jest.fn(),
debug: jest.fn(),
},
}));
jest.mock('~/utils/graph', () => ({
...jest.requireActual('~/utils/graph'),
preProcessGraphTokens: jest.fn(),
}));
jest.mock('~/mcp/oauth', () => ({
...jest.requireActual('~/mcp/oauth'),
detectOAuthRequirement: jest.fn(),
resolveOboToken: jest.fn(),
}));
/** Only `processMCPEnv` is a deliberate seam — the cases below drive it to hand
* the manager a specific processed config. Everything else stays real:
* `~/mcp/utils` reads `ALLOWED_BODY_FIELDS` from here at module scope, so a
* replacing factory breaks the suite at import time. */
jest.mock('~/utils/env', () => ({
...jest.requireActual('~/utils/env'),
processMCPEnv: jest.fn((params) => params.options),
}));
jest.mock('~/auth/domain', () => ({
isMCPDomainAllowed: jest.fn().mockResolvedValue(true),
}));
const fakeClient = (
request: jest.Mock,
capabilities: object | null = { resources: {}, tools: {} },
) =>
({
request,
getServerCapabilities: () => capabilities ?? undefined,
readResource: (params: unknown, options?: unknown) =>
request({ method: 'resources/read', params }, ReadResourceResultSchema, options),
listResources: (params: unknown, options?: unknown) =>
request(
{ method: 'resources/list', params: params ?? {} },
ListResourcesResultSchema,
options,
),
listResourceTemplates: (params: unknown, options?: unknown) =>
request(
{ method: 'resources/templates/list', params: params ?? {} },
ListResourceTemplatesResultSchema,
options,
),
callTool: (params: unknown, resultSchema?: unknown, options?: unknown) =>
request({ method: 'tools/call', params }, resultSchema ?? CallToolResultSchema, options),
}) as unknown as MCPConnection['client'];
const mockShouldEnableSSRFProtection = jest.fn().mockReturnValue(false);
const mockGetAllowedDomains = jest.fn().mockReturnValue(null);
const mockGetAllowedAddresses = jest.fn().mockReturnValue(null);
const mockRegistryInstance = {
getServerConfig: jest.fn(),
isAppServerConfig: jest.fn(),
isHiddenFromPrincipal: jest.fn(),
getUserHiddenServerNames: jest.fn(async (): Promise<ReadonlySet<string>> => new Set()),
getAllServerConfigs: jest.fn(),
getOAuthServers: jest.fn(),
shouldEnableSSRFProtection: mockShouldEnableSSRFProtection,
getAllowedDomains: mockGetAllowedDomains,
getAllowedAddresses: mockGetAllowedAddresses,
getMCPAppsPolicy: jest.fn().mockReturnValue({ enabled: true, legacyHtmlEnabled: true }),
// Mirrors the real per-request resolver by reading the base-allowlist mocks above, so
// existing tests that override getAllowedDomains/shouldEnableSSRFProtection still apply.
resolveAllowlists: jest.fn(async () => ({
allowedDomains: mockGetAllowedDomains(),
allowedAddresses: mockGetAllowedAddresses(),
useSSRFProtection: mockShouldEnableSSRFProtection(),
mcpApps: { enabled: true, legacyHtmlEnabled: true } as TMCPAppsPolicy,
})),
};
jest.mock('~/mcp/registry/MCPServersRegistry', () => ({
MCPServersRegistry: {
getInstance: () => mockRegistryInstance,
},
}));
jest.mock('~/mcp/registry/MCPServersInitializer', () => ({
MCPServersInitializer: {
initialize: jest.fn(),
},
}));
jest.mock('~/mcp/registry/MCPServerInspector');
jest.mock('~/mcp/ConnectionsRepository');
jest.mock('~/mcp/MCPConnectionFactory');
const mockLogger = logger as jest.Mocked<typeof logger>;
const mockResolveOboToken = resolveOboToken as jest.MockedFunction<typeof resolveOboToken>;
const mockDetectOAuthRequirement = detectOAuthRequirement as jest.MockedFunction<
typeof detectOAuthRequirement
>;
const mockProcessMCPEnv = processMCPEnv as jest.MockedFunction<typeof processMCPEnv>;
const mockIsMCPDomainAllowed = isMCPDomainAllowed as jest.MockedFunction<typeof isMCPDomainAllowed>;
describe('MCPManager', () => {
const userId = 'test-user-123';
const serverName = 'test_server';
beforeEach(() => {
// Reset MCPManager singleton state
(MCPManager as unknown as { instance: null }).instance = null;
jest.clearAllMocks();
// Set up default mock implementations
(MCPServersInitializer.initialize as jest.Mock).mockResolvedValue(undefined);
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'stdio',
command: 'test',
args: [],
source: 'yaml',
});
(mockRegistryInstance.isAppServerConfig as jest.Mock).mockResolvedValue(true);
mockRegistryInstance.isHiddenFromPrincipal.mockResolvedValue(false);
(mockRegistryInstance.shouldEnableSSRFProtection as jest.Mock).mockReturnValue(false);
(mockRegistryInstance.getAllowedDomains as jest.Mock).mockReturnValue(null);
(mockRegistryInstance.getAllowedAddresses as jest.Mock).mockReturnValue(null);
mockProcessMCPEnv.mockImplementation((params) => params.options);
jest.mocked(graphUtils.preProcessGraphTokens).mockImplementation(async (config) => config);
mockIsMCPDomainAllowed.mockResolvedValue(true);
mockDetectOAuthRequirement.mockResolvedValue({
requiresOAuth: false,
method: 'no-metadata-found',
});
});
function mockAppConnections(
appConnectionsConfig: Partial<ConnectionsRepository>,
): jest.MockedClass<typeof ConnectionsRepository> {
const mock = {
has: jest.fn().mockResolvedValue(false),
get: jest.fn().mockResolvedValue({} as unknown as MCPConnection),
getPooledConnection: jest.fn().mockReturnValue(undefined),
getAll: jest.fn().mockResolvedValue(new Map()),
getMany: jest.fn().mockResolvedValue(new Map()),
...appConnectionsConfig,
};
return (
ConnectionsRepository as jest.MockedClass<typeof ConnectionsRepository>
).mockImplementation(() => mock as unknown as ConnectionsRepository);
}
function newMCPServersConfig(serverNameOverride?: string): t.MCPServers {
return {
[serverNameOverride ?? serverName]: {
type: 'stdio',
command: 'test',
args: [],
},
};
}
describe('getAppToolFunctions', () => {
it('exposes shared operator sessions only to the standard profile', async () => {
const loaded = new Map([['shared', {} as MCPConnection]]);
const getLoaded = jest.fn().mockResolvedValue(loaded);
mockAppConnections({ getLoaded });
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(manager.getLoadedAppConnections(STANDARD_MCP_CAPABILITY_PROFILE)).resolves.toBe(
loaded,
);
await expect(manager.getLoadedAppConnections(MCP_APPS_CAPABILITY_PROFILE)).resolves.toEqual(
new Map(),
);
expect(getLoaded).toHaveBeenCalledTimes(1);
});
it('should return empty object when no servers have tool functions', async () => {
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
server1: { type: 'stdio', command: 'test', args: [] },
server2: { type: 'stdio', command: 'test2', args: [] },
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.getAppToolFunctions();
expect(result).toEqual({});
});
it('does not open live connections while collecting the startup snapshot', async () => {
const getAll = jest.fn().mockResolvedValue(new Map());
mockAppConnections({ getAll });
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getAppToolFunctions();
expect(getAll).not.toHaveBeenCalled();
});
it('should collect tool functions from multiple servers', async () => {
const toolFunctions1 = {
tool1_mcp_server1: {
type: 'function' as const,
function: {
name: 'tool1_mcp_server1',
description: 'Tool 1',
parameters: { type: 'object' as const },
},
},
};
const toolFunctions2 = {
tool2_mcp_server2: {
type: 'function' as const,
function: {
name: 'tool2_mcp_server2',
description: 'Tool 2',
parameters: { type: 'object' as const },
},
},
};
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
server1: {
type: 'stdio',
command: 'test',
args: [],
toolFunctions: toolFunctions1,
},
server2: {
type: 'stdio',
command: 'test2',
args: [],
toolFunctions: toolFunctions2,
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.getAppToolFunctions();
expect(result).toEqual({
...toolFunctions1,
...toolFunctions2,
});
});
it('should handle servers with null or undefined toolFunctions', async () => {
const toolFunctions1 = {
tool1_mcp_server1: {
type: 'function' as const,
function: {
name: 'tool1_mcp_server1',
description: 'Tool 1',
parameters: { type: 'object' as const },
},
},
};
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
server1: {
type: 'stdio',
command: 'test',
args: [],
toolFunctions: toolFunctions1,
},
server2: {
type: 'stdio',
command: 'test2',
args: [],
toolFunctions: null,
},
server3: {
type: 'stdio',
command: 'test3',
args: [],
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.getAppToolFunctions();
expect(result).toEqual(toolFunctions1);
});
it('excludes public user-managed servers from the app catalog', async () => {
const operatorKey = 'operator_tool_mcp_operator';
const publicKey = 'public_tool_mcp_public';
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
operator: {
type: 'stdio',
command: 'operator',
source: 'yaml',
toolFunctions: {
[operatorKey]: { type: 'function', function: { name: operatorKey } },
},
},
public: {
type: 'streamable-http',
url: 'https://public.example.com/mcp',
source: 'user',
toolFunctions: {
[publicKey]: { type: 'function', function: { name: publicKey } },
},
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(manager.getAppToolFunctions()).resolves.toEqual({
[operatorKey]: { type: 'function', function: { name: operatorKey } },
});
});
});
describe('withUserConnectionLease', () => {
it('retains a public checkout until its metadata read completes', async () => {
const connection = {} as MCPConnection;
let finishRead: (() => void) | undefined;
const read = new Promise<void>((resolve) => {
finishRead = resolve;
});
mockAppConnections({});
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(connection);
const lifecycle = manager as unknown as {
waitForConnectionBorrowersToDrain: (connection: MCPConnection) => Promise<void>;
};
const checkout = manager.withUserConnectionLease(
{ serverName, user: { id: userId } as IUser },
async () => {
await read;
return 'snapshot';
},
);
await new Promise((resolve) => setImmediate(resolve));
let drained = false;
const drain = lifecycle.waitForConnectionBorrowersToDrain(connection).then(() => {
drained = true;
});
await new Promise((resolve) => setImmediate(resolve));
expect(drained).toBe(false);
finishRead?.();
await expect(checkout).resolves.toBe('snapshot');
await drain;
expect(drained).toBe(true);
});
it('rejoins recovery registered between public checkout and lease acquisition', async () => {
const staleConnection = {} as MCPConnection;
const recoveredConnection = {} as MCPConnection;
let finishCheckout: ((connection: MCPConnection) => void) | undefined;
const checkout = new Promise<MCPConnection>((resolve) => {
finishCheckout = resolve;
});
let finishRecovery: (() => void) | undefined;
const recovery = new Promise<void>((resolve) => {
finishRecovery = resolve;
});
mockAppConnections({});
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest
.spyOn(manager, 'getUserConnection')
.mockReturnValueOnce(checkout)
.mockResolvedValue(recoveredConnection);
const internals = manager as unknown as {
oauthRecoveries: WeakMap<MCPConnection, { promise: Promise<void> }>;
};
const operation = jest.fn().mockResolvedValue('snapshot');
const result = manager.withUserConnectionLease(
{ serverName, user: { id: userId } as IUser },
operation,
);
finishCheckout?.(staleConnection);
internals.oauthRecoveries.set(staleConnection, { promise: recovery });
await new Promise((resolve) => setImmediate(resolve));
expect(operation).not.toHaveBeenCalled();
internals.oauthRecoveries.delete(staleConnection);
finishRecovery?.();
await expect(result).resolves.toBe('snapshot');
expect(operation).toHaveBeenCalledWith(recoveredConnection);
});
});
describe('connectAppServers', () => {
it('opens only operator app connections and refreshes their current catalogs', async () => {
const connection = new MCPConnection({
serverName: 'dynamic',
serverConfig: { type: 'streamable-http', url: 'http://localhost/mcp' },
useSSRFProtection: false,
});
const refreshToolList = jest
.spyOn(connection, 'refreshToolList')
.mockResolvedValue(undefined);
const getMany = jest.fn().mockResolvedValue(new Map([['dynamic', connection]]));
mockAppConnections({ getMany });
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
dynamic: {
type: 'streamable-http',
url: 'http://localhost/mcp',
source: 'yaml',
},
public: {
type: 'streamable-http',
url: 'https://public.example.com/mcp',
source: 'user',
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.connectAppServers();
expect(getMany).toHaveBeenCalledWith(['dynamic'], {
continueOnError: true,
refreshTools: false,
});
expect(refreshToolList).toHaveBeenCalledTimes(1);
});
});
describe('disconnectAppServers', () => {
it('waits for every loaded app connection to disconnect', async () => {
const disconnectAll = jest.fn().mockReturnValue([Promise.resolve(), Promise.resolve()]);
mockAppConnections({ disconnectAll });
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.disconnectAppServers();
expect(disconnectAll).toHaveBeenCalledTimes(1);
});
});
describe('formatInstructionsForContext', () => {
it('should return empty string when no servers have instructions', async () => {
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
server1: { type: 'stdio', command: 'test', args: [] },
server2: { type: 'stdio', command: 'test2', args: [] },
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.formatInstructionsForContext();
expect(result).toBe('');
});
it('should format instructions from multiple servers', async () => {
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
github: {
type: 'sse',
url: 'https://api.github.com',
serverInstructions: 'Use GitHub API with care',
},
files: {
type: 'stdio',
command: 'node',
args: ['files.js'],
serverInstructions: 'Only read/write files in allowed directories',
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.formatInstructionsForContext();
expect(result).toContain('# MCP Server Instructions');
expect(result).toContain('## github MCP Server Instructions');
expect(result).toContain('Use GitHub API with care');
expect(result).toContain('## files MCP Server Instructions');
expect(result).toContain('Only read/write files in allowed directories');
});
it('should filter instructions by server names when provided', async () => {
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
github: {
type: 'sse',
url: 'https://api.github.com',
serverInstructions: 'Use GitHub API with care',
},
files: {
type: 'stdio',
command: 'node',
args: ['files.js'],
serverInstructions: 'Only read/write files in allowed directories',
},
database: {
type: 'stdio',
command: 'node',
args: ['db.js'],
serverInstructions: 'Be careful with database operations',
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.formatInstructionsForContext(['github', 'database']);
expect(result).toContain('## github MCP Server Instructions');
expect(result).toContain('Use GitHub API with care');
expect(result).toContain('## database MCP Server Instructions');
expect(result).toContain('Be careful with database operations');
expect(result).not.toContain('files');
expect(result).not.toContain('Only read/write files in allowed directories');
});
it('should handle servers with null or undefined instructions', async () => {
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
github: {
type: 'sse',
url: 'https://api.github.com',
serverInstructions: 'Use GitHub API with care',
},
files: {
type: 'stdio',
command: 'node',
args: ['files.js'],
serverInstructions: null,
},
database: {
type: 'stdio',
command: 'node',
args: ['db.js'],
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.formatInstructionsForContext();
expect(result).toContain('## github MCP Server Instructions');
expect(result).toContain('Use GitHub API with care');
expect(result).not.toContain('files');
expect(result).not.toContain('database');
});
it('should return empty string when filtered servers have no instructions', async () => {
(mockRegistryInstance.getAllServerConfigs as jest.Mock).mockResolvedValue({
github: {
type: 'sse',
url: 'https://api.github.com',
serverInstructions: 'Use GitHub API with care',
},
files: {
type: 'stdio',
command: 'node',
args: ['files.js'],
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.formatInstructionsForContext(['files']);
expect(result).toBe('');
});
});
describe('getServerToolFunctions', () => {
it('should catch and handle errors gracefully', async () => {
(MCPServerInspector.getToolCatalog as jest.Mock) = jest.fn(() => {
throw new Error('Connection failed');
});
mockAppConnections({
has: jest.fn().mockResolvedValue(true),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.getServerToolFunctions(userId, serverName);
expect(result).toBeNull();
expect(mockLogger.warn).toHaveBeenCalledWith(
`[getServerToolFunctions] Error getting tool functions for server ${serverName}`,
expect.any(Error),
);
});
it('should catch synchronous errors from the profile pool lookup', async () => {
(MCPServerInspector.getToolCatalog as jest.Mock) = jest.fn().mockResolvedValue({ tools: {} });
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const userConnections = (
manager as unknown as { userConnections: Map<string, Map<string, MCPConnection>> }
).userConnections;
const spy = jest.spyOn(userConnections, 'get').mockImplementation(() => {
throw new Error('Failed to get user connections');
});
const result = await manager.getServerToolFunctions(userId, serverName);
expect(result).toBeNull();
expect(mockLogger.warn).toHaveBeenCalledWith(
`[getServerToolFunctions] Error getting tool functions for server ${serverName}`,
expect.any(Error),
);
expect(spy).toHaveBeenCalled();
});
it('should return tools successfully when no errors occur', async () => {
const expectedTools: t.LCAvailableTools = {
[`test_tool_mcp_${serverName}`]: {
type: 'function',
function: {
name: `test_tool_mcp_${serverName}`,
description: 'Test tool',
parameters: { type: 'object' },
},
},
};
(MCPServerInspector.getToolCatalog as jest.Mock) = jest
.fn()
.mockResolvedValue({ tools: expectedTools });
mockAppConnections({
has: jest.fn().mockResolvedValue(true),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.getServerToolFunctions(userId, serverName);
expect(result).toEqual(expectedTools);
expect(mockLogger.warn).not.toHaveBeenCalled();
});
it('leases a cached user connection while reading its tool metadata', async () => {
let finishInspection: ((tools: t.LCAvailableTools) => void) | undefined;
const inspection = new Promise<t.LCAvailableTools>((resolve) => {
finishInspection = resolve;
});
const connection = {} as MCPConnection;
(MCPServerInspector.getToolCatalog as jest.Mock) = jest
.fn()
.mockReturnValue(inspection.then((tools) => ({ tools })));
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const lifecycle = manager as unknown as {
userConnections: Map<string, Map<string, MCPConnection>>;
waitForConnectionBorrowersToDrain: (connection: MCPConnection) => Promise<void>;
};
lifecycle.userConnections.set(
userId,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), connection],
]),
);
const toolsPromise = manager.getServerToolFunctions(userId, serverName);
await new Promise((resolve) => setImmediate(resolve));
let drained = false;
const drainPromise = lifecycle.waitForConnectionBorrowersToDrain(connection).then(() => {
drained = true;
});
await new Promise((resolve) => setImmediate(resolve));
expect(drained).toBe(false);
finishInspection?.({});
await expect(toolsPromise).resolves.toEqual({});
await drainPromise;
expect(drained).toBe(true);
});
it('rejoins recovery after leasing cached tool metadata', async () => {
const staleConnection = {} as MCPConnection;
const recoveredConnection = {} as MCPConnection;
let resolveRecovery: (() => void) | undefined;
const recovery = new Promise<void>((resolve) => {
resolveRecovery = resolve;
});
(MCPServerInspector.getToolCatalog as jest.Mock) = jest.fn().mockResolvedValue({ tools: {} });
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
userId,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), staleConnection],
]),
);
internals.oauthRecoveries.set(staleConnection, {
promise: recovery,
allowsTakeover: true,
});
const toolsPromise = manager.getServerToolFunctions(userId, serverName);
await new Promise((resolve) => setImmediate(resolve));
expect(MCPServerInspector.getToolCatalog).not.toHaveBeenCalled();
internals.userConnections.set(
userId,
new Map([
[
getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE),
recoveredConnection,
],
]),
);
internals.oauthRecoveries.delete(staleConnection);
resolveRecovery?.();
await expect(toolsPromise).resolves.toEqual({});
expect(MCPServerInspector.getToolCatalog).toHaveBeenCalledWith(
serverName,
recoveredConnection,
);
});
it('should include specific server name in error messages', async () => {
const specificServerName = 'github_mcp_server';
(MCPServerInspector.getToolCatalog as jest.Mock) = jest.fn(() => {
throw new Error('Server specific error');
});
mockAppConnections({
has: jest.fn().mockResolvedValue(true),
});
const manager = await MCPManager.createInstance(newMCPServersConfig(specificServerName));
const result = await manager.getServerToolFunctions(userId, specificServerName);
expect(result).toBeNull();
expect(mockLogger.warn).toHaveBeenCalledWith(
`[getServerToolFunctions] Error getting tool functions for server ${specificServerName}`,
expect.any(Error),
);
});
it('uses a user connection when an effective overlay shadows an app server', async () => {
const overlayConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://tenant.example.com/mcp',
source: 'yaml',
startup: false,
};
const overlayConnection = {} as MCPConnection;
const expectedTools: t.LCAvailableTools = {
overlay_mcp_test_server: {
type: 'function',
function: {
name: 'overlay_mcp_test_server',
description: 'Overlay tool',
parameters: { type: 'object' },
},
},
};
const appGet = jest.fn().mockResolvedValue({} as MCPConnection);
mockAppConnections({ get: appGet });
(mockRegistryInstance.isAppServerConfig as jest.Mock).mockResolvedValue(false);
(MCPServerInspector.getToolCatalog as jest.Mock).mockResolvedValue({ tools: expectedTools });
const manager = await MCPManager.createInstance(newMCPServersConfig());
const internals = manager as unknown as {
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
userId,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), overlayConnection],
]),
);
await expect(
manager.getServerToolFunctionsSnapshot(userId, serverName, overlayConfig),
).resolves.toEqual({ tools: expectedTools, publicationGeneration: undefined });
expect(appGet).not.toHaveBeenCalled();
expect(MCPServerInspector.getToolCatalog).toHaveBeenCalledWith(serverName, overlayConnection);
});
});
describe('callTool - Activity Tracking', () => {
const mockUser = { id: 'activity-user' } as IUser;
const mockFlowManager = {} as Parameters<MCPManager['callTool']>[0]['flowManager'];
const serverConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com',
};
function createConnection(): MCPConnection {
return {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
timeout: 30000,
client: {
request: jest.fn().mockResolvedValue({
content: [{ type: 'text', text: 'Tool result' }],
isError: false,
}),
},
} as unknown as MCPConnection;
}
function getManagerInternals(manager: MCPManager): {
userConnections: Map<string, Map<string, MCPConnection>>;
updateUserLastActivity: (trackedUserId: string) => void;
} {
return manager as unknown as {
userConnections: Map<string, Map<string, MCPConnection>>;
updateUserLastActivity: (trackedUserId: string) => void;
};
}
beforeEach(() => {
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
});
it('updates activity when a cached connection is replaced during an in-flight call', async () => {
const manager = new MCPManager();
const activeConnection = createConnection();
const replacementConnection = createConnection();
const internals = getManagerInternals(manager);
internals.userConnections.set(
mockUser.id,
new Map([
[
getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE),
replacementConnection,
],
]),
);
jest.spyOn(manager, 'getConnection').mockResolvedValue(activeConnection);
const updateActivity = jest.spyOn(internals, 'updateUserLastActivity');
await manager.callTool({
user: mockUser,
serverName,
serverConfig,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager,
});
expect(updateActivity).toHaveBeenCalledWith(mockUser.id);
});
it('does not create activity entries for app-shared connections', async () => {
const manager = new MCPManager();
const appConnection = createConnection();
const internals = getManagerInternals(manager);
jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
const updateActivity = jest.spyOn(internals, 'updateUserLastActivity');
await manager.callTool({
user: mockUser,
serverName,
serverConfig,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager,
});
expect(updateActivity).not.toHaveBeenCalled();
expect(manager.getConnectionStats().activityEntries).toBe(0);
});
});
describe('callTool - scheduled authority boundary', () => {
async function setupScheduled(stage: 'invoke' | 'resume' = 'invoke') {
const fixture = await executionFixture(stage);
const request = jest.fn().mockResolvedValue({ content: [{ type: 'text', text: 'read' }] });
const snapshot = jest.fn().mockResolvedValue({ tools: [readTool], complete: true });
const connection = {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
fetchToolsSnapshot: snapshot,
timeout: 30_000,
client: fakeClient(request, { tools: {} }),
} as unknown as MCPConnection;
const manager = new MCPManager();
jest.spyOn(manager, 'getConnection').mockResolvedValue(connection);
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
const call = (agentId = 'root') =>
manager.callTool({
user: fixture.user,
serverName: 'warehouse',
serverConfig: fixture.config,
toolName: 'query',
provider: 'openai',
flowManager: {} as Parameters<MCPManager['callTool']>[0]['flowManager'],
scheduledMCPInvocation: fixture.invocation(agentId),
});
return { fixture, request, snapshot, call };
}
it.each(['root', 'child'])('dispatches an authorized %s read once', async (agentId) => {
const { request, call } = await setupScheduled();
await call(agentId);
expect(request.mock.calls.filter(([input]) => input.method === 'tools/call')).toHaveLength(1);
});
it.each(['revoke', 'expire', 'deny'] as const)(
'never dispatches after %s, including deliberate retries',
async (mutation) => {
const { fixture, request, call } = await setupScheduled('resume');
await fixture[mutation]();
await expect(call()).rejects.toMatchObject({ failure: { automaticReplay: false } });
await expect(call()).rejects.toMatchObject({ failure: { automaticReplay: false } });
expect(request).not.toHaveBeenCalled();
},
);
it('rejects misleading mutating metadata and changed definitions without reaching tools/call', async () => {
const { request, snapshot, call } = await setupScheduled();
snapshot.mockResolvedValue({
tools: [
{
...readTool,
description: 'Read only!',
annotations: { readOnlyHint: true },
inputSchema: { type: 'object', properties: { write: { type: 'boolean' } } },
},
],
complete: true,
});
await expect(call()).rejects.toMatchObject({ failure: { reason: 'tool_policy_denied' } });
expect(request).not.toHaveBeenCalled();
});
it('fences consent revoked during live tools/list immediately before dispatch', async () => {
const { fixture, request, snapshot, call } = await setupScheduled();
snapshot.mockImplementation(async () => {
await fixture.revoke();
return { tools: [readTool], complete: true };
});
await expect(call()).rejects.toMatchObject({ failure: { reason: 'consent_revoked' } });
expect(request).not.toHaveBeenCalled();
});
it('attributes a protected catalog credential rejection without dispatch or provider text', async () => {
const { request, snapshot, call } = await setupScheduled();
snapshot.mockResolvedValue({
tools: [],
complete: false,
authenticationError: Object.assign(new Error('Bearer PRIVATE'), { status: 401 }),
});
let failure: unknown;
try {
await call('child');
} catch (error) {
failure = error;
}
expect(failure).toMatchObject({
failure: {
reason: 'credential_rejected',
status: 'mcp_reauth_required',
automaticReplay: false,
},
outcomes: [expect.objectContaining({ agentId: 'child' })],
});
expect(String(failure)).not.toContain('PRIVATE');
expect(request).not.toHaveBeenCalled();
});
it('never automatically replays a protected call after resource bearer rejection', async () => {
const { request, call } = await setupScheduled();
request.mockRejectedValue(Object.assign(new Error('HTTP 401'), { status: 401 }));
await expect(call()).rejects.toMatchObject({
failure: {
reason: 'credential_rejected',
status: 'mcp_reauth_required',
automaticReplay: false,
},
outcomes: [expect.objectContaining({ agentId: 'root' })],
});
expect(request).toHaveBeenCalledTimes(1);
});
});
describe('callTool - cancellation logging', () => {
const mockUser = { id: 'cancel-user' } as IUser;
const mockFlowManager = {} as Parameters<MCPManager['callTool']>[0]['flowManager'];
const serverConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com',
};
/** Rejects the way the MCP SDK does once a request's signal aborts. */
function createAbortingConnection(): MCPConnection {
return {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
timeout: 30000,
client: {
request: jest.fn(
(_request: unknown, _schema: unknown, options: { signal?: AbortSignal }) =>
new Promise((_resolve, reject) => {
options.signal?.addEventListener('abort', () => reject(options.signal?.reason), {
once: true,
});
}),
),
},
} as unknown as MCPConnection;
}
beforeEach(() => {
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
(logger.error as jest.Mock).mockClear();
(logger.debug as jest.Mock).mockClear();
});
async function callAndAbort(connection: MCPConnection): Promise<unknown> {
const manager = new MCPManager();
jest.spyOn(manager, 'getConnection').mockResolvedValue(connection);
const controller = new AbortController();
const call = manager.callTool({
user: mockUser,
serverName,
serverConfig,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager,
options: { signal: controller.signal },
});
await new Promise((resolve) => setImmediate(resolve));
controller.abort();
return call.catch((error) => error);
}
it('logs a user-aborted tool call at debug rather than as a failure', async () => {
await callAndAbort(createAbortingConnection());
expect(logger.error).not.toHaveBeenCalledWith(
expect.stringContaining('Tool call failed'),
expect.anything(),
);
expect(logger.debug).toHaveBeenCalledWith(
expect.stringContaining('Tool call cancelled by user abort'),
);
});
it('keeps a real failure racing the Stop at error level', async () => {
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
timeout: 30000,
client: {
request: jest.fn(
(_request: unknown, _schema: unknown, options: { signal?: AbortSignal }) =>
new Promise((_resolve, reject) => {
options.signal?.addEventListener(
'abort',
() => reject(new Error('upstream 503 from the MCP server')),
{ once: true },
);
}),
),
},
} as unknown as MCPConnection;
await callAndAbort(connection);
expect(logger.error).toHaveBeenCalledWith(
expect.stringContaining('Tool call failed'),
expect.anything(),
);
});
});
describe('callTool - declared App document acquisition', () => {
const user = { id: 'app-user' } as IUser;
const flowManager = {} as Parameters<MCPManager['callTool']>[0]['flowManager'];
const serverConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com',
};
const resourceUri = 'ui://app';
const toolResult = {
content: [
{ type: 'text' as const, text: 'ordinary output' },
{
type: 'resource' as const,
resource: {
uri: resourceUri,
mimeType: 'text/html;profile=mcp-app',
text: '<p>embedded result</p>',
},
},
],
structuredContent: { count: 1 },
_meta: { result: 'meta' },
isError: false,
};
function connectionFor(request: jest.Mock): MCPConnection {
return {
createdAt: 1,
toolListVersion: 0,
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
getMCPAppRuntimeTarget: jest.fn(() => ({ type: 'sse', url: serverConfig.url })),
timeout: 1234,
fetchOrderedToolsSnapshot: jest.fn().mockResolvedValue({
tools: [
{
name: 'app_tool',
inputSchema: { type: 'object' },
_meta: { ui: { resourceUri } },
},
],
complete: true,
}),
client: fakeClient(request),
} as unknown as MCPConnection;
}
async function callWith(
connection: MCPConnection,
signal?: AbortSignal,
mcpApps: Parameters<MCPManager['callTool']>[0]['mcpApps'] | null = {
enabled: true,
legacyHtmlEnabled: true,
},
) {
const manager = new MCPManager(undefined, undefined, {
create: jest.fn(() => 'binding'),
verify: jest.fn(() => true),
});
jest.spyOn(manager, 'getConnection').mockResolvedValue(connection);
return manager.callTool({
user,
serverName,
serverConfig,
toolName: 'app_tool',
provider: 'openai',
flowManager,
options: { signal },
...(mcpApps ? { mcpApps } : {}),
});
}
it('reads the exact declared document once and preserves the original result separately', async () => {
const request = jest.fn(async ({ method }: { method: string }) => {
if (method === 'tools/call') {
return toolResult;
}
return {
contents: [
{ uri: 'ui://other', mimeType: 'text/html;profile=mcp-app', text: '<p>other</p>' },
{ uri: resourceUri, mimeType: 'text/plain', text: 'wrong mime' },
{
uri: resourceUri,
mimeType: 'text/html;profile=mcp-app',
text: '<p>resources/read document</p>',
_meta: { ui: { csp: { connectDomains: ['https://content.example'] } } },
},
],
};
});
const [, artifacts] = await callWith(connectionFor(request));
const app = artifacts?.ui_resources?.data?.[0];
const calls = request.mock.calls as unknown as Array<
[{ method: string; params?: unknown }, unknown, { timeout?: number }]
>;
expect(calls.map(([request]) => request.method)).toEqual(['tools/call', 'resources/read']);
expect(calls[1][0].params).toEqual({ uri: resourceUri });
expect(calls[1][2]).toMatchObject({ timeout: 1234 });
expect(app).toMatchObject({
uri: resourceUri,
text: '<p>resources/read document</p>',
csp: { connectDomains: ['https://content.example'] },
structuredContent: { count: 1 },
resultMeta: { result: 'meta' },
});
expect(app?.content).toBe(toolResult.content);
});
it('keeps canonical tool output and a bound retryable URI when document reading fails', async () => {
const request = jest.fn(async ({ method }: { method: string }) => {
if (method === 'tools/call') {
return toolResult;
}
throw new Error('resource unavailable');
});
const [text, artifacts] = await callWith(connectionFor(request));
expect(text).toContain('ordinary output');
expect(artifacts?.ui_resources?.data).toEqual([
expect.objectContaining({
uri: resourceUri,
mimeType: 'text/html;profile=mcp-app',
serverBinding: 'binding',
content: toolResult.content,
}),
]);
expect(artifacts?.ui_resources?.data?.[0]).not.toHaveProperty('text');
expect(
request.mock.calls.filter(([request]) => request.method === 'tools/call'),
).toHaveLength(1);
});
it('retains a bound URI without retrying the tool when the shared App budget is full', async () => {
const limits = { maxBytes: 4 * 1024 * 1024, timeoutMs: 30_000, maxActive: 1 };
const manager = new MCPManager(undefined, undefined, {
create: jest.fn(() => 'binding'),
verify: jest.fn(() => true),
});
const request = jest.fn(async ({ method }: { method: string }) => {
if (method === 'tools/call') return toolResult;
throw new Error('resource read must not start when capacity is full');
});
jest.spyOn(manager, 'getConnection').mockResolvedValue(connectionFor(request));
let finish!: () => void;
const occupied = manager.appOperationBudget.run(
new AbortController().signal,
() =>
new Promise<void>((resolve) => {
finish = resolve;
}),
limits,
);
const [text, artifacts] = await manager.callTool({
user,
serverName,
serverConfig,
toolName: 'app_tool',
provider: 'openai',
flowManager,
mcpApps: { enabled: true, legacyHtmlEnabled: true, operationLimits: limits },
});
expect(text).toContain('ordinary output');
expect(artifacts?.ui_resources?.data?.[0]).toMatchObject({
uri: resourceUri,
serverBinding: 'binding',
content: toolResult.content,
});
expect(request.mock.calls.map(([call]) => call.method)).toEqual(['tools/call']);
finish();
await occupied;
});
it('retains the bound URI if the read returns no usable matching App document', async () => {
const request = jest.fn(async ({ method }: { method: string }) =>
method === 'tools/call'
? toolResult
: { contents: [{ uri: resourceUri, mimeType: 'text/plain', text: 'not an app' }] },
);
const [text, artifacts] = await callWith(connectionFor(request));
expect(text).toContain('ordinary output');
expect(artifacts?.ui_resources?.data?.[0]).toMatchObject({
uri: resourceUri,
serverBinding: 'binding',
content: toolResult.content,
});
expect(artifacts?.ui_resources?.data?.[0]?.text).toBeUndefined();
expect(request.mock.calls.filter(([call]) => call.method === 'tools/call')).toHaveLength(1);
});
it('does not read or attach the App when Apps policy denies it', async () => {
const request = jest.fn().mockResolvedValue(toolResult);
const connection = connectionFor(request);
const [, artifacts] = await callWith(connection, undefined, {
enabled: false,
legacyHtmlEnabled: false,
});
expect(request).toHaveBeenCalledTimes(1);
expect(connection.fetchOrderedToolsSnapshot).not.toHaveBeenCalled();
expect(artifacts?.ui_resources).toBeUndefined();
});
it('keeps canonical tool output when no Apps policy was admitted', async () => {
const request = jest.fn().mockResolvedValue(toolResult);
const connection = connectionFor(request);
const [text, artifacts] = await callWith(connection, undefined, null);
expect(text).toContain('ordinary output');
expect(request).toHaveBeenCalledTimes(1);
expect(connection.fetchOrderedToolsSnapshot).not.toHaveBeenCalled();
expect(artifacts?.ui_resources).toBeUndefined();
});
it('keeps canonical tool output when the declared resource read is aborted', async () => {
let readStarted: (() => void) | undefined;
const started = new Promise<void>((resolve) => {
readStarted = resolve;
});
const request = jest.fn(
({ method }: { method: string }, _schema: unknown, options: { signal?: AbortSignal }) => {
if (method === 'tools/call') {
return Promise.resolve(toolResult);
}
readStarted?.();
return new Promise((_resolve, reject) => {
options.signal?.addEventListener('abort', () => reject(options.signal?.reason), {
once: true,
});
});
},
);
const controller = new AbortController();
const call = callWith(connectionFor(request), controller.signal);
await started;
controller.abort(new DOMException('stopped', 'AbortError'));
await expect(call).resolves.toEqual(
expect.arrayContaining([expect.stringContaining('ordinary output')]),
);
expect(
request.mock.calls.filter(([request]) => request.method === 'tools/call'),
).toHaveLength(1);
});
it('keeps canonical tool output when metadata discovery is aborted', async () => {
let snapshotStarted: (() => void) | undefined;
const started = new Promise<void>((resolve) => {
snapshotStarted = resolve;
});
const request = jest.fn().mockResolvedValue(toolResult);
const connection = connectionFor(request);
(connection.fetchOrderedToolsSnapshot as jest.Mock).mockImplementation(
(_deadline: unknown, signal?: AbortSignal) => {
snapshotStarted?.();
return new Promise((_resolve, reject) => {
signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
});
},
);
const controller = new AbortController();
const call = callWith(connection, controller.signal);
await started;
controller.abort(new DOMException('stopped', 'AbortError'));
await expect(call).resolves.toEqual(
expect.arrayContaining([expect.stringContaining('ordinary output')]),
);
expect(request).toHaveBeenCalledTimes(1);
});
it('does not reuse declared App metadata after an incomplete catalog refresh', async () => {
const request = jest.fn(async ({ method }: { method: string }) => {
if (method === 'tools/call') {
return toolResult;
}
return {
contents: [
{
uri: resourceUri,
mimeType: 'text/html;profile=mcp-app',
text: '<p>resources/read document</p>',
},
],
};
});
const connection = connectionFor(request);
const manager = new MCPManager(undefined, undefined, {
create: jest.fn(() => 'binding'),
verify: jest.fn(() => true),
});
jest.spyOn(manager, 'getConnection').mockResolvedValue(connection);
const first = await manager.callTool({
user,
serverName,
serverConfig,
toolName: 'app_tool',
provider: 'openai',
flowManager,
mcpApps: { enabled: true, legacyHtmlEnabled: true },
});
connection.toolListVersion += 1;
(connection.fetchOrderedToolsSnapshot as jest.Mock).mockResolvedValueOnce({
tools: [],
complete: false,
});
const second = await manager.callTool({
user,
serverName,
serverConfig,
toolName: 'app_tool',
provider: 'openai',
flowManager,
mcpApps: { enabled: true, legacyHtmlEnabled: true },
});
expect(first[1]?.ui_resources?.data).toHaveLength(1);
expect(second[1]?.ui_resources).toBeUndefined();
expect(request.mock.calls.map(([request]) => (request as { method: string }).method)).toEqual(
['tools/call', 'resources/read', 'tools/call'],
);
});
it('uses the admitted policy without a post-call policy read', async () => {
const request = jest.fn().mockResolvedValue(toolResult);
mockRegistryInstance.resolveAllowlists.mockClear();
await callWith(connectionFor(request));
expect(mockRegistryInstance.resolveAllowlists).not.toHaveBeenCalled();
});
});
describe('callTool - Graph Token Integration', () => {
const mockUser: Partial<IUser> = {
id: 'user-123',
provider: 'openid',
openidId: 'oidc-sub-456',
};
const mockFlowManager = {
getState: jest.fn(),
setState: jest.fn(),
clearState: jest.fn(),
};
const mockConnection = {
isConnected: jest.fn().mockResolvedValue(true),
refreshToolList: jest.fn().mockResolvedValue(undefined),
disconnect: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
setRequestHeaders: jest.fn(),
timeout: 30000,
client: {
request: jest.fn().mockResolvedValue({
content: [{ type: 'text', text: 'Tool result' }],
isError: false,
}),
},
} as unknown as MCPConnection;
const mockGraphTokenResolver: GraphTokenResolver = jest.fn().mockResolvedValue({
access_token: 'resolved-graph-token',
token_type: 'Bearer',
expires_in: 3600,
scope: 'https://graph.microsoft.com/.default',
});
function createServerConfigWithGraphPlaceholder(): t.SSEOptions {
return {
type: 'sse',
url: 'https://api.example.com',
headers: {
Authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
'Content-Type': 'application/json',
},
};
}
beforeEach(() => {
jest.clearAllMocks();
// Mock preProcessGraphTokens to simulate token resolution
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options, graphOptions) => {
if (
options.headers?.Authorization?.includes('{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}') &&
graphOptions.graphTokenResolver
) {
return {
...options,
headers: {
...options.headers,
Authorization: 'Bearer resolved-graph-token',
},
};
}
return options;
},
);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
});
it('should call preProcessGraphTokens with graphTokenResolver when provided', async () => {
const serverConfig = createServerConfigWithGraphPlaceholder();
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
});
expect(graphUtils.preProcessGraphTokens).toHaveBeenCalledWith(
serverConfig,
expect.objectContaining({
user: mockUser,
graphTokenResolver: mockGraphTokenResolver,
}),
);
});
it('should resolve graph token placeholders in headers before tool call', async () => {
const serverConfig = createServerConfigWithGraphPlaceholder();
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
});
// Verify the connection received the resolved headers
expect(mockConnection.setRequestHeaders).toHaveBeenCalledWith(
expect.objectContaining({
Authorization: 'Bearer resolved-graph-token',
}),
);
});
it('should attach a recovery handler without reprocessing resolved config', async () => {
const rawServerConfig = {
type: 'sse',
url: 'https://api.example.com/{{LIBRECHAT_USER_ID}}',
headers: {
Authorization: 'Bearer {{USER_TOKEN}}',
},
requiresOAuth: true,
oauth: {
authorization_url: 'https://auth.example.com/authorize',
},
} as t.ParsedServerConfig;
const processedServerConfig = {
...rawServerConfig,
url: 'https://api.example.com/user-123',
headers: {
Authorization: 'Bearer ${SHOULD_NOT_EXPAND}',
},
};
const authError = new Error('Non-200 status code (401)');
const connection = Object.assign(new EventEmitter(), {
client: {
request: jest
.fn()
.mockRejectedValueOnce(authError)
.mockResolvedValueOnce({
content: [{ type: 'text', text: 'Recovered result' }],
isError: false,
}),
},
connect: jest.fn().mockResolvedValue(undefined),
getLastConnectionCheckError: jest.fn().mockReturnValue(undefined),
isConnected: jest.fn().mockResolvedValue(true),
isOAuthAuthenticationError: jest.fn((error: unknown) => error === authError),
setRequestHeaders: jest.fn(),
timeout: 30000,
url: processedServerConfig.url,
}) as unknown as MCPConnection;
mockProcessMCPEnv.mockReturnValue(processedServerConfig);
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mockImplementation(
(_basic, _oauth, currentConnection: MCPConnection) => {
const listener = () => currentConnection.emit('oauthHandled');
currentConnection.on('oauthReauthenticationRequired', listener);
return () => currentConnection.off('oauthReauthenticationRequired', listener);
},
);
mockAppConnections({
get: jest.fn().mockResolvedValue(connection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(rawServerConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(connection);
const oauthStart = jest.fn();
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
oauthStart,
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
});
/** callTool resolves the config once; handler attachment does not process it again. */
expect(mockProcessMCPEnv).toHaveBeenCalledTimes(1);
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledWith(
expect.objectContaining({
serverConfig: processedServerConfig,
skipEnvProcessing: true,
}),
expect.objectContaining({
oauthStart: expect.any(Function),
user: mockUser,
}),
connection,
);
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('request-peer-generation');
try {
const oauthOptions = (MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mock
.calls[0][1];
await expect(oauthOptions.onOAuthCredentialsInvalidated()).resolves.toBe(
'request-peer-generation',
);
expect(generationSpy).toHaveBeenCalledWith({ userId: mockUser.id, serverName });
} finally {
generationSpy.mockRestore();
}
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('should leave graph token placeholders sandboxed for user-sourced configs', async () => {
const serverConfig: t.ParsedServerConfig = {
type: 'sse',
url: 'https://api.example.com',
headers: {
Authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
},
source: 'user',
dbId: 'user-server-id',
};
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
});
expect(graphUtils.preProcessGraphTokens).not.toHaveBeenCalled();
expect(mockConnection.setRequestHeaders).toHaveBeenCalledWith(
expect.objectContaining({
Authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
}),
);
});
it('preserves Graph preprocessing for an unrelated server in a scheduled request', async () => {
const config = { ...createServerConfigWithGraphPlaceholder(), source: 'yaml' as const };
const context = createMCPRequestContext();
attachScheduledMCPBearer(context, {
scheduleId: 's1',
ownerId: mockUser.id!,
tenantId: mockUser.tenantId ?? null,
agentId: 'root',
invocationMode: 'delegated',
});
(graphUtils.preProcessGraphTokens as jest.Mock).mockResolvedValue({
...config,
headers: { Authorization: 'Bearer fresh-graph' },
});
mockAppConnections({ get: jest.fn().mockResolvedValue(mockConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(config);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
requestScopedConnections: context,
graphTokenResolver: jest.fn(),
});
expect(mockConnection.setRequestHeaders).toHaveBeenCalledWith(
expect.objectContaining({ Authorization: 'Bearer fresh-graph' }),
);
});
it('should pass options unchanged when no graphTokenResolver is provided', async () => {
const serverConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com',
headers: {
Authorization: 'Bearer static-token',
},
};
// Reset mock to return options unchanged
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
// No graphTokenResolver provided
});
// Verify preProcessGraphTokens was still called (to check for placeholders)
expect(graphUtils.preProcessGraphTokens).toHaveBeenCalledWith(
serverConfig,
expect.objectContaining({
user: mockUser,
graphTokenResolver: undefined,
}),
);
});
it('should handle graph token resolution failure gracefully', async () => {
const serverConfig = createServerConfigWithGraphPlaceholder();
// Simulate resolution failure - returns original value unchanged
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
// Should not throw, even when token resolution fails
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
}),
).resolves.toBeDefined();
// Headers should contain the unresolved placeholder
expect(mockConnection.setRequestHeaders).toHaveBeenCalledWith(
expect.objectContaining({
Authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
}),
);
});
it('should resolve graph tokens in env variables', async () => {
const serverConfig: t.StdioOptions = {
type: 'stdio',
command: 'node',
args: ['server.js'],
env: {
GRAPH_TOKEN: '{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
OTHER_VAR: 'static-value',
},
};
// Mock resolution for env variables
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (options) => {
if (options.env?.GRAPH_TOKEN?.includes('{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}')) {
return {
...options,
env: {
...options.env,
GRAPH_TOKEN: 'resolved-graph-token',
},
};
}
return options;
});
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
});
expect(graphUtils.preProcessGraphTokens).toHaveBeenCalledWith(
serverConfig,
expect.objectContaining({
graphTokenResolver: mockGraphTokenResolver,
}),
);
});
it('should resolve graph tokens in URL', async () => {
const serverConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com?token={{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
};
// Mock resolution for URL
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (options) => {
if (options.url?.includes('{{LIBRECHAT_GRAPH_ACCESS_TOKEN}}')) {
return {
...options,
url: 'https://api.example.com?token=resolved-graph-token',
};
}
return options;
});
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
});
expect(graphUtils.preProcessGraphTokens).toHaveBeenCalledWith(
serverConfig,
expect.objectContaining({
graphTokenResolver: mockGraphTokenResolver,
}),
);
});
it('should pass scopes from environment variable to preProcessGraphTokens', async () => {
const originalEnv = process.env.GRAPH_API_SCOPES;
process.env.GRAPH_API_SCOPES = 'custom.scope.read custom.scope.write';
const serverConfig = createServerConfigWithGraphPlaceholder();
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
});
expect(graphUtils.preProcessGraphTokens).toHaveBeenCalledWith(
serverConfig,
expect.objectContaining({
scopes: 'custom.scope.read custom.scope.write',
}),
);
// Restore environment
if (originalEnv !== undefined) {
process.env.GRAPH_API_SCOPES = originalEnv;
} else {
delete process.env.GRAPH_API_SCOPES;
}
});
it('should work correctly when config has no graph token placeholders', async () => {
const serverConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com',
headers: {
Authorization: 'Bearer static-token',
},
};
// Mock to return unchanged options when no placeholders
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
graphTokenResolver: mockGraphTokenResolver,
});
expect(result).toBeDefined();
expect(mockConnection.setRequestHeaders).toHaveBeenCalledWith(
expect.objectContaining({
Authorization: 'Bearer static-token',
}),
);
});
});
describe('callTool - runtime OAuth recovery', () => {
const mockUser = { id: 'oauth-user' } as IUser;
const mockFlowManager = {} as Parameters<MCPManager['callTool']>[0]['flowManager'];
const serverConfig: t.StreamableHTTPOptions = {
type: 'streamable-http',
url: 'https://mcp.example.com',
requiresOAuth: true,
oauth: {
authorization_url: 'https://auth.example.com/authorize',
},
};
const toolResult = {
content: [{ type: 'text', text: 'Recovered result' }],
isError: false,
};
function createConnection(request: jest.Mock) {
const emitter = new EventEmitter();
return Object.assign(emitter, {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
client: { request },
connect: jest.fn().mockResolvedValue(undefined),
disconnect: jest.fn().mockResolvedValue(undefined),
dispose: jest.fn().mockResolvedValue(undefined),
getLastConnectionCheckError: jest.fn().mockReturnValue(undefined),
isConnected: jest.fn().mockResolvedValue(true),
isOAuthAuthenticationError: jest.fn((error: unknown) => {
return error instanceof Error && error.message.includes('401');
}),
usesOAuth: jest.fn().mockReturnValue(true),
setRequestHeaders: jest.fn(),
timeout: 30000,
url: serverConfig.url,
}) as unknown as MCPConnection;
}
function attachOAuthHandler(
handler: (connection: MCPConnection) => void = (connection) => {
connection.emit('oauthHandled');
},
) {
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mockImplementation(
(_basic, _oauth, connection: MCPConnection) => {
const listener = () => handler(connection);
connection.on('oauthReauthenticationRequired', listener);
return () => connection.off('oauthReauthenticationRequired', listener);
},
);
}
async function callTool(
manager: MCPManager,
signal?: AbortSignal,
oauthStart: t.OAuthStartHandler = jest.fn(),
requestScopedConnections?: t.RequestScopedMCPConnectionStore,
oauthEnd?: () => Promise<void>,
) {
return manager.callTool({
user: mockUser,
serverName,
toolName: 'oauth_tool',
provider: 'openai',
oauthStart,
oauthEnd,
flowManager: mockFlowManager,
requestScopedConnections,
options: signal ? { signal } : undefined,
});
}
async function createManager(connection: MCPConnection) {
mockAppConnections({});
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(connection);
return manager;
}
beforeEach(() => {
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
mockProcessMCPEnv.mockReturnValue(serverConfig);
});
it('refreshes, rebuilds, and retries a rejected tool request once', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
attachOAuthHandler();
const manager = await createManager(connection);
await expect(callTool(manager)).resolves.toBeDefined();
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
expect(request.mock.calls[1]).toEqual(request.mock.calls[0]);
});
it.each([false, true])(
'approval transport fencing handles account replacement=%s after a 401',
async (replaceAccount) => {
let epoch = 'account-a';
const request = jest
.fn()
.mockRejectedValueOnce(new Error('Non-200 status code (401)'))
.mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
connection.getOAuthCredentialSetId = () => epoch;
attachOAuthHandler((active) => {
if (replaceAccount) epoch = 'account-b';
active.emit('oauthHandled');
});
const manager = await createManager(connection);
const guard = jest.fn(async (_serverName: string, currentEpoch: string | null) => {
if (currentEpoch !== 'account-a') throw new Error('Approved OAuth epoch changed');
});
const invoke = () =>
withToolApprovalExecution(
{ validateExecution: async () => {}, validateTransport: guard },
() =>
withToolApprovalTransport(
{ toolCall: { id: 'approved-call' }, metadata: { agentId: 'agent-a' } },
() => callTool(manager),
),
);
if (replaceAccount) {
await expect(invoke()).rejects.toThrow('Approved OAuth epoch changed');
expect(request).toHaveBeenCalledTimes(1);
} else {
await expect(invoke()).resolves.toBeDefined();
expect(request).toHaveBeenCalledTimes(2);
}
expect(guard).toHaveBeenCalledTimes(2);
},
);
it.each([true, false])(
'rechecks reviewed OAuth after scheduled authorization for enrolled=%s',
async (enrolled) => {
let epoch = 'account-a';
const request = jest.fn().mockResolvedValue(toolResult);
const connection = createConnection(request);
connection.getOAuthCredentialSetId = () => epoch;
const manager = await createManager(connection);
const authorize = jest.fn(async () => {
epoch = 'account-b';
});
const guard = jest.fn(async (_server: string, currentEpoch: string | null) => {
if (currentEpoch !== 'account-a') throw new Error('Approved OAuth epoch changed');
});
const invoke = () =>
withToolApprovalExecution(
{ validateExecution: async () => {}, validateTransport: guard },
() =>
withToolApprovalTransport(
{ toolCall: { id: 'approved-call' }, metadata: { agentId: 'root' } },
() =>
manager.callTool({
user: mockUser,
serverName,
toolName: 'oauth_tool',
provider: 'openai',
flowManager: mockFlowManager,
scheduledMCPInvocation: {
identity: {
scheduleId: 'schedule',
ownerId: mockUser.id,
tenantId: null,
agentId: 'root',
invocationMode: 'delegated',
},
enrolled,
agentId: 'root',
authorize,
},
}),
),
);
await expect(invoke()).rejects.toThrow('Approved OAuth epoch changed');
expect(authorize).toHaveBeenCalledTimes(1);
expect(guard).toHaveBeenCalledWith(serverName, 'account-b', expect.any(Object), true);
expect(request).not.toHaveBeenCalled();
expect(connection.connect).not.toHaveBeenCalled();
},
);
it.each([true, false])(
'preserves first JSON-RPC failure without stored-OAuth replay for enrolled=%s',
async (enrolled) => {
const failure = new McpError(ErrorCode.InternalError, 'HTTP 401 invalid_token');
const request = jest.fn().mockRejectedValueOnce(failure).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
attachOAuthHandler();
const manager = await createManager(connection);
const authorize = jest.fn(async () => undefined);
const identity = {
scheduleId: 's',
ownerId: mockUser.id,
tenantId: null,
agentId: 'root',
invocationMode: 'delegated' as const,
};
const result = manager.callTool({
user: mockUser,
serverName,
toolName: 'oauth_tool',
provider: 'openai',
flowManager: mockFlowManager,
oauthStart: jest.fn(),
scheduledMCPInvocation: { identity, enrolled, agentId: 'root', authorize },
});
if (enrolled) await expect(result).rejects.toBe(failure);
else await expect(result).resolves.toBeDefined();
expect(request).toHaveBeenCalledTimes(enrolled ? 1 : 2);
expect(authorize).toHaveBeenCalledTimes(enrolled ? 1 : 2);
expect(connection.connect).toHaveBeenCalledTimes(enrolled ? 0 : 1);
},
);
it('carries the request credential through a delayed 401 after the connection rotates', async () => {
let credential = 'credential-a';
const request = jest
.fn()
.mockImplementationOnce(async () => {
credential = 'credential-b';
throw new Error('Non-200 status code (401)');
})
.mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
connection.getOAuthCredentialSetId = jest.fn(() => credential);
const events: unknown[] = [];
connection.on('oauthReauthenticationRequired', (event) => events.push(event));
attachOAuthHandler();
const manager = await createManager(connection);
await expect(callTool(manager)).resolves.toBeDefined();
expect(events).toEqual([
expect.objectContaining({ rejectedCredentialSetId: 'credential-a' }),
]);
expect(credential).toBe('credential-b');
});
it.each(['credential-a', null])(
'preserves the recorded transport identity %s',
async (rejected) => {
const connection = createConnection(jest.fn().mockResolvedValue(toolResult));
const error = new Error('Non-200 status code (401)');
(connection.isConnected as jest.Mock).mockResolvedValueOnce(false);
(connection.getLastConnectionCheckError as jest.Mock).mockReturnValue(error);
connection.getOAuthCredentialSetId = jest.fn(() => 'credential-b');
connection.getLastConnectionCheckCredentialSetId = jest.fn(() => rejected);
const events: unknown[] = [];
connection.on('oauthReauthenticationRequired', (event) => events.push(event));
attachOAuthHandler();
const manager = await createManager(connection);
await expect(callTool(manager)).resolves.toBeDefined();
expect(events).toEqual([expect.objectContaining({ rejectedCredentialSetId: rejected })]);
},
);
it('joins recovery registered between cached checkout and lease acquisition', async () => {
const request = jest.fn().mockResolvedValue(toolResult);
const connection = createConnection(request);
const manager = await createManager(connection);
let resolveConnection: ((connection: MCPConnection) => void) | undefined;
const firstCheckout = new Promise<MCPConnection>((resolve) => {
resolveConnection = resolve;
});
(manager.getConnection as jest.Mock)
.mockReset()
.mockReturnValueOnce(firstCheckout)
.mockResolvedValue(connection);
let resolveRecovery: (() => void) | undefined;
const recovery = new Promise<void>((resolve) => {
resolveRecovery = resolve;
});
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
};
const toolPromise = callTool(manager);
resolveConnection?.(connection);
internals.oauthRecoveries.set(connection, { promise: recovery, allowsTakeover: true });
await new Promise((resolve) => setImmediate(resolve));
expect(request).not.toHaveBeenCalled();
expect(manager.getConnection).toHaveBeenCalledTimes(1);
internals.oauthRecoveries.delete(connection);
resolveRecovery?.();
await expect(toolPromise).resolves.toBeDefined();
expect(manager.getConnection).toHaveBeenCalledTimes(2);
expect(request).toHaveBeenCalledTimes(1);
});
it('reacquires the cached connection after claiming a failed checkout recovery', async () => {
const staleRequest = jest.fn();
const recoveredRequest = jest.fn().mockResolvedValue(toolResult);
const staleConnection = createConnection(staleRequest);
const recoveredConnection = createConnection(recoveredRequest);
const manager = await createManager(staleConnection);
(manager.getConnection as jest.Mock)
.mockReset()
.mockResolvedValueOnce(staleConnection)
.mockResolvedValue(recoveredConnection);
let rejectRecovery: ((error: Error) => void) | undefined;
const recovery = new Promise<void>((_resolve, reject) => {
rejectRecovery = reject;
});
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
};
internals.oauthRecoveries.set(staleConnection, {
promise: recovery,
allowsTakeover: true,
});
const toolPromise = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
rejectRecovery?.(new Error('Shared recovery failed'));
await expect(toolPromise).resolves.toBeDefined();
expect(manager.getConnection).toHaveBeenCalledTimes(2);
expect(staleRequest).not.toHaveBeenCalled();
expect(recoveredRequest).toHaveBeenCalledTimes(1);
});
it('disposes a recovered connection that was evicted before recovery', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn();
const connection = createConnection(request);
attachOAuthHandler();
const manager = await createManager(connection);
const lifecycle = manager as unknown as {
disposeEvictedConnection: (connection: MCPConnection, logPrefix: string) => Promise<void>;
};
request
.mockImplementationOnce(async () => {
await lifecycle.disposeEvictedConnection(connection, '[MCP][evicted]');
throw authError;
})
.mockResolvedValueOnce(toolResult);
await expect(callTool(manager)).resolves.toBeDefined();
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(connection.dispose).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
});
it('preserves recovery eviction when another borrower releases last', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn();
const connection = createConnection(request);
attachOAuthHandler();
const manager = await createManager(connection);
const lifecycle = manager as unknown as {
disposeEvictedConnection: (connection: MCPConnection, logPrefix: string) => Promise<void>;
retainConnection: (connection: MCPConnection) => void;
releaseConnection: (connection: MCPConnection) => Promise<void>;
};
request
.mockImplementationOnce(async () => {
lifecycle.retainConnection(connection);
await lifecycle.disposeEvictedConnection(connection, '[MCP][evicted]');
throw authError;
})
.mockResolvedValueOnce(toolResult);
const toolPromise = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
expect(connection.connect).not.toHaveBeenCalled();
expect(connection.dispose).not.toHaveBeenCalled();
await lifecycle.releaseConnection(connection);
await expect(toolPromise).resolves.toBeDefined();
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(connection.dispose).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
});
it('preserves eviction requested during a recovery lease gap', async () => {
const connection = createConnection(jest.fn());
const manager = await createManager(connection);
const lifecycle = manager as unknown as {
disposeEvictedConnection: (connection: MCPConnection, logPrefix: string) => Promise<void>;
holdDeferredConnectionDisposal: (connection: MCPConnection) => void;
releaseDeferredConnectionDisposal: (connection: MCPConnection) => Promise<void>;
retainConnection: (connection: MCPConnection) => void;
releaseConnection: (connection: MCPConnection) => Promise<void>;
};
lifecycle.holdDeferredConnectionDisposal(connection);
await lifecycle.disposeEvictedConnection(connection, '[MCP][evicted]');
expect(connection.dispose).not.toHaveBeenCalled();
lifecycle.retainConnection(connection);
await lifecycle.releaseDeferredConnectionDisposal(connection);
await lifecycle.releaseConnection(connection);
expect(connection.dispose).toHaveBeenCalledTimes(1);
});
it('defers final borrower disposal until the recovery hold is released', async () => {
const connection = createConnection(jest.fn());
const manager = await createManager(connection);
const lifecycle = manager as unknown as {
disposeEvictedConnection: (connection: MCPConnection, logPrefix: string) => Promise<void>;
holdDeferredConnectionDisposal: (connection: MCPConnection) => void;
releaseDeferredConnectionDisposal: (connection: MCPConnection) => Promise<void>;
retainConnection: (connection: MCPConnection) => void;
releaseConnection: (connection: MCPConnection) => Promise<void>;
};
lifecycle.holdDeferredConnectionDisposal(connection);
lifecycle.retainConnection(connection);
await lifecycle.disposeEvictedConnection(connection, '[MCP][evicted]');
await lifecycle.releaseConnection(connection);
expect(connection.dispose).not.toHaveBeenCalled();
await lifecycle.releaseDeferredConnectionDisposal(connection);
expect(connection.dispose).toHaveBeenCalledTimes(1);
});
it('recovers an OAuth failure found by the connection preflight check', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
(connection.isConnected as jest.Mock).mockResolvedValue(false);
(connection.getLastConnectionCheckError as jest.Mock).mockReturnValue(authError);
attachOAuthHandler();
const manager = await createManager(connection);
await expect(callTool(manager)).resolves.toBeDefined();
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(1);
});
it('recovers when OAuth was detected from the resolved connection config', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
const runtimeConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/users/{{LIBRECHAT_USER_ID}}/mcp',
source: 'yaml',
};
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(runtimeConfig);
mockProcessMCPEnv.mockReturnValue({
...runtimeConfig,
url: 'https://api.example.com/users/oauth-user/mcp',
});
attachOAuthHandler();
const manager = await createManager(connection);
await expect(callTool(manager)).resolves.toBeDefined();
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
});
it('keeps the request OAuth handler attached through reconnect-time OAuth', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
(connection.connect as jest.Mock)
.mockImplementationOnce(async () => {
const emitted = connection.emit('oauthReauthenticationRequired', {
serverName,
error: authError,
serverUrl: serverConfig.url,
userId: mockUser.id,
});
if (!emitted) {
throw new Error('Reconnect OAuth handler missing');
}
throw new Error('Connection not established');
})
.mockResolvedValueOnce(undefined);
const oauthHandler = jest.fn((currentConnection: MCPConnection) => {
currentConnection.emit('oauthHandled');
});
attachOAuthHandler(oauthHandler);
const manager = await createManager(connection);
await expect(callTool(manager)).resolves.toBeDefined();
expect(oauthHandler).toHaveBeenCalledTimes(2);
expect(connection.connect).toHaveBeenCalledTimes(2);
expect(request).toHaveBeenCalledTimes(2);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('escalates to interactive OAuth when reconnect rejects a silently refreshed token', async () => {
const authError = new Error('Non-200 status code (401)');
const reconnectError = new Error('Connection not established');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
(connection.connect as jest.Mock)
.mockImplementationOnce(async () => {
connection.emit('oauthHandled', 'silent-refresh');
throw reconnectError;
})
.mockResolvedValueOnce(undefined);
const recoveryEvents: Array<{ skipSilentRefresh?: boolean }> = [];
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mockImplementation(
(_basic, _oauth, currentConnection: MCPConnection) => {
const listener = (data: { skipSilentRefresh?: boolean }) => {
recoveryEvents.push(data);
currentConnection.emit(
'oauthHandled',
data.skipSilentRefresh ? 'interactive' : 'silent-refresh',
);
};
currentConnection.on('oauthReauthenticationRequired', listener);
return () => currentConnection.off('oauthReauthenticationRequired', listener);
},
);
const manager = await createManager(connection);
await expect(callTool(manager)).resolves.toBeDefined();
expect(recoveryEvents).toHaveLength(2);
expect(recoveryEvents[0].skipSilentRefresh).toBeUndefined();
expect(recoveryEvents[1].skipSilentRefresh).toBe(true);
expect(connection.connect).toHaveBeenCalledTimes(2);
expect(request).toHaveBeenCalledTimes(2);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('does not start a second recovery when the retried request is rejected', async () => {
const firstError = new Error('Non-200 status code (401)');
const secondError = new Error('Non-200 status code (401) again');
const request = jest
.fn()
.mockRejectedValueOnce(firstError)
.mockRejectedValueOnce(secondError);
const connection = createConnection(request);
attachOAuthHandler();
const manager = await createManager(connection);
await expect(callTool(manager)).rejects.toBe(secondError);
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
});
it('returns the original error when OAuth recovery fails', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError);
const connection = createConnection(request);
attachOAuthHandler((currentConnection) => {
currentConnection.emit('oauthFailed', new Error('Refresh rejected'));
});
const manager = await createManager(connection);
await expect(callTool(manager)).rejects.toBe(authError);
expect(connection.connect).not.toHaveBeenCalled();
expect(request).toHaveBeenCalledTimes(1);
});
it('does not recover or retry non-authentication failures', async () => {
const toolError = new Error('Tool execution failed');
const request = jest.fn().mockRejectedValueOnce(toolError);
const connection = createConnection(request);
attachOAuthHandler();
const manager = await createManager(connection);
await expect(callTool(manager)).rejects.toBe(toolError);
expect(MCPConnectionFactory.attachRequestOAuthHandler).not.toHaveBeenCalled();
expect(connection.connect).not.toHaveBeenCalled();
expect(request).toHaveBeenCalledTimes(1);
});
it('shares one OAuth handler and connection rebuild across concurrent rejected calls', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest
.fn()
.mockRejectedValueOnce(authError)
.mockRejectedValueOnce(authError)
.mockResolvedValue(toolResult);
const connection = createConnection(request);
let finishConnect: (() => void) | undefined;
(connection.connect as jest.Mock).mockImplementation(
() =>
new Promise<void>((resolve) => {
finishConnect = resolve;
}),
);
const oauthHandler = jest.fn((currentConnection: MCPConnection) => {
currentConnection.emit('oauthHandled');
});
attachOAuthHandler(oauthHandler);
const manager = await createManager(connection);
const firstCall = callTool(manager);
const secondCall = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
finishConnect?.();
await expect(Promise.all([firstCall, secondCall])).resolves.toHaveLength(2);
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
expect(oauthHandler).toHaveBeenCalledTimes(1);
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(4);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('lets an aborted runtime waiter leave without cancelling the recovery owner', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValue(authError);
const connection = createConnection(request);
attachOAuthHandler(() => undefined);
const manager = await createManager(connection);
const controller = new AbortController();
const abortReason = new Error('waiter aborted');
const ownerCall = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
const waiterCall = callTool(manager, controller.signal);
await new Promise((resolve) => setImmediate(resolve));
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
controller.abort(abortReason);
await expect(waiterCall).rejects.toBe(abortReason);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(1);
connection.emit('oauthFailed', new Error('Recovery owner aborted'));
await expect(ownerCall).rejects.toBe(authError);
expect(connection.connect).not.toHaveBeenCalled();
expect(request).toHaveBeenCalledTimes(1);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('lets an aborted recovery owner leave while a live waiter completes recovery', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
attachOAuthHandler(() => undefined);
const manager = await createManager(connection);
const controller = new AbortController();
const abortReason = new Error('owner aborted');
const ownerCall = callTool(manager, controller.signal);
await new Promise((resolve) => setImmediate(resolve));
const waiterCall = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
controller.abort(abortReason);
await expect(ownerCall).rejects.toBe(abortReason);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(1);
connection.emit('oauthHandled');
await expect(waiterCall).resolves.toBeDefined();
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
expect(
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mock.calls[0][1].signal,
).toBeUndefined();
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('relays an active recovery prompt to a joining request', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValue(toolResult);
const connection = createConnection(request);
const ownerOAuthStart = jest.fn().mockResolvedValue(undefined);
const waiterOAuthStart = jest.fn().mockResolvedValue(undefined);
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mockImplementation(
(_basic, oauth: { oauthStart?: t.OAuthStartHandler }, currentConnection: MCPConnection) => {
const listener = () => {
void oauth.oauthStart?.('https://auth.example.com/pending');
};
currentConnection.on('oauthReauthenticationRequired', listener);
return () => currentConnection.off('oauthReauthenticationRequired', listener);
},
);
const manager = await createManager(connection);
const ownerCall = callTool(manager, undefined, ownerOAuthStart);
await new Promise((resolve) => setImmediate(resolve));
expect(ownerOAuthStart).toHaveBeenCalledWith('https://auth.example.com/pending', undefined);
const waiterCall = callTool(manager, undefined, waiterOAuthStart);
await new Promise((resolve) => setImmediate(resolve));
expect(waiterOAuthStart).toHaveBeenCalledWith('https://auth.example.com/pending', undefined);
connection.emit('oauthHandled');
await expect(Promise.all([ownerCall, waiterCall])).resolves.toHaveLength(2);
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(3);
});
it('relays OAuth completion to live waiters without failing recovery on notification errors', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValue(toolResult);
const connection = createConnection(request);
const ownerOAuthStart = jest.fn().mockResolvedValue(undefined);
const waiterOAuthStart = jest.fn().mockResolvedValue(undefined);
const ownerOAuthEnd = jest.fn().mockRejectedValue(new Error('owner response is stale'));
const waiterOAuthEnd = jest.fn().mockResolvedValue(undefined);
let completeOAuth: (() => void) | undefined;
const completionGate = new Promise<void>((resolve) => {
completeOAuth = resolve;
});
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mockImplementation(
(
_basic,
oauth: {
oauthStart?: t.OAuthStartHandler;
oauthEnd?: () => Promise<void>;
},
currentConnection: MCPConnection,
) => {
const listener = async () => {
await oauth.oauthStart?.('https://auth.example.com/pending');
await completionGate;
try {
await oauth.oauthEnd?.();
currentConnection.emit('oauthHandled');
} catch (error) {
currentConnection.emit('oauthFailed', error);
}
};
currentConnection.on('oauthReauthenticationRequired', listener);
return () => currentConnection.off('oauthReauthenticationRequired', listener);
},
);
const manager = await createManager(connection);
const ownerCall = callTool(manager, undefined, ownerOAuthStart, undefined, ownerOAuthEnd);
await new Promise((resolve) => setImmediate(resolve));
const waiterCall = callTool(manager, undefined, waiterOAuthStart, undefined, waiterOAuthEnd);
await new Promise((resolve) => setImmediate(resolve));
completeOAuth?.();
await expect(Promise.all([ownerCall, waiterCall])).resolves.toHaveLength(2);
expect(ownerOAuthEnd).toHaveBeenCalledTimes(1);
expect(waiterOAuthEnd).toHaveBeenCalledTimes(1);
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(3);
});
it('defers request-context cleanup until shared recovery settles', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
attachOAuthHandler(() => undefined);
const manager = await createManager(connection);
const requestContext = createMCPRequestContext();
requestContext.connections.set(
getMCPUserConnectionPoolKey(mockUser.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
connection,
);
const toolPromise = callTool(manager, undefined, jest.fn(), requestContext);
await new Promise((resolve) => setImmediate(resolve));
await cleanupMCPRequestContext(requestContext);
expect(connection.dispose).not.toHaveBeenCalled();
expect(requestContext.connections.size).toBe(0);
connection.emit('oauthHandled');
await expect(toolPromise).resolves.toBeDefined();
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(connection.dispose).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
});
it('retries transient reconnect failures within the recovery budget', async () => {
const authError = new Error('Non-200 status code (401)');
const transientError = new Error('Connection reset');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
(connection.connect as jest.Mock)
.mockRejectedValueOnce(transientError)
.mockResolvedValueOnce(undefined);
attachOAuthHandler();
const manager = await createManager(connection);
const retryPolicy = manager as unknown as {
waitForOAuthReconnectRetry: (attempt: number) => Promise<void>;
};
const waitForRetry = jest
.spyOn(retryPolicy, 'waitForOAuthReconnectRetry')
.mockResolvedValue(undefined);
await expect(callTool(manager)).resolves.toBeDefined();
expect(waitForRetry).toHaveBeenCalledWith(1);
expect(connection.connect).toHaveBeenCalledTimes(2);
expect(request).toHaveBeenCalledTimes(2);
});
it('disposes a recovered connection explicitly disconnected during recovery', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError).mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
attachOAuthHandler(() => undefined);
const manager = await createManager(connection);
const internals = manager as unknown as {
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
mockUser.id,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), connection],
]),
);
const toolPromise = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
await manager.disconnectUserConnection(mockUser.id, serverName);
expect(internals.userConnections.get(mockUser.id)).toBeUndefined();
expect(connection.dispose).not.toHaveBeenCalled();
connection.emit('oauthHandled');
await expect(toolPromise).resolves.toBeDefined();
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(connection.dispose).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(2);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('keeps recovery disposal owned after the request owner aborts', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError);
const connection = createConnection(request);
attachOAuthHandler(() => undefined);
const manager = await createManager(connection);
const lifecycle = manager as unknown as {
disposeEvictedConnection: (connection: MCPConnection, logPrefix: string) => Promise<void>;
};
const controller = new AbortController();
const abortReason = new Error('request aborted');
const ownerCall = callTool(manager, controller.signal);
await new Promise((resolve) => setImmediate(resolve));
controller.abort(abortReason);
await expect(ownerCall).rejects.toBe(abortReason);
await lifecycle.disposeEvictedConnection(connection, '[MCP][evicted]');
expect(connection.dispose).not.toHaveBeenCalled();
connection.emit('oauthHandled');
await new Promise((resolve) => setImmediate(resolve));
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(connection.dispose).toHaveBeenCalledTimes(1);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('defers ephemeral disposal until an aborted OAuth recovery settles', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValueOnce(authError);
const connection = createConnection(request);
attachOAuthHandler(() => undefined);
const manager = await createManager(connection);
const ephemeralConfig: t.StreamableHTTPOptions = {
...serverConfig,
url: 'https://mcp.example.com/{{LIBRECHAT_BODY_CONVERSATIONID}}',
};
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(ephemeralConfig);
mockProcessMCPEnv.mockReturnValue({
...ephemeralConfig,
url: 'https://mcp.example.com/conversation-1',
});
const controller = new AbortController();
const abortReason = new Error('request aborted');
const toolCall = manager.callTool({
user: mockUser,
serverName,
toolName: 'oauth_tool',
provider: 'openai',
oauthStart: jest.fn(),
flowManager: mockFlowManager,
requestBody: { conversationId: 'conversation-1' },
options: { signal: controller.signal },
});
await new Promise((resolve) => setImmediate(resolve));
controller.abort(abortReason);
await expect(toolCall).rejects.toBe(abortReason);
expect(connection.dispose).not.toHaveBeenCalled();
connection.emit('oauthHandled');
await new Promise((resolve) => setImmediate(resolve));
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(connection.dispose).toHaveBeenCalledTimes(1);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('lets a live waiter recover after the recovery owner fails', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest
.fn()
.mockRejectedValueOnce(authError)
.mockRejectedValueOnce(authError)
.mockResolvedValueOnce(toolResult);
const connection = createConnection(request);
let attachmentCount = 0;
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mockImplementation(
(_basic, _oauth, currentConnection: MCPConnection) => {
const currentAttachment = ++attachmentCount;
const listener = () => {
if (currentAttachment === 2) {
currentConnection.emit('oauthHandled');
}
};
currentConnection.on('oauthReauthenticationRequired', listener);
return () => currentConnection.off('oauthReauthenticationRequired', listener);
},
);
const manager = await createManager(connection);
const ownerCall = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
const waiterCall = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
connection.emit('oauthFailed', new Error('Recovery owner aborted'));
await expect(ownerCall).rejects.toBe(authError);
await expect(waiterCall).resolves.toBeDefined();
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(2);
expect(connection.connect).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledTimes(3);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('restarts checkout when a post-request recovery waiter claims takeover', async () => {
const authError = new Error('Non-200 status code (401)');
const staleRequest = jest.fn().mockRejectedValue(authError);
const recoveredRequest = jest.fn().mockResolvedValue(toolResult);
const staleConnection = createConnection(staleRequest);
const recoveredConnection = createConnection(recoveredRequest);
attachOAuthHandler(() => undefined);
const manager = await createManager(staleConnection);
let currentConnection = staleConnection;
(manager.getConnection as jest.Mock).mockImplementation(async () => currentConnection);
const ownerCall = callTool(manager);
const waiterCall = callTool(manager);
await new Promise((resolve) => setImmediate(resolve));
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
currentConnection = recoveredConnection;
staleConnection.emit('oauthFailed', new Error('Recovery owner failed'));
await expect(ownerCall).rejects.toBe(authError);
await expect(waiterCall).resolves.toBeDefined();
expect(staleRequest).toHaveBeenCalledTimes(2);
expect(recoveredRequest).toHaveBeenCalledTimes(1);
expect(staleConnection.connect).not.toHaveBeenCalled();
expect(recoveredConnection.connect).not.toHaveBeenCalled();
expect(staleConnection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('caps waiter takeover after a shared recovery keeps failing', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValue(authError);
const connection = createConnection(request);
let attachmentCount = 0;
(MCPConnectionFactory.attachRequestOAuthHandler as jest.Mock).mockImplementation(
(_basic, _oauth, currentConnection: MCPConnection) => {
attachmentCount += 1;
const listener = () => {
currentConnection.emit('oauthFailed', new Error('OAuth denied'));
};
currentConnection.on('oauthReauthenticationRequired', listener);
return () => currentConnection.off('oauthReauthenticationRequired', listener);
},
);
const manager = await createManager(connection);
const calls = [callTool(manager), callTool(manager), callTool(manager), callTool(manager)];
const results = await Promise.allSettled(calls);
expect(results.every((result) => result.status === 'rejected')).toBe(true);
expect(attachmentCount).toBe(2);
expect(connection.connect).not.toHaveBeenCalled();
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
it('allows only one checkout waiter to claim a failed recovery takeover', async () => {
const authError = new Error('Non-200 status code (401)');
const request = jest.fn().mockRejectedValue(authError);
const connection = createConnection(request);
attachOAuthHandler((currentConnection) => {
currentConnection.emit('oauthFailed', new Error('OAuth denied'));
});
const manager = await createManager(connection);
let rejectRecovery: ((error: Error) => void) | undefined;
const recovery = new Promise<void>((_resolve, reject) => {
rejectRecovery = reject;
});
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean; takeoverClaimed?: boolean }
>;
};
internals.oauthRecoveries.set(connection, {
promise: recovery,
allowsTakeover: true,
});
const calls = [callTool(manager), callTool(manager), callTool(manager), callTool(manager)];
await new Promise((resolve) => setImmediate(resolve));
internals.oauthRecoveries.delete(connection);
rejectRecovery?.(new Error('Shared recovery failed'));
const results = await Promise.allSettled(calls);
expect(results.every((result) => result.status === 'rejected')).toBe(true);
expect(request).toHaveBeenCalledTimes(1);
expect(MCPConnectionFactory.attachRequestOAuthHandler).toHaveBeenCalledTimes(1);
expect(connection.listenerCount('oauthReauthenticationRequired')).toBe(0);
});
});
describe('getUserConnection - recovery lifecycle', () => {
const mockUser = { id: 'recovery-user' } as IUser;
const serverConfig: t.StreamableHTTPOptions = {
type: 'streamable-http',
url: 'https://mcp.example.com',
requiresOAuth: false,
};
it('forwards the OAuth credential mutation callback to the connection factory', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
refreshToolList: jest.fn().mockResolvedValue({ tools: [] }),
on: jest.fn(),
} as unknown as MCPConnection;
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const onOAuthCredentialsChanged = jest.fn().mockResolvedValue(undefined);
const oauthConfig = { ...serverConfig, requiresOAuth: true };
await manager.getUserConnection({
serverName,
user: mockUser,
serverConfig: oauthConfig,
flowManager: {} as Parameters<typeof manager.getUserConnection>[0]['flowManager'],
onOAuthCredentialsChanged,
});
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({ serverName }),
expect.objectContaining({
useOAuth: true,
onOAuthCredentialsChanged,
}),
);
});
it('detects direct-bearer mode when the Authorization template lives in requestHeaders', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
refreshToolList: jest.fn().mockResolvedValue({ tools: [] }),
on: jest.fn(),
} as unknown as MCPConnection;
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'live-token' });
await manager.getUserConnection({
serverName,
user: { id: 'direct-user', provider: 'openid', openidId: 'direct-subject' } as IUser,
serverConfig: {
...serverConfig,
source: 'yaml',
requestHeaders: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
} as t.ParsedServerConfig,
flowManager: {} as Parameters<typeof manager.getUserConnection>[0]['flowManager'],
upstreamTokenProvider,
});
/** The manager's own bearer decisions read the config directly, so the map
* has to be folded in before them or a 401 never reaches recovery. */
expect(upstreamTokenProvider).toHaveBeenCalled();
const createCalls = (MCPConnectionFactory.create as jest.Mock).mock.calls;
const [basic] = createCalls[createCalls.length - 1];
expect(basic.directBearerSourceConfig).toBeDefined();
expect(basic.serverConfig.headers).toEqual({ Authorization: 'Bearer live-token' });
expect(basic.serverConfig).not.toHaveProperty('requestHeaders');
expect(basic.serverDefinition.requestHeaders).toEqual({
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
});
const published = jest.fn();
toolsChanged.setMCPToolsChangedHandler(published);
try {
const listener = (connection.on as jest.Mock).mock.calls.find(
([event]) => event === 'toolsChanged',
)?.[1];
listener([]);
await new Promise<void>((resolve) => setImmediate(resolve));
expect(published).toHaveBeenCalledWith(
expect.objectContaining({
serverConfig: basic.serverDefinition,
}),
);
} finally {
toolsChanged.setMCPToolsChangedHandler(null);
}
});
it('waits for an active recovery before reusing a cached connection', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
let resolveRecovery: (() => void) | undefined;
const recovery = new Promise<void>((resolve) => {
resolveRecovery = resolve;
});
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
mockUser.id,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), connection],
]),
);
internals.oauthRecoveries.set(connection, { promise: recovery, allowsTakeover: true });
const connectionPromise = manager.getUserConnection({
serverName,
user: mockUser,
serverConfig,
});
await new Promise((resolve) => setImmediate(resolve));
expect(connection.isConnected).not.toHaveBeenCalled();
resolveRecovery?.();
await expect(connectionPromise).resolves.toBe(connection);
expect(connection.isConnected).toHaveBeenCalledTimes(1);
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('rechecks recovery after yielding to load connection configuration', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
let resolveConfig: ((config: t.ParsedServerConfig) => void) | undefined;
(mockRegistryInstance.getServerConfig as jest.Mock).mockReturnValue(
new Promise<t.ParsedServerConfig>((resolve) => {
resolveConfig = resolve;
}),
);
const manager = await MCPManager.createInstance(newMCPServersConfig());
let recovered = false;
const connection = {
disconnect: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockImplementation(async () => recovered),
isStale: jest.fn().mockReturnValue(false),
} as unknown as MCPConnection;
let resolveRecovery: (() => void) | undefined;
const recovery = new Promise<void>((resolve) => {
resolveRecovery = resolve;
});
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
mockUser.id,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), connection],
]),
);
const connectionPromise = manager.getUserConnection({
serverName,
user: mockUser,
});
await new Promise((resolve) => setImmediate(resolve));
internals.oauthRecoveries.set(connection, { promise: recovery, allowsTakeover: true });
resolveConfig?.(serverConfig);
await new Promise((resolve) => setImmediate(resolve));
expect(connection.disconnect).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
recovered = true;
resolveRecovery?.();
await expect(connectionPromise).resolves.toBe(connection);
expect(connection.isConnected).toHaveBeenCalledTimes(1);
expect(connection.disconnect).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('replaces stale configuration without waiting for obsolete recovery', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const staleConnection = {
disconnect: jest.fn().mockResolvedValue(undefined),
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(false),
isStale: jest.fn().mockReturnValue(true),
} as unknown as MCPConnection;
const replacementConnection = {
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
refreshToolList: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const recovery = new Promise<void>(() => undefined);
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
retainConnection: (connection: MCPConnection) => void;
releaseConnection: (connection: MCPConnection) => Promise<void>;
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
mockUser.id,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), staleConnection],
]),
);
internals.retainConnection(staleConnection);
internals.oauthRecoveries.set(staleConnection, {
promise: recovery,
allowsTakeover: true,
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(replacementConnection);
const updatedConfig = { ...serverConfig, updatedAt: Date.now() };
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
serverConfig: updatedConfig,
}),
).resolves.toBe(replacementConnection);
expect(staleConnection.dispose).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
await internals.releaseConnection(staleConnection);
expect(staleConnection.dispose).toHaveBeenCalledTimes(1);
});
it('lets an aborted waiter leave without cancelling the shared recovery', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const recovery = new Promise<void>(() => undefined);
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
mockUser.id,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), connection],
]),
);
internals.oauthRecoveries.set(connection, { promise: recovery, allowsTakeover: true });
const controller = new AbortController();
const abortReason = new Error('request aborted');
const connectionPromise = manager.getUserConnection({
serverName,
user: mockUser,
serverConfig,
signal: controller.signal,
});
controller.abort(abortReason);
await expect(connectionPromise).rejects.toBe(abortReason);
expect(internals.oauthRecoveries.get(connection)?.promise).toBe(recovery);
expect(connection.isConnected).not.toHaveBeenCalled();
});
it('evicts an inactive cached connection without disconnecting current borrowers', async () => {
const unusableConnection = {
disconnect: jest.fn().mockResolvedValue(undefined),
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(false),
} as unknown as MCPConnection;
const replacementConnection = {
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
refreshToolList: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(replacementConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const lifecycle = manager as unknown as {
retainConnection: (connection: MCPConnection) => void;
releaseConnection: (connection: MCPConnection) => Promise<void>;
};
(
manager as unknown as { userConnections: Map<string, Map<string, MCPConnection>> }
).userConnections.set(
mockUser.id,
new Map([
[
getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE),
unusableConnection,
],
]),
);
lifecycle.retainConnection(unusableConnection);
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
serverConfig,
}),
).resolves.toBe(replacementConnection);
expect(unusableConnection.dispose).not.toHaveBeenCalled();
await lifecycle.releaseConnection(unusableConnection);
expect(unusableConnection.dispose).toHaveBeenCalledTimes(1);
});
it('disposes an inactive cached connection immediately when it has no borrowers', async () => {
const unusableConnection = {
disconnect: jest.fn().mockResolvedValue(undefined),
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(false),
} as unknown as MCPConnection;
const replacementConnection = {
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
refreshToolList: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(replacementConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
(
manager as unknown as { userConnections: Map<string, Map<string, MCPConnection>> }
).userConnections.set(
mockUser.id,
new Map([
[
getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE),
unusableConnection,
],
]),
);
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
serverConfig,
}),
).resolves.toBe(replacementConnection);
expect(unusableConnection.dispose).toHaveBeenCalledTimes(1);
});
it('evicts an inactive request connection without disconnecting current borrowers', async () => {
const requestConnection = {
disconnect: jest.fn().mockResolvedValue(undefined),
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(false),
} as unknown as MCPConnection;
const replacementConnection = {
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
refreshToolList: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const requestScopedConnections: t.RequestScopedMCPConnectionStore = {
connections: new Map([
[
getMCPUserConnectionPoolKey(mockUser.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
requestConnection,
],
]),
pending: new Map(),
};
const bodyScopedConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/{{LIBRECHAT_BODY_MESSAGEID}}',
source: 'yaml',
requiresOAuth: false,
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace('{{LIBRECHAT_BODY_MESSAGEID}}', body?.messageId ?? ''),
}),
}));
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(replacementConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const lifecycle = manager as unknown as {
retainConnection: (connection: MCPConnection) => void;
releaseConnection: (connection: MCPConnection) => Promise<void>;
};
lifecycle.retainConnection(requestConnection);
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
serverConfig: bodyScopedConfig,
requestBody: { messageId: 'message-1' },
requestScopedConnections,
}),
).resolves.toBe(replacementConnection);
expect(requestConnection.dispose).not.toHaveBeenCalled();
await lifecycle.releaseConnection(requestConnection);
expect(requestConnection.dispose).toHaveBeenCalledTimes(1);
});
it('propagates a failed recovery before checking the cached connection', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const recoveryError = new Error('OAuth denied');
const recovery = Promise.reject(recoveryError);
const internals = manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{ promise: Promise<void>; allowsTakeover: boolean }
>;
userConnections: Map<string, Map<string, MCPConnection>>;
};
internals.userConnections.set(
mockUser.id,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), connection],
]),
);
internals.oauthRecoveries.set(connection, { promise: recovery, allowsTakeover: true });
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
serverConfig,
}),
).rejects.toBe(recoveryError);
expect(connection.isConnected).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
});
describe('callTool - OBO Integration', () => {
const mockUser: Partial<IUser> = {
id: 'user-123',
provider: 'openid',
openidId: 'oidc-sub-456',
};
const mockFlowManager = {
getState: jest.fn(),
setState: jest.fn(),
clearState: jest.fn(),
};
const mockConnection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
setOAuthTokens: jest.fn(),
timeout: 30000,
client: {
request: jest.fn().mockResolvedValue({
content: [{ type: 'text', text: 'Tool result' }],
isError: false,
}),
},
} as unknown as MCPConnection;
const mockOboTokenResolver = jest.fn();
const mockUpstreamTokenProvider = jest.fn().mockResolvedValue({
access_token: 'live-access-token',
id_token: 'live-id-token',
expires_at: Math.floor(Date.now() / 1000) + 3600,
});
const serverConfig: t.SSEOptions & { obo: { scopes: string } } = {
type: 'sse',
url: 'https://api.example.com',
headers: {
Authorization: 'Bearer bootstrap-token',
},
obo: {
scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite',
},
};
beforeEach(() => {
mockResolveOboToken.mockReset();
mockUpstreamTokenProvider.mockClear();
});
it('should bypass shared app connections for OBO servers and use a user-scoped connection', async () => {
const sharedAppConnection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
setOAuthTokens: jest.fn(),
timeout: 30000,
client: {
request: jest.fn().mockResolvedValue({
content: [{ type: 'text', text: 'Shared tool result' }],
isError: false,
}),
},
} as unknown as MCPConnection;
const userConnection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
setOAuthTokens: jest.fn(),
timeout: 30000,
client: {
request: jest.fn().mockResolvedValue({
content: [{ type: 'text', text: 'User tool result' }],
isError: false,
}),
},
} as unknown as MCPConnection;
const appConnections = {
get: jest.fn().mockResolvedValue(sharedAppConnection),
};
mockResolveOboToken.mockResolvedValue({
access_token: 'fresh-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
});
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(userConnection);
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
});
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnectionSpy).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
connectionTarget: { serverConfig, connectionOwner: 'operator' },
user: mockUser,
}),
);
expect(userConnection.setRequestHeaders as jest.Mock).toHaveBeenCalledWith(
expect.objectContaining({
Authorization: 'Bearer fresh-obo-token',
}),
);
expect(sharedAppConnection.setRequestHeaders as jest.Mock).not.toHaveBeenCalled();
expect(userConnection.client.request as jest.Mock).toHaveBeenCalled();
expect(sharedAppConnection.client.request as jest.Mock).not.toHaveBeenCalled();
});
it('should replace Authorization with the refreshed OBO token on each tool call', async () => {
mockResolveOboToken.mockResolvedValue({
access_token: 'fresh-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
});
const appConnections = {
get: jest.fn().mockResolvedValue(mockConnection),
};
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(mockConnection);
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
});
expect(mockResolveOboToken).toHaveBeenCalledWith(
mockUser,
serverConfig.obo,
mockOboTokenResolver,
mockUpstreamTokenProvider,
undefined,
false,
);
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnectionSpy).toHaveBeenCalled();
expect(mockConnection.setRequestHeaders).toHaveBeenCalledWith(
expect.objectContaining({
Authorization: 'Bearer fresh-obo-token',
}),
);
expect(mockConnection.client.request).toHaveBeenCalled();
});
it.each([undefined, new Error('owner stopped'), 'stopped'])(
'detaches a cancelled tool from an uncooperative OBO exchange (%s)',
async (reason) => {
const controller = new AbortController();
mockResolveOboToken.mockImplementationOnce(() => {
queueMicrotask(() => controller.abort(reason));
return new Promise(() => {});
});
mockAppConnections({ get: jest.fn().mockResolvedValue(mockConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
options: { signal: controller.signal },
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
}),
).rejects.toMatchObject({ name: 'AbortError' });
expect(mockConnection.client.request).not.toHaveBeenCalled();
},
);
it('lazily resolves the upstream provider for an OBO tool call', async () => {
mockResolveOboToken.mockImplementationOnce(async (_user, _config, _exchange, provider) => {
await provider();
return {
access_token: 'fresh-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
};
});
mockAppConnections({ get: jest.fn().mockResolvedValue(mockConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
const upstreamTokenProviderResolver = jest.fn().mockResolvedValue(mockUpstreamTokenProvider);
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProviderResolver,
});
expect(upstreamTokenProviderResolver).toHaveBeenCalledTimes(1);
expect(upstreamTokenProviderResolver).toHaveBeenCalledWith(
expect.objectContaining({
target: { mcpServer: serverName, scopes: serverConfig.obo?.scopes },
}),
);
expect(mockResolveOboToken).toHaveBeenCalledWith(
mockUser,
serverConfig.obo,
mockOboTokenResolver,
expect.any(Function),
undefined,
false,
);
});
it('does not resolve an OBO provider for a non-OBO tool call', async () => {
const directConfig = {
type: 'streamable-http',
url: 'https://direct.example.com',
headers: { Authorization: 'Bearer static-token' },
} as t.ParsedServerConfig;
mockAppConnections({ get: jest.fn().mockResolvedValue(mockConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
const upstreamTokenProviderResolver = jest.fn();
await manager.callTool({
user: mockUser as IUser,
serverName,
serverConfig: directConfig,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
upstreamTokenProviderResolver,
});
expect(upstreamTokenProviderResolver).not.toHaveBeenCalled();
});
it('passes the OBO-cleaned config into runtime header processing', async () => {
const mixedConfig = {
...serverConfig,
source: 'yaml' as const,
headers: {
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
'X-Service': 'private-mcp',
},
};
mockResolveOboToken.mockResolvedValue({
access_token: 'fresh-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(mixedConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
});
expect(mockProcessMCPEnv).toHaveBeenCalledWith(
expect.objectContaining({
options: expect.objectContaining({
headers: { 'X-Service': 'private-mcp' },
}),
}),
);
expect(mockConnection.setRequestHeaders).toHaveBeenCalledWith({
'X-Service': 'private-mcp',
Authorization: 'Bearer fresh-obo-token',
});
});
it('should fail closed with a retryable message when per-call OBO refresh has a transient failure', async () => {
mockResolveOboToken.mockRejectedValue(
new OboTokenResolutionError(
'exchange_failed',
'Temporary OBO token exchange failure.',
true,
),
);
const appConnections = {
get: jest.fn().mockResolvedValue(mockConnection),
};
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(mockConnection);
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
}),
).rejects.toMatchObject({
message: expect.stringContaining('Temporary OBO token exchange failure.'),
});
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnectionSpy).toHaveBeenCalled();
expect(mockConnection.setRequestHeaders).not.toHaveBeenCalled();
expect(mockConnection.client.request).not.toHaveBeenCalled();
expect(mockLogger.error).toHaveBeenCalledWith(
expect.stringContaining('[test_tool] Tool call failed'),
expect.anything(),
);
});
it('should fail closed with a re-authentication message when per-call OBO refresh has a permanent failure', async () => {
mockResolveOboToken.mockRejectedValue(
new OboTokenResolutionError(
'exchange_failed',
'The identity provider rejected the OBO token exchange.',
),
);
const appConnections = {
get: jest.fn().mockResolvedValue(mockConnection),
};
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(mockConnection);
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
}),
).rejects.toMatchObject({
message: expect.stringContaining('verify the configured OBO scopes'),
});
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnectionSpy).toHaveBeenCalled();
expect(mockConnection.setRequestHeaders).not.toHaveBeenCalled();
expect(mockConnection.client.request).not.toHaveBeenCalled();
});
it('should fail with an internal error when upstreamTokenProvider is omitted on an OBO call', async () => {
const appConnections = {
get: jest.fn().mockResolvedValue(mockConnection),
};
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(mockConnection);
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
/** upstreamTokenProvider intentionally omitted */
}),
).rejects.toMatchObject({
cause: expect.objectContaining({ reason: 'missing_upstream_provider', retryable: false }),
});
expect(mockResolveOboToken).not.toHaveBeenCalled();
});
it.each([true, false])(
'does not replay an enrolled OBO JSON-RPC invalid_token failure, enrolled=%s',
async (enrolled) => {
const failure = new McpError(ErrorCode.InternalError, 'invalid_token');
const request = jest
.fn()
.mockRejectedValueOnce(failure)
.mockResolvedValueOnce({ content: [{ type: 'text', text: 'retried' }] });
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
setOAuthTokens: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
timeout: 30000,
client: { request },
} as unknown as MCPConnection;
mockResolveOboToken.mockResolvedValue({
access_token: 'current-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
});
mockAppConnections({ get: jest.fn().mockResolvedValue(connection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(connection);
const authorize = jest.fn(async () => undefined);
const identity = {
scheduleId: 's',
ownerId: String(mockUser.id),
tenantId: null,
agentId: 'root',
invocationMode: 'delegated' as const,
};
const result = manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
scheduledMCPInvocation: { identity, enrolled, agentId: 'root', authorize },
});
if (enrolled) await expect(result).rejects.toBe(failure);
else await expect(result).resolves.toBeDefined();
expect(request).toHaveBeenCalledTimes(enrolled ? 1 : 2);
expect(authorize).toHaveBeenCalledTimes(enrolled ? 1 : 2);
expect(mockResolveOboToken).toHaveBeenCalledTimes(enrolled ? 1 : 2);
},
);
it('re-exchanges past the token cache when the server rejects the bearer mid-call', async () => {
const authError = new Error('HTTP 401 Unauthorized');
const rejectingConnection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
setOAuthTokens: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
timeout: 30000,
client: {
request: jest
.fn()
.mockRejectedValueOnce(authError)
.mockResolvedValueOnce({
content: [{ type: 'text', text: 'Tool result' }],
isError: false,
}),
},
} as unknown as MCPConnection;
mockResolveOboToken
.mockResolvedValueOnce({
access_token: 'rejected-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
})
.mockResolvedValueOnce({
access_token: 'reminted-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
});
mockAppConnections({ get: jest.fn().mockResolvedValue(rejectingConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(rejectingConnection);
await manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
});
/** The rejected token is still inside its cached lifetime, so the cache is bypassed. */
expect(mockResolveOboToken).toHaveBeenNthCalledWith(
2,
mockUser,
serverConfig.obo,
mockOboTokenResolver,
mockUpstreamTokenProvider,
undefined,
true,
);
expect(rejectingConnection.setRequestHeaders as jest.Mock).toHaveBeenLastCalledWith(
expect.objectContaining({ Authorization: 'Bearer reminted-obo-token' }),
);
/**
* A legacy SSE event stream reads its bearer from `oauthTokens` at transport
* construction and never sees runtime request headers, so leaving the rejected
* credential there would 401 the next rebuild and retire a recovered connection.
*/
expect(rejectingConnection.setOAuthTokens as jest.Mock).toHaveBeenLastCalledWith(
expect.objectContaining({ access_token: 'reminted-obo-token' }),
);
expect((rejectingConnection.client.request as jest.Mock).mock.calls).toHaveLength(2);
});
it('does not retry a non-auth failure', async () => {
const toolError = new Error('tool blew up');
const failingConnection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
setOAuthTokens: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(false),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(toolError) },
} as unknown as MCPConnection;
mockResolveOboToken.mockResolvedValue({
access_token: 'fresh-obo-token',
token_type: 'Bearer',
obtained_at: Date.now(),
expires_at: Date.now() + 3600_000,
});
mockAppConnections({ get: jest.fn().mockResolvedValue(failingConnection) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest.spyOn(manager, 'getUserConnection').mockResolvedValue(failingConnection);
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
toolName: 'test_tool',
provider: 'openai',
flowManager: mockFlowManager as unknown as Parameters<
typeof manager.callTool
>[0]['flowManager'],
oboTokenResolver: mockOboTokenResolver,
upstreamTokenProvider: mockUpstreamTokenProvider,
}),
).rejects.toThrow('tool blew up');
expect(mockResolveOboToken).toHaveBeenCalledTimes(1);
expect((failingConnection.client.request as jest.Mock).mock.calls).toHaveLength(1);
});
});
describe('direct OpenID bearer recovery', () => {
const serverName = 'direct-bearer-server';
const serverConfig = {
type: 'streamable-http' as const,
url: 'https://api.example.com/mcp',
source: 'yaml' as const,
headers: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
};
const user = {
id: 'direct-user',
provider: 'openid',
openidId: 'direct-subject',
} as IUser;
it.each(['headers', 'requestHeaders'] as const)(
'refreshes %s without replaying a rejected tool call or losing its declaration',
async (headerMap) => {
const declared: t.ParsedServerConfig = {
...serverConfig,
headers: undefined,
[headerMap]: serverConfig.headers,
...(headerMap === 'requestHeaders' && {
apiKey: {
source: 'admin' as const,
authorization_type: 'bearer' as const,
key: 'catalog-key',
},
}),
};
const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
stopReconnecting: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(rejection) },
} as unknown as MCPConnection;
const replacement = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const upstreamTokenProvider = jest
.fn()
.mockResolvedValueOnce({ access_token: 'current-token' })
.mockResolvedValueOnce({ access_token: 'refreshed-token' });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (config) => config,
);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(declared);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnection = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValueOnce(connection)
.mockResolvedValueOnce(replacement);
await expect(
manager.callTool({
user,
serverName,
toolName: 'mutating_tool',
provider: 'openai',
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: true,
} satisfies Partial<MCPAuthenticationRejectedError>);
expect(connection.client.request).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).toHaveBeenNthCalledWith(2, {
forceRefresh: true,
signal: expect.any(AbortSignal),
});
expect(connection.stopReconnecting).toHaveBeenCalled();
expect(getUserConnection).toHaveBeenLastCalledWith(
expect.objectContaining({
forceNew: true,
serverConfig: declared,
directBearerRecoveryState: expect.objectContaining({ attempted: true }),
directBearerResolvedConfig: expect.objectContaining({
headers: { Authorization: 'Bearer refreshed-token' },
}),
}),
);
},
);
it('preserves a JSON-RPC tool failure that mentions downstream authentication', async () => {
const toolError = new McpError(ErrorCode.InternalError, 'downstream HTTP 401 invalid_token');
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
stopReconnecting: jest.fn(),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(toolError) },
} as unknown as MCPConnection;
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'valid-token' });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const checkout = jest.spyOn(manager, 'getConnection').mockResolvedValue(connection);
await expect(
manager.callTool({
user,
serverName,
serverConfig,
toolName: 'mutating_tool',
provider: 'openai',
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
}),
).rejects.toBe(toolError);
expect(checkout).toHaveBeenCalledTimes(1);
expect(connection.stopReconnecting).not.toHaveBeenCalled();
expect(upstreamTokenProvider).not.toHaveBeenCalledWith({ forceRefresh: true });
});
it('reuses a recovered checkout bearer for the first tool request without another session read', async () => {
const makeConnection = () =>
({
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
setRequestHeaders: jest.fn(),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
timeout: 30000,
refreshToolList: jest.fn().mockResolvedValue({ tools: [], complete: true }),
client: {
request: jest.fn().mockResolvedValue({ content: [{ type: 'text', text: 'done' }] }),
},
}) as unknown as MCPConnection;
const rejected = makeConnection();
const replacement = makeConnection();
(rejected.refreshToolList as jest.Mock).mockResolvedValue({
tools: [],
complete: false,
authenticationError: Object.assign(new Error('unauthorized'), { status: 401 }),
});
const upstreamTokenProvider = jest
.fn()
.mockResolvedValueOnce({ access_token: 'stale-token' })
.mockResolvedValueOnce({ access_token: 'fresh-token' });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(rejected)
.mockResolvedValueOnce(replacement);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.callTool({
user,
serverName,
serverConfig,
toolName: 'mutating_tool',
provider: 'openai',
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
});
expect(upstreamTokenProvider.mock.calls).toEqual([
[{ forceRefresh: false }],
[{ forceRefresh: true }],
]);
expect(replacement.setRequestHeaders).toHaveBeenCalledWith({
Authorization: 'Bearer fresh-token',
});
expect(rejected.client.request).not.toHaveBeenCalled();
expect(replacement.client.request).toHaveBeenCalledTimes(1);
});
it('shares a checkout recovery budget with the rejected tool call', async () => {
const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
stopReconnecting: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(rejection) },
} as unknown as MCPConnection;
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'fresh-token' });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnection = jest
.spyOn(manager, 'getUserConnection')
.mockImplementation(async (options) => {
options.directBearerRecoveryState!.attempted = true;
return connection;
});
await expect(
manager.callTool({
user,
serverName,
toolName: 'mutating_tool',
provider: 'openai',
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: false,
} satisfies Partial<MCPAuthenticationRejectedError>);
expect(connection.client.request).toHaveBeenCalledTimes(1);
expect(connection.stopReconnecting).not.toHaveBeenCalled();
expect(getUserConnection).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).not.toHaveBeenCalledWith({ forceRefresh: true });
});
it('propagates direct recovery registered during the base cached checkout', async () => {
let finishConnectionCheck: ((connected: boolean) => void) | undefined;
const connectionCheck = new Promise<boolean>((resolve) => {
finishConnectionCheck = resolve;
});
const connection = {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
isConnected: jest.fn().mockReturnValueOnce(connectionCheck).mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
} as unknown as MCPConnection;
let finishRecovery: (() => void) | undefined;
const recovery = new Promise<void>((resolve) => {
finishRecovery = resolve;
});
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const internals = manager as unknown as {
userConnections: Map<string, Map<string, MCPConnection>>;
oauthRecoveries: WeakMap<
MCPConnection,
{
promise: Promise<void>;
allowsTakeover: boolean;
directBearerRecoveryConsumed: boolean;
directBearerRecoveryState?: t.DirectBearerRecoveryState;
}
>;
};
internals.userConnections.set(
user.id,
new Map([
[getMCPConnectionPoolKey(serverName, STANDARD_MCP_CAPABILITY_PROFILE), connection],
]),
);
const directBearerRecoveryState: t.DirectBearerRecoveryState = { attempted: false };
const sharedState: t.DirectBearerRecoveryState = { attempted: true };
const checkout = manager.getUserConnection({
serverName,
serverConfig,
user,
directBearerRecoveryState,
});
while ((connection.isConnected as jest.Mock).mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
internals.oauthRecoveries.set(connection, {
promise: recovery,
allowsTakeover: false,
directBearerRecoveryConsumed: true,
directBearerRecoveryState: sharedState,
});
finishConnectionCheck?.(true);
await new Promise((resolve) => setImmediate(resolve));
expect(directBearerRecoveryState.attempted).toBe(true);
internals.oauthRecoveries.delete(connection);
sharedState.resolvedConfig = {
...serverConfig,
headers: { Authorization: 'Bearer recovered-token' },
};
finishRecovery?.();
await expect(checkout).resolves.toBe(connection);
expect(connection.isConnected).toHaveBeenCalledTimes(2);
expect(directBearerRecoveryState.resolvedConfig).toBe(sharedState.resolvedConfig);
});
it.each([false, true])(
'propagates a connection leader recovery budget to a pending checkout joiner (request-scoped=%s)',
async (requestScoped) => {
const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
const checkoutConfig = requestScoped
? {
...serverConfig,
headers: {
...serverConfig.headers,
'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
}
: serverConfig;
const requestScopedConnections = requestScoped
? {
connections: new Map<string, unknown>(),
pending: new Map<string, Promise<unknown>>(),
}
: undefined;
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
setRequestHeaders: jest.fn(),
stopReconnecting: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
refreshToolList: jest.fn().mockResolvedValue({ tools: [], complete: true }),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(rejection) },
} as unknown as MCPConnection;
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'fresh-token' });
let releaseCreation: (() => void) | undefined;
const creationGate = new Promise<void>((resolve) => {
releaseCreation = resolve;
});
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (config) => config,
);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(checkoutConfig);
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(MCPConnectionFactory.create as jest.Mock).mockImplementation(
async (basic: t.BasicConnectionOptions) => {
basic.directBearerRecoveryState!.attempted = true;
await creationGate;
return connection;
},
);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const invocation = () =>
manager.callTool({
user,
serverName,
serverConfig: checkoutConfig,
toolName: 'mutating_tool',
provider: 'openai',
requestBody: requestScoped ? { conversationId: 'conversation-1' } : undefined,
requestScopedConnections,
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
});
const leader = invocation();
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
const joiner = invocation();
await new Promise((resolve) => setImmediate(resolve));
releaseCreation?.();
await Promise.all([
expect(leader).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: false,
}),
expect(joiner).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: false,
}),
]);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
expect(connection.client.request).toHaveBeenCalledTimes(2);
expect(upstreamTokenProvider).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).not.toHaveBeenCalledWith({ forceRefresh: true });
},
);
it('propagates an active direct recovery budget to a checkout waiter', async () => {
const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
const oldConnection = {
isConnected: jest.fn().mockResolvedValue(false),
} as unknown as MCPConnection;
const replacement = {
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
stopReconnecting: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(rejection) },
} as unknown as MCPConnection;
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'fresh-token' });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest
.spyOn(manager, 'getConnection')
.mockResolvedValueOnce(oldConnection)
.mockResolvedValueOnce(replacement);
(
manager as unknown as {
oauthRecoveries: WeakMap<
MCPConnection,
{
promise: Promise<void>;
allowsTakeover: boolean;
directBearerRecoveryConsumed: boolean;
}
>;
}
).oauthRecoveries.set(oldConnection, {
promise: Promise.resolve(),
allowsTakeover: false,
directBearerRecoveryConsumed: true,
});
await expect(
manager.callTool({
user,
serverName,
serverConfig,
toolName: 'mutating_tool',
provider: 'openai',
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: false,
});
expect(replacement.client.request).toHaveBeenCalledTimes(1);
expect(replacement.stopReconnecting).not.toHaveBeenCalled();
expect(upstreamTokenProvider).not.toHaveBeenCalledWith({ forceRefresh: true });
});
it('installs an ephemeral replacement in the request-scoped store without leaking the old connection', async () => {
const rejection = Object.assign(new Error('HTTP 401 Unauthorized'), { status: 401 });
const scopedConfig = {
...serverConfig,
headers: {
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
};
const connection = {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
isConnected: jest.fn().mockResolvedValue(true),
setRequestHeaders: jest.fn(),
stopReconnecting: jest.fn(),
isOAuthAuthenticationError: jest.fn().mockReturnValue(true),
timeout: 30000,
client: { request: jest.fn().mockRejectedValue(rejection) },
} as unknown as MCPConnection;
const replacement = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const requestScopedConnections = {
connections: new Map([
[
getMCPUserConnectionPoolKey(user.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
connection,
],
]),
pending: new Map(),
};
const upstreamTokenProvider = jest
.fn()
.mockResolvedValueOnce({ access_token: 'current-token' })
.mockResolvedValueOnce({ access_token: 'refreshed-token' });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(async (config) => config);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(scopedConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const disposeEvicted = jest
.spyOn(
manager as unknown as {
disposeEvictedConnection: (
connection: MCPConnection,
logPrefix: string,
) => Promise<void>;
},
'disposeEvictedConnection',
)
.mockResolvedValue(undefined);
jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValueOnce(connection)
.mockImplementationOnce(async () => {
requestScopedConnections.connections.set(
getMCPUserConnectionPoolKey(user.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
replacement,
);
return replacement;
});
await expect(
manager.callTool({
user,
serverName,
serverConfig: scopedConfig,
toolName: 'mutating_tool',
provider: 'openai',
requestBody: { conversationId: 'conversation-1' } as Parameters<
typeof manager.callTool
>[0]['requestBody'],
requestScopedConnections,
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
}),
).rejects.toMatchObject({ code: 'MCP_AUTHENTICATION_REJECTED' });
expect(disposeEvicted).toHaveBeenCalledWith(
connection,
expect.stringContaining('Request-scoped'),
);
expect(
requestScopedConnections.connections.get(
getMCPUserConnectionPoolKey(user.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
),
).toBe(replacement);
expect(connection.client.request).toHaveBeenCalledTimes(1);
});
it.each(['before', 'refresh', 'drain'] as const)(
'stops direct-bearer recovery when cancelled during %s',
async (abortAt) => {
const controller = new AbortController();
const cancelled = new Error('request stopped');
const connection = {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
stopReconnecting: jest.fn(),
} as unknown as MCPConnection;
const upstreamTokenProvider = jest.fn(async () => {
if (abortAt === 'refresh') {
controller.abort(cancelled);
}
return { access_token: 'fresh-token' };
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnection = jest.spyOn(manager, 'getUserConnection');
const internals = manager as unknown as {
waitForConnectionBorrowersToDrain: (connection: MCPConnection) => Promise<void>;
recoverDirectOpenIDBearerConnection: (args: {
connection: MCPConnection;
serverName: string;
serverConfig: t.ParsedServerConfig;
user: IUser;
flowManager: Parameters<typeof manager.callTool>[0]['flowManager'];
upstreamTokenProvider: NonNullable<
Parameters<typeof manager.callTool>[0]['upstreamTokenProvider']
>;
signal: AbortSignal;
}) => Promise<void>;
};
jest.spyOn(internals, 'waitForConnectionBorrowersToDrain').mockImplementation(async () => {
if (abortAt === 'drain') {
controller.abort(cancelled);
}
});
if (abortAt === 'before') {
controller.abort(cancelled);
}
await expect(
internals.recoverDirectOpenIDBearerConnection({
connection,
serverName,
serverConfig,
user,
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
signal: controller.signal,
}),
).rejects.toBe(cancelled);
await new Promise((resolve) => setImmediate(resolve));
expect(upstreamTokenProvider).toHaveBeenCalledTimes(abortAt === 'before' ? 0 : 1);
expect(getUserConnection).not.toHaveBeenCalled();
},
);
it.each(['refresh', 'drain', 'initialize'] as const)(
'keeps shared recovery alive after its leader aborts during %s',
async (stage) => {
const leaderAbort = new AbortController();
const waiterAbort = new AbortController();
let entered!: () => void;
let finish!: () => void;
const started = new Promise<void>((resolve) => {
entered = resolve;
});
const gate = new Promise<void>((resolve) => {
finish = resolve;
});
const pause = async () => {
entered();
await gate;
};
const connection = {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
stopReconnecting: jest.fn(),
} as unknown as MCPConnection;
const replacement = {} as MCPConnection;
const upstreamTokenProvider = jest.fn(async () => {
if (stage === 'refresh') {
await pause();
}
return { access_token: 'fresh-token' };
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
jest
.spyOn(
manager as unknown as {
waitForConnectionBorrowersToDrain: (connection: MCPConnection) => Promise<void>;
},
'waitForConnectionBorrowersToDrain',
)
.mockImplementation(async () => {
if (stage === 'drain') {
await pause();
}
});
const getConnection = jest
.spyOn(manager, 'getUserConnection')
.mockImplementation(async (options) => {
if (stage === 'initialize') {
await pause();
}
options.signal?.throwIfAborted();
return replacement;
});
const options = {
connection,
serverName,
serverConfig,
user,
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
};
const leader = manager['recoverDirectOpenIDBearerConnection']({
...options,
signal: leaderAbort.signal,
});
const leaderOutcome = leader.catch((error: Error) => error);
await started;
const waiter = manager['recoverDirectOpenIDBearerConnection']({
...options,
signal: waiterAbort.signal,
});
leaderAbort.abort(new Error('leader stopped'));
await expect(leaderOutcome).resolves.toMatchObject({ message: 'leader stopped' });
finish();
await expect(waiter).resolves.toBeUndefined();
expect(upstreamTokenProvider).toHaveBeenCalledTimes(1);
expect(getConnection).toHaveBeenCalledTimes(1);
expect(getConnection.mock.calls[0][0].signal?.aborted).toBe(false);
},
);
it.each([true, false])(
'accounts for a borrower before it can join recovery (joins=%s)',
async (joins) => {
const manager = await MCPManager.createInstance(newMCPServersConfig());
const connection = {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
stopReconnecting: jest.fn(),
} as unknown as MCPConnection;
const controller = new AbortController();
let finish!: () => void;
let entered!: () => void;
const gate = new Promise<void>((resolve) => {
finish = resolve;
});
const started = new Promise<void>((resolve) => {
entered = resolve;
});
const upstreamTokenProvider = jest.fn(async () => {
entered();
await gate;
return { access_token: 'fresh-token' };
});
const getConnection = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue({} as MCPConnection);
manager['retainConnection'](connection);
const options = {
connection,
serverName,
serverConfig,
user,
upstreamTokenProvider,
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
};
const leader = manager['recoverDirectOpenIDBearerConnection']({
...options,
signal: controller.signal,
});
const outcome = leader.catch((error: Error) => error);
await started;
controller.abort(new Error('leader stopped'));
await expect(outcome).resolves.toMatchObject({ message: 'leader stopped' });
const waiter = joins ? manager['recoverDirectOpenIDBearerConnection'](options) : undefined;
await manager['releaseConnection'](connection);
finish();
if (waiter) {
await expect(waiter).resolves.toBeUndefined();
}
await new Promise((resolve) => setImmediate(resolve));
expect(getConnection).toHaveBeenCalledTimes(joins ? 1 : 0);
expect(upstreamTokenProvider).toHaveBeenCalledTimes(1);
},
);
it('fences a delayed direct-bearer replacement when the server config mutates', async () => {
const connection = {
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
stopReconnecting: jest.fn(),
} as unknown as MCPConnection;
let finishRefresh: ((tokens: { access_token: string }) => void) | undefined;
const forcedRefresh = new Promise<{ access_token: string }>((resolve) => {
finishRefresh = resolve;
});
const upstreamTokenProvider = jest.fn().mockReturnValue(forcedRefresh);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnection = jest.spyOn(manager, 'getUserConnection');
const recovery = (
manager as unknown as {
recoverDirectOpenIDBearerConnection: (args: {
connection: MCPConnection;
serverName: string;
serverConfig: t.ParsedServerConfig;
user: IUser;
flowManager: Parameters<typeof manager.callTool>[0]['flowManager'];
upstreamTokenProvider: NonNullable<
Parameters<typeof manager.callTool>[0]['upstreamTokenProvider']
>;
}) => Promise<void>;
}
).recoverDirectOpenIDBearerConnection({
connection,
serverName,
serverConfig,
user,
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
upstreamTokenProvider,
});
while (upstreamTokenProvider.mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
await manager.disconnectUserConnection(user.id, serverName);
finishRefresh?.({ access_token: 'fresh-token' });
await expect(recovery).rejects.toThrow('cancelled during teardown');
expect(getUserConnection).not.toHaveBeenCalled();
expect(connection.stopReconnecting).toHaveBeenCalledTimes(1);
});
});
describe('MCP App operations', () => {
const user = { id: 'user-123', role: 'ADMIN' } as IUser & { id: string };
const flowManager = {} as Parameters<MCPManager['readResource']>[0]['flowManager'];
const appBindingCodec = {
create: jest.fn(() => 'binding'),
verify: jest.fn(() => true),
};
const createAppManager = (configs: t.MCPServers) =>
MCPManager.createInstance(configs, { appBindingCodec });
const defaultOAuthCredentialsChanging = jest.fn(async () => async () => undefined);
const context = (
serverName: string,
config: t.ParsedServerConfig,
extra: Partial<Parameters<MCPManager['readResource']>[0]> = {},
) => ({
serverName,
serverBinding: 'binding',
user,
connectionTarget: {
serverConfig: config,
connectionOwner: config.requiresOAuth ? ('principal' as const) : ('operator' as const),
},
allowlists: {
allowedDomains: null,
allowedAddresses: null,
useSSRFProtection: false,
},
flowManager,
onOAuthCredentialsChanging: defaultOAuthCredentialsChanging,
...extra,
});
const connection = (request: jest.Mock, tools = [{ name: 'do_thing', _meta: {} }]) =>
({
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
createdAt: 1,
toolListVersion: 1,
isConnected: jest.fn().mockResolvedValue(true),
getLastConnectionCheckError: jest.fn(),
isOAuthAuthenticationError: jest.fn((error: { status?: number }) => error?.status === 401),
usesOAuth: jest.fn().mockReturnValue(false),
setRequestHeaders: jest.fn(),
getMCPAppRuntimeTarget: jest.fn(() => ({
type: 'sse',
url: 'https://example.com/mcp',
})),
fetchOrderedToolsSnapshot: jest.fn().mockResolvedValue({ tools, complete: true }),
timeout: 30_000,
client: fakeClient(request),
}) as unknown as MCPConnection;
const newOAuthConnection = (request: jest.Mock) =>
Object.assign(connection(request), {
isStale: jest.fn().mockReturnValue(false),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
});
const standardOAuthConfig = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
requiresOAuth: true,
oauth: { client_id: 'client' },
} as t.ParsedServerConfig;
const prepareFreshOAuthAppOperation = ({
request,
publish,
renewalCurrent = true,
}: {
request: jest.Mock;
publish: jest.Mock;
renewalCurrent?: boolean;
}) => {
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
const appConnection = newOAuthConnection(request);
const onOAuthCredentialsChanging = jest.fn().mockResolvedValue(publish);
const generation = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewal = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(renewalCurrent);
(MCPConnectionFactory.create as jest.Mock).mockImplementation(
async (_basic: t.BasicConnectionOptions, options: t.OAuthConnectionOptions) => {
const publishPrepared = await options.onOAuthCredentialsChanging?.({
userId: user.id,
serverName: 'srv',
});
await publishPrepared?.();
return appConnection;
},
);
return {
appConnection,
onOAuthCredentialsChanging,
renewal,
restore: () => {
generation.mockRestore();
renewal.mockRestore();
},
};
};
it.each([
{
name: 'OBO',
config: {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
obo: { audience: 'api://mcp' },
},
message: /OBO token resolution/,
},
{
name: 'Graph',
config: {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
headers: { Authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}' },
},
message: /Graph API token resolution/,
},
{
name: 'BODY',
config: {
source: 'yaml',
type: 'sse',
url: 'https://example.com/{{LIBRECHAT_BODY_CONVERSATIONID}}/mcp',
},
message: /request body field/,
},
])(
'rejects unsupported $name configuration before connection checkout',
async ({ config, message }) => {
const manager = await createAppManager(newMCPServersConfig());
const getConnection = jest.spyOn(manager, 'getConnection');
await expect(
manager.readResource({
...context('srv', config as t.ParsedServerConfig),
uri: 'data://catalog/42',
}),
).rejects.toThrow(message);
expect(getConnection).not.toHaveBeenCalled();
},
);
it('uses the supplied authorized server config without another registry lookup', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
} as t.ParsedServerConfig;
const request = jest.fn().mockResolvedValue({ resources: [] });
const appConnection = connection(request);
const manager = await createAppManager(newMCPServersConfig());
const getConnection = jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
await expect(manager.listResources(context('srv', config))).resolves.toEqual({
resources: [],
});
expect(mockRegistryInstance.getAllServerConfigs).not.toHaveBeenCalled();
expect(getConnection).toHaveBeenCalledWith(
expect.objectContaining({
connectionTarget: { serverConfig: config, connectionOwner: 'operator' },
}),
);
});
it('validates a binding from the supplied target without checking out a connection', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
} as t.ParsedServerConfig;
const manager = await createAppManager(newMCPServersConfig());
const getConnection = jest.spyOn(manager, 'getConnection');
await expect(manager.validateAppBinding(context('srv', config))).resolves.toEqual({
valid: true,
});
expect(getConnection).not.toHaveBeenCalled();
expect(appBindingCodec.verify).toHaveBeenCalledWith(
'binding',
expect.objectContaining({
serverName: 'srv',
userId: user.id,
connectionTarget: { serverConfig: config, connectionOwner: 'operator' },
runtimeTarget: { type: 'sse', url: 'https://example.com/mcp' },
}),
);
});
it('uses the normal checkout path for an existing standard OAuth connection', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
requiresOAuth: true,
oauth: { client_id: 'client' },
} as t.ParsedServerConfig;
const request = jest.fn().mockResolvedValue({ resources: [] });
const appConnection = connection(request);
const manager = await createAppManager(newMCPServersConfig());
const getConnection = jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
const onOAuthCredentialsChanging = jest.fn(async () => async () => 'generation-b');
await manager.listResources(context('srv', config, { onOAuthCredentialsChanging }));
expect(getConnection).toHaveBeenCalledWith(
expect.objectContaining({
user,
connectionTarget: { serverConfig: config, connectionOwner: 'principal' },
flowManager,
onOAuthCredentialsChanging,
}),
);
expect(request).toHaveBeenCalledWith(
expect.objectContaining({ method: 'resources/list' }),
ListResourcesResultSchema,
expect.any(Object),
);
});
it('uses the shared OAuth recovery owner and retries an App operation once', async () => {
const unauthorized = Object.assign(new Error('Unauthorized'), { status: 401 });
const request = jest
.fn()
.mockRejectedValueOnce(unauthorized)
.mockResolvedValueOnce({ resources: [] });
const appConnection = connection(request);
const manager = await createAppManager(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
const recoverOAuth = jest
.spyOn(
manager as unknown as {
recoverOAuthConnection: (...args: unknown[]) => Promise<void>;
},
'recoverOAuthConnection',
)
.mockResolvedValue();
await expect(manager.listResources(context('srv', standardOAuthConfig))).resolves.toEqual({
resources: [],
});
expect(recoverOAuth).toHaveBeenCalledWith(
appConnection,
unauthorized,
'srv',
user.id,
expect.any(Function),
undefined,
undefined,
flowManager,
undefined,
true,
);
expect(request).toHaveBeenCalledTimes(2);
});
it('adopts the authorization generation published by a fresh App OAuth connection', async () => {
const request = jest.fn().mockResolvedValue({ resources: [] });
const publish = jest.fn().mockResolvedValue('generation-b');
const { onOAuthCredentialsChanging, renewal, restore } = prepareFreshOAuthAppOperation({
request,
publish,
});
try {
const manager = await createAppManager(newMCPServersConfig());
await expect(
manager.listResources(
context('srv', standardOAuthConfig, { onOAuthCredentialsChanging }),
),
).resolves.toEqual({ resources: [] });
expect(onOAuthCredentialsChanging).toHaveBeenCalledWith({
userId: user.id,
serverName: 'srv',
});
expect(publish).toHaveBeenCalledTimes(1);
expect(renewal).toHaveBeenCalledWith({
userId: user.id,
serverName: 'srv',
publicationGeneration: 'generation-b',
});
expect(request).toHaveBeenCalledTimes(1);
} finally {
restore();
}
});
it('does not run an App operation after a foreign rotation fences its fresh OAuth connection', async () => {
const request = jest.fn();
const { appConnection, onOAuthCredentialsChanging, restore } = prepareFreshOAuthAppOperation({
request,
publish: jest.fn().mockResolvedValue('generation-b'),
renewalCurrent: false,
});
try {
const manager = await createAppManager(newMCPServersConfig());
await expect(
manager.listResources(
context('srv', standardOAuthConfig, { onOAuthCredentialsChanging }),
),
).rejects.toThrow('Publication lease is no longer current');
expect(appConnection.dispose).toHaveBeenCalled();
expect(request).not.toHaveBeenCalled();
} finally {
restore();
}
});
it('does not run an App operation when OAuth authorization publication fails', async () => {
const request = jest.fn();
const publicationError = new Error('authorization publication unavailable');
const { onOAuthCredentialsChanging, restore } = prepareFreshOAuthAppOperation({
request,
publish: jest.fn().mockRejectedValue(publicationError),
});
try {
const manager = await createAppManager(newMCPServersConfig());
await expect(
manager.listResources(
context('srv', standardOAuthConfig, { onOAuthCredentialsChanging }),
),
).rejects.toBe(publicationError);
expect(request).not.toHaveBeenCalled();
} finally {
restore();
}
});
it('forwards an opaque auxiliary URI to the same authenticated server without local template inference', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
} as t.ParsedServerConfig;
const request = jest.fn().mockResolvedValue({
contents: [{ uri: 'data://catalog/part%2Fleaf', text: 'leaf' }],
});
const appConnection = connection(request);
const manager = await createAppManager(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
await manager.readResource({
...context('srv', config),
uri: 'data://catalog/part%2Fleaf',
});
expect(request).toHaveBeenCalledTimes(1);
expect(request).toHaveBeenCalledWith(
{
method: 'resources/read',
params: { uri: 'data://catalog/part%2Fleaf' },
},
ReadResourceResultSchema,
expect.objectContaining({ timeout: 30_000 }),
);
});
it('binds the authenticated user and role, forwards cancellation, and awaits activity renewal', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
headers: { 'X-User': '{{LIBRECHAT_USER_ID}}' },
} as t.ParsedServerConfig;
const request = jest.fn().mockResolvedValue({ resources: [] });
const appConnection = connection(request);
const manager = await createAppManager(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
const activity = jest
.spyOn(
manager as unknown as { updateUserLastActivity: (userId: string) => Promise<void> },
'updateUserLastActivity',
)
.mockResolvedValue();
(
manager as unknown as {
userConnections: Map<string, Map<string, MCPConnection>>;
}
).userConnections.set(
user.id,
new Map([[getMCPConnectionPoolKey('srv', MCP_APPS_CAPABILITY_PROFILE), appConnection]]),
);
const signal = new AbortController().signal;
await manager.listResources({ ...context('srv', config, { signal }), cursor: 'next' });
expect(manager.getConnection).toHaveBeenCalledWith(
expect.objectContaining({
user,
connectionTarget: { serverConfig: config, connectionOwner: 'operator' },
signal,
}),
);
expect(request).toHaveBeenCalledWith(
expect.objectContaining({ method: 'resources/list', params: { cursor: 'next' } }),
ListResourcesResultSchema,
expect.objectContaining({ signal }),
);
expect(activity).toHaveBeenCalledWith(user.id);
});
it('releases the connection lease when an SDK operation fails', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
} as t.ParsedServerConfig;
const failure = new Error('provider unavailable');
const appConnection = connection(jest.fn().mockRejectedValue(failure));
const manager = await createAppManager(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
const retain = jest.spyOn(
manager as unknown as { retainConnection: (value: MCPConnection) => void },
'retainConnection',
);
const release = jest.spyOn(
manager as unknown as { releaseConnection: (value: MCPConnection) => Promise<void> },
'releaseConnection',
);
await expect(
manager.readResource({ ...context('srv', config), uri: 'data://catalog/42' }),
).rejects.toBe(failure);
expect(retain).toHaveBeenCalledWith(appConnection);
expect(release).toHaveBeenCalledWith(appConnection);
});
it('uses the existing direct OpenID recovery coordinator and retries once after releasing', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
headers: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
} as t.ParsedServerConfig;
const request = jest
.fn()
.mockRejectedValueOnce(Object.assign(new Error('Unauthorized'), { status: 401 }))
.mockResolvedValueOnce({ resources: [] });
const appConnection = connection(request);
const manager = await createAppManager(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
const release = jest.spyOn(
manager as unknown as { releaseConnection: (value: MCPConnection) => Promise<void> },
'releaseConnection',
);
const recover = jest
.spyOn(
manager as unknown as {
recoverDirectOpenIDBearerConnection: (args: object) => Promise<void>;
},
'recoverDirectOpenIDBearerConnection',
)
.mockResolvedValue();
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'current-token' });
await manager.listResources({
...context('srv', config, { upstreamTokenProvider }),
});
expect(recover).toHaveBeenCalledWith(
expect.objectContaining({
connection: appConnection,
serverName: 'srv',
serverConfig: config,
user,
upstreamTokenProvider,
}),
);
expect(release.mock.invocationCallOrder[0]).toBeLessThan(request.mock.invocationCallOrder[1]);
expect(request).toHaveBeenCalledTimes(2);
});
it('reacquires after lifecycle eviction while direct OpenID refresh is in flight', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
headers: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
} as t.ParsedServerConfig;
const stale = Object.assign(
connection(
jest.fn().mockRejectedValue(Object.assign(new Error('Unauthorized'), { status: 401 })),
),
{
dispose: jest.fn().mockResolvedValue(undefined),
removeAllListeners: jest.fn(),
stopReconnecting: jest.fn(),
},
);
const replacementRequest = jest.fn().mockResolvedValue({ resources: [] });
const replacement = connection(replacementRequest);
const manager = await createAppManager(newMCPServersConfig());
jest
.spyOn(manager, 'getConnection')
.mockResolvedValueOnce(stale)
.mockResolvedValueOnce(replacement);
const createReplacement = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(replacement);
(
manager as unknown as {
userConnections: Map<string, Map<string, MCPConnection>>;
}
).userConnections.set(
user.id,
new Map([[getMCPConnectionPoolKey('srv', MCP_APPS_CAPABILITY_PROFILE), stale]]),
);
let refreshStarted!: () => void;
const started = new Promise<void>((resolve) => {
refreshStarted = resolve;
});
let finishRefresh!: (tokens: { access_token: string }) => void;
const refresh = new Promise<{ access_token: string }>((resolve) => {
finishRefresh = resolve;
});
const upstreamTokenProvider = jest
.fn()
.mockResolvedValueOnce({ access_token: 'stale-token' })
.mockImplementationOnce(() => {
refreshStarted();
return refresh;
});
const result = manager.listResources({
...context('srv', config, { upstreamTokenProvider }),
});
await started;
await manager.disconnectUserConnection(user.id, 'srv', { reason: 'lifecycle' });
expect(stale.dispose).toHaveBeenCalledTimes(1);
finishRefresh({ access_token: 'fresh-token' });
await expect(result).resolves.toEqual({ resources: [] });
expect(createReplacement).toHaveBeenCalledWith(
expect.objectContaining({ forceNew: true, serverName: 'srv', user }),
);
expect(replacementRequest).toHaveBeenCalledTimes(1);
});
it('enforces app tool visibility and returns the standard raw call result', async () => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
} as t.ParsedServerConfig;
const visibleRequest = jest.fn().mockResolvedValue({
content: [{ type: 'text', text: 'done' }],
});
const visibleConnection = connection(visibleRequest);
const manager = await createAppManager(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(visibleConnection);
const signal = new AbortController().signal;
await expect(
manager.appToolCall({
...context('srv', config, { signal }),
toolName: 'do_thing',
toolArguments: { value: 1 },
}),
).resolves.toEqual({ content: [{ type: 'text', text: 'done' }] });
expect(visibleConnection.fetchOrderedToolsSnapshot).toHaveBeenCalledWith(undefined, signal);
(MCPManager as unknown as { instance: null }).instance = null;
const hiddenRequest = jest.fn();
const hiddenManager = await createAppManager(newMCPServersConfig());
jest
.spyOn(hiddenManager, 'getConnection')
.mockResolvedValue(
connection(hiddenRequest, [
{ name: 'do_thing', _meta: { ui: { visibility: ['model'] } } },
]),
);
await expect(
hiddenManager.appToolCall({
...context('srv', config),
toolName: 'do_thing',
toolArguments: {},
}),
).rejects.toMatchObject({ code: ErrorCode.InvalidRequest });
expect(hiddenRequest).not.toHaveBeenCalled();
});
it.each([
{ name: 'incomplete', snapshot: { tools: [], complete: false } },
{ name: 'empty', snapshot: { tools: [], complete: true } },
])(
'does not authorize an App tool from stale cache after a $name catalog refresh',
async ({ snapshot }) => {
const config = {
source: 'yaml',
type: 'sse',
url: 'https://example.com/mcp',
} as t.ParsedServerConfig;
const request = jest.fn().mockResolvedValue({ content: [{ type: 'text', text: 'done' }] });
const appConnection = connection(request);
const snapshots = appConnection.fetchOrderedToolsSnapshot as jest.Mock;
const manager = await createAppManager(newMCPServersConfig());
jest.spyOn(manager, 'getConnection').mockResolvedValue(appConnection);
await expect(
manager.appToolCall({
...context('srv', config),
toolName: 'do_thing',
toolArguments: {},
}),
).resolves.toEqual({ content: [{ type: 'text', text: 'done' }] });
appConnection.toolListVersion += 1;
snapshots.mockResolvedValueOnce(snapshot);
await expect(
manager.appToolCall({
...context('srv', config),
toolName: 'do_thing',
toolArguments: {},
}),
).rejects.toMatchObject({ code: ErrorCode.InvalidRequest });
snapshots.mockResolvedValueOnce({
tools: [{ name: 'do_thing', _meta: {} }],
complete: true,
});
await expect(
manager.appToolCall({
...context('srv', config),
toolName: 'do_thing',
toolArguments: {},
}),
).resolves.toEqual({ content: [{ type: 'text', text: 'done' }] });
expect(request).toHaveBeenCalledTimes(2);
},
);
});
describe('getConnection', () => {
const mockUser: Partial<IUser> = {
id: 'user-123',
provider: 'openid',
openidId: 'oidc-sub-456',
};
describe('librechat.yaml servers hidden for the principal', () => {
const yamlConfig: t.ParsedServerConfig = {
type: 'sse',
url: 'https://api.example.com',
source: 'yaml',
};
it('refuses a config resolved before the hide, without reaching any connection', async () => {
const appConnections = { get: jest.fn() };
mockAppConnections(appConnections);
mockRegistryInstance.isHiddenFromPrincipal.mockResolvedValue(true);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest.spyOn(manager, 'getUserConnection');
await expect(
manager.getConnection({ serverName, user: mockUser as IUser, serverConfig: yamlConfig }),
).rejects.toThrow(`No connection found for server ${serverName}`);
expect(mockRegistryInstance.isHiddenFromPrincipal).toHaveBeenCalledWith(
serverName,
yamlConfig,
mockUser,
);
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnectionSpy).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('refuses a pre-resolved connection target the same way', async () => {
mockAppConnections({ get: jest.fn() });
mockRegistryInstance.isHiddenFromPrincipal.mockResolvedValue(true);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest.spyOn(manager, 'getUserConnection');
await expect(
manager.getConnection({
serverName,
user: mockUser as IUser,
connectionTarget: { serverConfig: yamlConfig, connectionOwner: 'principal' },
}),
).rejects.toThrow(`No connection found for server ${serverName}`);
expect(getUserConnectionSpy).not.toHaveBeenCalled();
});
it('fails a tool call on a hidden server without dispatching it', async () => {
mockAppConnections({ get: jest.fn() });
mockRegistryInstance.isHiddenFromPrincipal.mockResolvedValue(true);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest.spyOn(manager, 'getUserConnection');
await expect(
manager.callTool({
user: mockUser as IUser,
serverName,
serverConfig: yamlConfig,
toolName: 'tool',
provider: 'openai',
toolArguments: {},
flowManager: {} as Parameters<MCPManager['callTool']>[0]['flowManager'],
}),
).rejects.toThrow();
expect(getUserConnectionSpy).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('leaves a registry lookup to the registry, which already withholds hidden servers', async () => {
mockAppConnections({ get: jest.fn() });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(undefined);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const user = { ...mockUser, role: 'USER', idOnTheSource: null } as unknown as IUser;
await expect(manager.getConnection({ serverName, user })).rejects.toThrow(
`No connection found for server ${serverName}`,
);
expect(mockRegistryInstance.getServerConfig).toHaveBeenCalledWith(
serverName,
'user-123',
undefined,
'USER',
{ idOnTheSource: null },
);
expect(mockRegistryInstance.isHiddenFromPrincipal).not.toHaveBeenCalled();
});
it('refuses a config supplied straight to getUserConnection', async () => {
mockAppConnections({ get: jest.fn() });
mockRegistryInstance.isHiddenFromPrincipal.mockResolvedValue(true);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser as IUser,
serverConfig: yamlConfig,
flowManager: {} as Parameters<typeof manager.getUserConnection>[0]['flowManager'],
}),
).rejects.toThrow(`[MCP] Configuration for server "${serverName}" not found.`);
expect(mockRegistryInstance.isHiddenFromPrincipal).toHaveBeenCalledWith(
serverName,
yamlConfig,
mockUser,
);
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('cancels a supplied connection when a mutation lands while hiding is checked', async () => {
mockAppConnections({ get: jest.fn() });
let settleCheck: (hidden: boolean) => void = () => undefined;
mockRegistryInstance.isHiddenFromPrincipal.mockReturnValue(
new Promise<boolean>((resolve) => {
settleCheck = resolve;
}),
);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const creation = manager
.getUserConnection({
serverName,
user: mockUser as IUser,
serverConfig: yamlConfig,
forceNew: true,
flowManager: {} as Parameters<typeof manager.getUserConnection>[0]['flowManager'],
})
.catch((error: Error) => error);
await manager.disconnectUserConnection(mockUser.id as string, serverName);
settleCheck(false);
await expect(creation).resolves.toMatchObject({
message: expect.stringContaining('cancelled during teardown'),
});
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('refuses a supplied target leased for an operation, without running it', async () => {
mockAppConnections({ get: jest.fn() });
mockRegistryInstance.isHiddenFromPrincipal.mockResolvedValue(true);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const operation = jest.fn();
await expect(
manager.withUserConnectionLease(
{
serverName,
user: mockUser as IUser,
connectionTarget: { serverConfig: yamlConfig, connectionOwner: 'principal' },
flowManager: {} as Parameters<typeof manager.getUserConnection>[0]['flowManager'],
},
operation,
),
).rejects.toThrow(`[MCP] Configuration for server "${serverName}" not found.`);
expect(operation).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
});
it('should continue using shared app connections for non-OBO servers', async () => {
const appConnection = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const appConnections = {
get: jest.fn().mockResolvedValue(appConnection),
};
const nonOboConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com',
};
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(nonOboConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest.spyOn(manager, 'getUserConnection');
const connection = await manager.getConnection({
serverName,
user: mockUser as IUser,
});
expect(connection).toBe(appConnection);
expect(appConnections.get).toHaveBeenCalledWith(serverName, {
expectedConfig: nonOboConfig,
});
expect(getUserConnectionSpy).not.toHaveBeenCalled();
});
it('uses a profile-separated user session for Apps on an operator server', async () => {
const appConnections = {
get: jest.fn().mockResolvedValue({} as MCPConnection),
};
const userConnection = {} as MCPConnection;
const operatorConfig: t.SSEOptions = {
type: 'sse',
url: 'https://api.example.com',
};
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(operatorConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(userConnection);
await expect(
manager.getConnection({
serverName,
user: mockUser as IUser,
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
}),
).resolves.toBe(userConnection);
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnectionSpy).toHaveBeenCalledWith(
expect.objectContaining({
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
connectionTarget: {
serverConfig: operatorConfig,
connectionOwner: 'operator',
},
}),
);
});
it('keeps a static request-header overlay off its same-named shared app connection', async () => {
const appConnections = {
get: jest.fn(),
has: jest.fn().mockResolvedValue(true),
};
mockAppConnections(appConnections);
const candidate = {
isConnected: jest.fn().mockResolvedValue(true),
refreshToolList: jest.fn().mockResolvedValue({ tools: [], complete: true }),
on: jest.fn(),
} as unknown as MCPConnection;
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(candidate);
const declared: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/mcp',
source: 'yaml',
requestHeaders: { 'X-Workspace': 'chat-only' },
};
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getConnection({
serverName,
user: mockUser as IUser,
serverConfig: declared,
}),
).resolves.toBe(candidate);
expect(appConnections.get).not.toHaveBeenCalled();
expect(appConnections.has).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({
serverDefinition: declared,
serverConfig: expect.objectContaining({ headers: { 'X-Workspace': 'chat-only' } }),
}),
expect.any(Object),
);
});
it('should use user-scoped connections for trusted runtime context placeholders', async () => {
const appConnection = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const userConnection = {
isConnected: jest.fn().mockResolvedValue(true),
} as unknown as MCPConnection;
const appConnections = {
get: jest.fn().mockResolvedValue(appConnection),
};
const runtimeHeaderConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/mcp',
source: 'yaml',
headers: {
'X-LibreChat-User-Email': '{{LIBRECHAT_USER_EMAIL}}',
},
};
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(runtimeHeaderConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnectionSpy = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(userConnection);
const connection = await manager.getConnection({
serverName,
user: mockUser as IUser,
});
expect(connection).toBe(userConnection);
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnectionSpy).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
connectionTarget: {
serverConfig: runtimeHeaderConfig,
connectionOwner: 'operator',
},
user: mockUser,
}),
);
});
it('uses the admitted principal target when it shadows an operator server name', async () => {
const principalConfig = {
type: 'sse',
url: 'https://principal.example.com',
source: 'config',
} as t.ParsedServerConfig;
const userConnection = {} as MCPConnection;
const appConnections = { get: jest.fn() };
mockAppConnections(appConnections);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const getUserConnection = jest
.spyOn(manager, 'getUserConnection')
.mockResolvedValue(userConnection);
await expect(
manager.getConnection({
serverName,
user: mockUser as IUser,
connectionTarget: {
serverConfig: principalConfig,
connectionOwner: 'principal',
},
}),
).resolves.toBe(userConnection);
expect(appConnections.get).not.toHaveBeenCalled();
expect(getUserConnection).toHaveBeenCalledWith(
expect.objectContaining({
connectionTarget: {
serverConfig: principalConfig,
connectionOwner: 'principal',
},
}),
);
});
});
describe('discoverServerTools', () => {
const mockTools = [
{ name: 'tool1', description: 'First tool', inputSchema: { type: 'object' } },
{ name: 'tool2', description: 'Second tool', inputSchema: { type: 'object' } },
];
const mockConnection = {
isConnected: jest.fn().mockResolvedValue(true),
fetchTools: jest.fn().mockResolvedValue(mockTools),
fetchToolsSnapshot: jest.fn().mockResolvedValue({ tools: mockTools, complete: true }),
fetchOrderedToolsSnapshot: jest.fn().mockResolvedValue({ tools: mockTools, complete: true }),
disconnect: jest.fn().mockResolvedValue(undefined),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
beforeEach(() => {
(MCPConnectionFactory.discoverTools as jest.Mock) = jest.fn();
});
it.each([64, 6 * 1024 * 1024])(
'passes the user-scoped %i byte limit to App-profile discovery',
async (maxBytes) => {
const operationLimits = { maxBytes, timeoutMs: 45_000, maxActive: 8 };
mockRegistryInstance.resolveAllowlists.mockResolvedValueOnce({
allowedDomains: null,
allowedAddresses: null,
useSSRFProtection: false,
mcpApps: { enabled: true, legacyHtmlEnabled: true, operationLimits },
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: false,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.discoverServerTools({
serverName,
user: { id: 'discovery-user', role: 'ADMIN' } as IUser,
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
});
expect(mockRegistryInstance.resolveAllowlists).toHaveBeenCalledWith({
userId: 'discovery-user',
role: 'ADMIN',
});
expect(MCPConnectionFactory.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
operationLimits,
}),
expect.any(Object),
);
},
);
it('does not apply App limits to standard-profile discovery', async () => {
const operationLimits = { maxBytes: 64, timeoutMs: 45_000, maxActive: 8 };
mockAppConnections({ get: jest.fn().mockResolvedValue(null) });
mockRegistryInstance.resolveAllowlists.mockResolvedValueOnce({
allowedDomains: null,
allowedAddresses: null,
useSSRFProtection: false,
mcpApps: { enabled: true, legacyHtmlEnabled: true, operationLimits },
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: false,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.discoverServerTools({
serverName,
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
});
expect((MCPConnectionFactory.discoverTools as jest.Mock).mock.calls[0][0]).not.toHaveProperty(
'operationLimits',
);
});
it('keeps the declared OAuth identity while stripping discovery headers', async () => {
const declared: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
requiresOAuth: true,
requestHeaders: { 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
};
mockRegistryInstance.getServerConfig.mockResolvedValue(declared);
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: false,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.discoverServerTools({
serverName,
user: { id: 'oauth-user' } as IUser,
flowManager: {} as Parameters<typeof manager.discoverServerTools>[0]['flowManager'],
});
const [basic] = (MCPConnectionFactory.discoverTools as jest.Mock).mock.calls[0];
expect(basic.serverDefinition).toBe(declared);
expect(basic.serverConfig).not.toHaveProperty('requestHeaders');
});
it('should return tools from existing app connection when available', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result.tools).toEqual(mockTools);
expect(result.oauthRequired).toBe(false);
expect(result.oauthUrl).toBeNull();
expect(MCPConnectionFactory.discoverTools).not.toHaveBeenCalled();
});
it('gives a budgeted caller an abort signal for the app-connection probe and snapshot', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
const deadlineMs = Date.now() + 3000;
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName, deadlineMs });
expect(result.tools).toEqual(mockTools);
expect(mockConnection.isConnected).toHaveBeenCalledWith(expect.any(AbortSignal));
expect(mockConnection.fetchOrderedToolsSnapshot).toHaveBeenCalledWith(
deadlineMs,
expect.any(AbortSignal),
);
});
it('lets the caller signal cancel app-connection work even without a deadline', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(mockConnection),
});
const controller = new AbortController();
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.discoverServerTools({ serverName, signal: controller.signal });
expect(mockConnection.isConnected).toHaveBeenCalledWith(controller.signal);
expect(mockConnection.fetchOrderedToolsSnapshot).toHaveBeenCalledWith(
undefined,
controller.signal,
);
});
it('does not start discovery fallback for a caller whose signal already aborted', async () => {
const isConnected = jest.fn().mockResolvedValue(false);
mockAppConnections({
get: jest.fn().mockResolvedValue({ ...mockConnection, isConnected }),
});
const controller = new AbortController();
controller.abort();
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName, signal: controller.signal });
expect(result.tools).toBeNull();
expect(MCPConnectionFactory.discoverTools).not.toHaveBeenCalled();
});
it('forwards the caller signal into non-OAuth fallback discovery', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: false,
oauthUrl: null,
});
const controller = new AbortController();
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.discoverServerTools({ serverName, signal: controller.signal });
expect(MCPConnectionFactory.discoverTools).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({ signal: controller.signal }),
);
});
it('does not reuse an app connection for a tenant-scoped config override', async () => {
const configOverride = {
type: 'streamable-http' as const,
url: 'https://tenant.example.com/mcp',
source: 'config' as const,
};
const appConnections = { get: jest.fn().mockResolvedValue(mockConnection) };
mockAppConnections(appConnections);
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(configOverride);
(mockRegistryInstance.isAppServerConfig as jest.Mock).mockResolvedValue(false);
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: false,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({
serverName,
user: { id: 'tenant-user' } as IUser,
configServers: { [serverName]: configOverride },
});
expect(result.tools).toEqual(mockTools);
expect(mockRegistryInstance.getServerConfig).toHaveBeenCalledWith(
serverName,
'tenant-user',
{ [serverName]: configOverride },
undefined,
{ idOnTheSource: undefined },
);
expect(appConnections.get).not.toHaveBeenCalled();
expect(MCPConnectionFactory.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({ serverConfig: configOverride }),
expect.objectContaining({ user: expect.objectContaining({ id: 'tenant-user' }) }),
);
});
it('should use MCPConnectionFactory.discoverTools when no app connection available', async () => {
const discoveryConnection = {
disconnect: jest.fn().mockResolvedValue(undefined),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'stdio',
command: 'test',
args: [],
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: discoveryConnection,
oauthRequired: false,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result.tools).toEqual(mockTools);
expect(result.oauthRequired).toBe(false);
expect(MCPConnectionFactory.discoverTools).toHaveBeenCalled();
expect(discoveryConnection.dispose).toHaveBeenCalledTimes(1);
});
it('classifies a dynamically detected authentication challenge as OAuth', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://api.example.com/mcp',
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: null,
connection: null,
oauthRequired: true,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result.oauthRequired).toBe(true);
expect(result.authenticationKind).toBe('oauth');
});
it('keeps an authentication challenge server-managed when OAuth is explicitly disabled', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://api.example.com/mcp',
requiresOAuth: false,
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: null,
connection: null,
oauthRequired: true,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result.oauthRequired).toBe(true);
expect(result.authenticationKind).toBe('server');
});
it('should forward runtime context to discoverTools in the non-OAuth path', async () => {
const mockUser = { id: 'user123', email: '[email protected]' } as unknown as IUser;
const customUserVars = { MY_CUSTOM_KEY: 'c527bd0abc123' };
const graphTokenResolver = jest.fn();
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://my-mcp.server.com?key={{MY_CUSTOM_KEY}}',
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: false,
oauthUrl: null,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.discoverServerTools({
serverName,
user: mockUser,
customUserVars,
requestBody: { conversationId: 'conv-123' } as t.ToolDiscoveryOptions['requestBody'],
graphTokenResolver,
connectionTimeout: 10000,
});
expect(MCPConnectionFactory.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({
serverName,
serverConfig: expect.objectContaining({
url: 'https://my-mcp.server.com?key={{MY_CUSTOM_KEY}}',
}),
}),
expect.objectContaining({
user: mockUser,
customUserVars,
requestBody: { conversationId: 'conv-123' },
graphTokenResolver,
connectionTimeout: 10000,
}),
);
});
it('should not discover BODY-scoped servers without request body context', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result).toEqual({ tools: null, oauthRequired: false, oauthUrl: null });
expect(MCPConnectionFactory.discoverTools).not.toHaveBeenCalled();
expect(mockLogger.warn).toHaveBeenCalledWith(
'[MCP][Discovery] Runtime request fields are missing',
{ missingBodyFieldCount: 1 },
);
expect(JSON.stringify(mockLogger.warn.mock.calls)).not.toContain('messageId');
expect(JSON.stringify(mockLogger.warn.mock.calls)).not.toContain(serverName);
});
it('should return null tools when server config not found', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(null);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result.tools).toBeNull();
expect(result.oauthRequired).toBe(false);
expect(mockLogger.warn).toHaveBeenCalledWith(
'[MCP][Discovery] Server configuration not found',
);
});
it('should treat configured oauth as OAuth when requiresOAuth is unset', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'sse',
url: 'https://api.example.com',
oauth: {
authorization_url: 'https://auth.example.com/oauth/authorize',
token_url: 'https://auth.example.com/oauth/token',
},
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result.tools).toBeNull();
expect(result.oauthRequired).toBe(true);
expect(result.authenticationKind).toBe('oauth');
expect(MCPConnectionFactory.discoverTools).not.toHaveBeenCalled();
});
it('should return OAuth info when server requires OAuth but no user provided', async () => {
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'sse',
url: 'https://api.example.com',
requiresOAuth: true,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({ serverName });
expect(result.tools).toBeNull();
expect(result.oauthRequired).toBe(true);
expect(result.authenticationKind).toBe('oauth');
expect(mockLogger.warn).toHaveBeenCalledWith(
'[MCP][Discovery] OAuth server requires a user and flow manager',
);
});
it('should discover tools with OAuth when user and flowManager provided', async () => {
const mockUser = { id: 'user123', email: '[email protected]' } as unknown as IUser;
const mockFlowManager = {
createFlow: jest.fn(),
getFlowState: jest.fn(),
deleteFlow: jest.fn(),
};
mockAppConnections({
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'sse',
url: 'https://api.example.com',
requiresOAuth: true,
});
(MCPConnectionFactory.discoverTools as jest.Mock).mockResolvedValue({
tools: mockTools,
connection: null,
oauthRequired: true,
oauthUrl: 'https://auth.example.com/authorize',
});
const onDiscoveryDetached = jest.fn();
const onOAuthCredentialsAdopted = jest.fn();
const manager = await MCPManager.createInstance(newMCPServersConfig());
const result = await manager.discoverServerTools({
serverName,
user: mockUser,
flowManager: mockFlowManager as unknown as t.ToolDiscoveryOptions['flowManager'],
graphTokenResolver: jest.fn(),
onDiscoveryDetached,
onOAuthCredentialsAdopted,
});
expect(result.tools).toEqual(mockTools);
expect(result.oauthRequired).toBe(true);
expect(result.oauthUrl).toBe('https://auth.example.com/authorize');
expect(result.authenticationKind).toBe('oauth');
expect(MCPConnectionFactory.discoverTools).toHaveBeenCalledWith(
expect.objectContaining({ serverName }),
expect.objectContaining({
user: mockUser,
useOAuth: true,
graphTokenResolver: expect.any(Function),
onDiscoveryDetached,
onOAuthCredentialsAdopted,
}),
);
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('discovery-peer-generation');
try {
const oauthOptions = (MCPConnectionFactory.discoverTools as jest.Mock).mock.calls[0][1];
await expect(oauthOptions.onOAuthCredentialsInvalidated()).resolves.toBe(
'discovery-peer-generation',
);
expect(generationSpy).toHaveBeenCalledWith({ userId: mockUser.id, serverName });
} finally {
generationSpy.mockRestore();
}
});
});
describe('getUserConnection - useOAuth derivation', () => {
const mockUser = { id: userId, email: '[email protected]' } as unknown as IUser;
const mockFlowManager = {
createFlow: jest.fn(),
getFlowState: jest.fn(),
deleteFlow: jest.fn(),
};
const mockConnection = {
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
disconnect: jest.fn().mockResolvedValue(undefined),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
} as unknown as MCPConnection;
const newUserConnection = () =>
({
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
}) as unknown as MCPConnection;
it('keeps concurrent standard and Apps sessions distinct and disconnects both', async () => {
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
};
const created = new Map<string, MCPConnection>();
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(mockRegistryInstance.isAppServerConfig as jest.Mock).mockResolvedValue(false);
(MCPConnectionFactory.create as jest.Mock).mockImplementation(
async (basic: t.BasicConnectionOptions) => {
const capabilityProfile = basic.capabilityProfile ?? STANDARD_MCP_CAPABILITY_PROFILE;
const connection = Object.assign(newUserConnection(), {
serverName,
capabilityProfile,
});
created.set(capabilityProfile, connection);
return connection;
},
);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const [standard, apps] = await Promise.all([
manager.getConnection({
serverName,
user: mockUser,
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
}),
manager.getConnection({
serverName,
user: mockUser,
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
}),
]);
expect(standard).toBe(created.get(STANDARD_MCP_CAPABILITY_PROFILE));
expect(apps).toBe(created.get(MCP_APPS_CAPABILITY_PROFILE));
expect(standard).not.toBe(apps);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
expect(manager.getUserConnections(userId)?.get(serverName)).toBe(standard);
expect(manager.getUserConnections(userId, MCP_APPS_CAPABILITY_PROFILE)?.get(serverName)).toBe(
apps,
);
await expect(
manager.getConnection({
serverName,
user: mockUser,
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
}),
).resolves.toBe(standard);
await expect(
manager.getConnection({
serverName,
user: mockUser,
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
}),
).resolves.toBe(apps);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
await manager.disconnectUserConnection(userId, serverName);
expect(standard.dispose).toHaveBeenCalledTimes(1);
expect(apps.dispose).toHaveBeenCalledTimes(1);
expect(manager.getUserConnections(userId)).toBeUndefined();
});
/** An OAuth server whose connection build refreshes credentials, fencing the catalog mid-build. */
const refreshingOAuthServer = () => {
const connection = newUserConnection();
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://oauth-mcp.example.com/mcp',
source: 'yaml',
startup: false,
requiresOAuth: true,
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock).mockImplementation(
async (_basic: t.BasicConnectionOptions, options: t.OAuthConnectionOptions) => {
const publish = await options.onOAuthCredentialsChanging?.({ userId, serverName });
await publish?.();
return connection;
},
);
return {
connection,
serverConfig,
flowManager: mockFlowManager as unknown as t.UserMCPConnectionOptions['flowManager'],
};
};
const adoptingOAuthServer = (
adopt: (options: t.OAuthConnectionOptions) => Promise<void> | void,
) => {
const connection = newUserConnection();
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://oauth-mcp.example.com/mcp',
source: 'yaml',
startup: false,
requiresOAuth: true,
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock).mockImplementation(
async (_basic: t.BasicConnectionOptions, options: t.OAuthConnectionOptions) => {
await adopt(options);
return connection;
},
);
return {
connection,
serverConfig,
flowManager: mockFlowManager as unknown as t.UserMCPConnectionOptions['flowManager'],
};
};
it('should pass useOAuth for servers with configured oauth and no requiresOAuth value', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'sse',
url: 'https://oauth-mcp.example.com',
oauth: {
authorization_url: 'https://auth.example.com/oauth/authorize',
token_url: 'https://auth.example.com/oauth/token',
},
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
flowManager: mockFlowManager as unknown as t.UserMCPConnectionOptions['flowManager'],
});
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({ serverName }),
expect.objectContaining({ useOAuth: true }),
);
});
it('should not pass useOAuth for servers with requiresOAuth: false', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'http://private-mcp.svc:5446/mcp',
requiresOAuth: false,
oauth: {
authorization_url: 'https://auth.example.com/oauth/authorize',
token_url: 'https://auth.example.com/oauth/token',
},
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
});
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({ serverName }),
expect.not.objectContaining({ useOAuth: true }),
);
});
it('routes tool-list snapshots from user connections to the user-scoped publisher', async () => {
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/{{LIBRECHAT_BODY_CONVERSATIONID}}',
source: 'yaml',
requiresOAuth: false,
};
const tools: t.MCPTool[] = [{ name: 'dynamic', inputSchema: { type: 'object' } }];
const notifySpy = jest
.spyOn(toolsChanged, 'notifyMCPToolsChanged')
.mockResolvedValue(undefined);
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
mockProcessMCPEnv.mockImplementation(({ options }) => ({
...options,
url: 'https://mcp.example.com/conversation-1',
}));
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { conversationId: 'conversation-1' },
});
const listener = (mockConnection.on as jest.Mock).mock.calls.find(
([eventName]) => eventName === 'toolsChanged',
)?.[1];
expect(listener).toEqual(expect.any(Function));
listener(tools);
expect(notifySpy).toHaveBeenCalledWith({
tools,
userId,
serverName,
serverConfig,
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
});
} finally {
notifySpy.mockRestore();
}
});
it('refreshes a newly recreated durable user connection after subscribing', async () => {
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
expect(mockConnection.on).toHaveBeenCalledWith('toolsChanged', expect.any(Function));
expect(mockConnection.refreshToolList).toHaveBeenCalledTimes(1);
});
it.each(['headers', 'requestHeaders'] as const)(
'recovers an initial tools/list rejection with %s and preserves the replacement identity',
async (headerMap) => {
const authenticationError = Object.assign(new Error('unauthorized'), { status: 401 });
const rejectedConnection = newUserConnection();
const replacementConnection = newUserConnection();
(rejectedConnection.refreshToolList as jest.Mock).mockResolvedValue({
tools: [],
complete: false,
authenticationError,
});
(replacementConnection.refreshToolList as jest.Mock).mockResolvedValue({
tools: [],
complete: false,
authenticationError,
});
const directBearerConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
...(headerMap === 'requestHeaders' && {
apiKey: {
source: 'admin' as const,
authorization_type: 'bearer' as const,
key: 'catalog-key',
},
}),
[headerMap]: {
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
};
const upstreamTokenProvider = jest
.fn()
.mockResolvedValueOnce({ access_token: 'stale-token' })
.mockResolvedValueOnce({ access_token: 'fresh-token' })
.mockResolvedValueOnce({ access_token: 'fresh-token' });
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directBearerConfig);
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(rejectedConnection)
.mockResolvedValueOnce(replacementConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { conversationId: 'conversation-1' },
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: false,
} satisfies Partial<MCPAuthenticationRejectedError>);
expect(rejectedConnection.dispose).toHaveBeenCalledTimes(1);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
expect.objectContaining({
ephemeralConnection: true,
directBearerRecoveryState: expect.objectContaining({ attempted: true }),
}),
expect.any(Object),
);
expect(upstreamTokenProvider.mock.calls).toEqual([
[{ forceRefresh: false }],
[{ forceRefresh: true }],
]);
expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
expect.objectContaining({
serverDefinition: directBearerConfig,
directBearerSourceConfig: expect.objectContaining({
headers: {
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}',
},
}),
serverConfig: expect.objectContaining({
headers: expect.objectContaining({ Authorization: 'Bearer fresh-token' }),
}),
}),
expect.any(Object),
);
},
);
it.each([false, true])(
'does not publish a cancelled initial catalog (request-scoped=%s)',
async (requestScoped) => {
const controller = new AbortController();
const candidate = newUserConnection();
let finishCatalog: (() => void) | undefined;
(candidate.refreshToolList as jest.Mock).mockReturnValue(
new Promise<void>((resolve) => {
finishCatalog = resolve;
}),
);
const config: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
headers: {
Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}',
...(requestScoped && { 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}' }),
},
};
const store = { connections: new Map(), pending: new Map() };
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(candidate);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const creating = manager.getUserConnection({
serverName,
serverConfig: config,
user: mockUser,
signal: controller.signal,
requestBody: { conversationId: 'conversation-1' },
requestScopedConnections: requestScoped ? store : undefined,
upstreamTokenProvider: jest.fn().mockResolvedValue({ access_token: 'token' }),
});
const outcome = creating.catch((error: Error) => error);
for (
let attempt = 0;
attempt < 20 && !(candidate.refreshToolList as jest.Mock).mock.calls.length;
attempt++
) {
await new Promise((resolve) => setImmediate(resolve));
}
expect(candidate.refreshToolList).toHaveBeenCalledWith(controller.signal);
controller.abort(new Error('request stopped'));
finishCatalog?.();
await expect(outcome).resolves.toMatchObject({ message: 'request stopped' });
expect(candidate.dispose).toHaveBeenCalledTimes(1);
expect(manager.getUserConnections(mockUser.id)?.has(serverName)).not.toBe(true);
expect(store.connections.size).toBe(0);
},
);
it.each(
[
{ stage: 'initialize', cancelJoiner: false, mutate: false },
{ stage: 'catalog', cancelJoiner: false, mutate: false },
{ stage: 'initialize', cancelJoiner: true, mutate: false },
{ stage: 'catalog', cancelJoiner: true, mutate: false },
{ stage: 'initialize', cancelJoiner: false, mutate: true },
{ stage: 'catalog', cancelJoiner: false, mutate: true },
].flatMap((scenario) => ['direct', 'oauth', 'custom'].map((mode) => ({ ...scenario, mode }))),
)(
'isolates a stopped $mode creation leader during $stage (cancelJoiner=$cancelJoiner, mutate=$mutate)',
async ({ stage, cancelJoiner, mutate, mode }) => {
const leaderAbort = new AbortController();
const joinerAbort = new AbortController();
const candidate = newUserConnection();
const replacement = newUserConnection();
let entered!: () => void;
const started = new Promise<void>((resolve) => {
entered = resolve;
});
const waitForAbort = () =>
new Promise<never>((_, reject) => {
leaderAbort.signal.addEventListener('abort', () => reject(leaderAbort.signal.reason), {
once: true,
});
entered();
});
if (stage === 'catalog') {
(candidate.refreshToolList as jest.Mock).mockImplementationOnce(waitForAbort);
}
const config: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
headers: {
Authorization:
mode === 'direct' ? 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' : '{{MCP_API_KEY}}',
},
...(mode === 'oauth' && { oauth: { client_id: 'test-client' }, requiresOAuth: true }),
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (options) => options,
);
(MCPConnectionFactory.create as jest.Mock)
.mockReset()
.mockImplementationOnce((basic: t.BasicConnectionOptions) => {
basic.directBearerRecoveryState!.attempted = mode === 'direct';
return stage === 'initialize' ? waitForAbort() : Promise.resolve(candidate);
})
.mockResolvedValue(replacement);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const opts = {
serverName,
serverConfig: config,
user: mockUser,
upstreamTokenProvider: jest.fn().mockResolvedValue({ access_token: 'token' }),
customUserVars: { MCP_API_KEY: 'custom-key' },
flowManager: {} as Parameters<typeof manager.callTool>[0]['flowManager'],
};
const leader = manager.getUserConnection({ ...opts, signal: leaderAbort.signal });
const leaderOutcome = leader.catch((error: Error) => error);
await started;
const joiner = manager.getUserConnection({ ...opts, signal: joinerAbort.signal });
const joinerOutcome = joiner.catch((error: Error) => error);
await new Promise((resolve) => setImmediate(resolve));
if (cancelJoiner) {
joinerAbort.abort(new Error('joiner stopped'));
}
if (mutate) {
await manager.disconnectUserConnection(mockUser.id, serverName);
}
leaderAbort.abort(new Error('leader stopped'));
await expect(leaderOutcome).resolves.toMatchObject({ message: 'leader stopped' });
if (cancelJoiner || mutate) {
await expect(joinerOutcome).resolves.toMatchObject({
message: cancelJoiner
? 'joiner stopped'
: expect.stringContaining('cancelled during teardown'),
});
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
} else {
await expect(joinerOutcome).resolves.toBe(replacement);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
expect(MCPConnectionFactory.create).toHaveBeenLastCalledWith(
expect.objectContaining({
directBearerRecoveryState: expect.objectContaining({ attempted: mode === 'direct' }),
}),
expect.objectContaining({ signal: joinerAbort.signal }),
);
}
if (stage === 'catalog') {
expect(candidate.dispose).toHaveBeenCalledTimes(1);
}
},
);
it('honors a direct bearer recovery budget consumed during factory initialization', async () => {
const authenticationError = Object.assign(new Error('unauthorized'), { status: 401 });
const connection = newUserConnection();
(connection.refreshToolList as jest.Mock).mockResolvedValue({
tools: [],
complete: false,
authenticationError,
});
const directBearerConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
headers: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
};
const upstreamTokenProvider = jest.fn().mockResolvedValue({ access_token: 'stale-token' });
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directBearerConfig);
(MCPConnectionFactory.create as jest.Mock).mockImplementation(
async (basic: t.BasicConnectionOptions) => {
basic.directBearerRecoveryState!.attempted = true;
return connection;
},
);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
upstreamTokenProvider,
}),
).rejects.toMatchObject({
code: 'MCP_AUTHENTICATION_REJECTED',
connectionRefreshed: false,
} satisfies Partial<MCPAuthenticationRejectedError>);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).toHaveBeenCalledTimes(1);
expect(upstreamTokenProvider).not.toHaveBeenCalledWith({ forceRefresh: true });
});
it('fails closed when initial tools/list rejects without a live provider', async () => {
const authenticationError = Object.assign(new Error('unauthorized'), { status: 401 });
const connection = newUserConnection();
(connection.refreshToolList as jest.Mock).mockResolvedValue({
tools: [],
complete: false,
authenticationError,
});
const directBearerConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
headers: { Authorization: 'Bearer {{LIBRECHAT_OPENID_ACCESS_TOKEN}}' },
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(directBearerConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
}),
).rejects.toBeInstanceOf(OpenIDReauthRequiredError);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
expect(connection.dispose).toHaveBeenCalledTimes(1);
});
it.each(['serverConfig', 'connectionTarget'] as const)(
'registers a forced creation synchronously for a supplied %s',
async (targetKind) => {
const config: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
};
const connection = newUserConnection();
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const target =
targetKind === 'serverConfig'
? { serverConfig: config }
: {
connectionTarget: {
serverConfig: config,
connectionOwner: 'principal' as const,
},
};
const creation = manager.getUserConnection({
serverName,
user: mockUser,
forceNew: true,
...target,
});
const activeCreations = (
manager as unknown as {
activeConnectionCreations: Map<string, Set<unknown>>;
}
).activeConnectionCreations;
const poolKey = getMCPUserConnectionPoolKey(
userId,
serverName,
STANDARD_MCP_CAPABILITY_PROFILE,
);
expect(activeCreations.get(poolKey)?.size).toBe(1);
await expect(creation).resolves.toBe(connection);
expect(activeCreations.has(poolKey)).toBe(false);
},
);
it.each([false, true])(
'cancels and disposes a pending connection during mutation teardown (forceNew=%s)',
async (forceNew) => {
const pendingConnection = newUserConnection();
const neverReached = newUserConnection();
let resolveConnection: ((connection: MCPConnection) => void) | undefined;
const factoryResult = new Promise<MCPConnection>((resolve) => {
resolveConnection = resolve;
});
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/old',
source: 'user',
dbId: 'server-1',
});
(MCPConnectionFactory.create as jest.Mock)
.mockReturnValueOnce(factoryResult)
.mockResolvedValue(neverReached);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const creation = manager.getUserConnection({ serverName, user: mockUser, forceNew });
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
await manager.disconnectUserConnection(userId, serverName);
resolveConnection?.(pendingConnection);
await expect(creation).rejects.toThrow('Connection creation was cancelled during teardown');
expect(pendingConnection.removeAllListeners).toHaveBeenCalledWith('toolsChanged');
expect(pendingConnection.dispose).toHaveBeenCalledTimes(1);
expect(manager.getUserConnections(userId)?.has(serverName) ?? false).toBe(false);
/** A committed mutation invalidates what the caller resolved, so nothing re-establishes. */
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
},
);
it('resolves both callers when a forced replacement races a plain creation', async () => {
const original = newUserConnection();
const replacement = newUserConnection();
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(original);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(replacement);
const results = await Promise.allSettled([
manager.getUserConnection({ serverName, user: mockUser, forceNew: true }),
manager.getUserConnection({ serverName, user: mockUser }),
]);
expect(results.map((result) => result.status)).toEqual(['fulfilled', 'fulfilled']);
expect(manager.getUserConnections(userId)?.get(serverName)).toBe(replacement);
expect(original.dispose).toHaveBeenCalledTimes(1);
});
it('tears down idle users with a lifecycle teardown', async () => {
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(newUserConnection());
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const internals = manager as unknown as {
userLastActivity: Map<string, number>;
checkIdleConnections(currentUserId?: string): void;
};
internals.userLastActivity.set(userId, 0);
const disconnectSpy = jest
.spyOn(manager, 'disconnectUserConnections')
.mockResolvedValue(undefined);
internals.checkIdleConnections();
expect(disconnectSpy).toHaveBeenCalledWith(userId, { reason: 'lifecycle' });
disconnectSpy.mockRestore();
});
it('re-establishes a creation cancelled by a user-wide lifecycle teardown', async () => {
const cancelledConnection = newUserConnection();
const reestablishedConnection = newUserConnection();
let resolveConnection: ((connection: MCPConnection) => void) | undefined;
const factoryResult = new Promise<MCPConnection>((resolve) => {
resolveConnection = resolve;
});
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
});
(MCPConnectionFactory.create as jest.Mock)
.mockReturnValueOnce(factoryResult)
.mockResolvedValue(reestablishedConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const creation = manager.getUserConnection({ serverName, user: mockUser });
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
await manager.disconnectUserConnections(userId, { reason: 'lifecycle' });
resolveConnection?.(cancelledConnection);
await expect(creation).resolves.toBe(reestablishedConnection);
expect(cancelledConnection.dispose).toHaveBeenCalledTimes(1);
expect(manager.getUserConnections(userId)?.get(serverName)).toBe(reestablishedConnection);
});
it('fails a caller-resolved creation fenced by a credential mutation', async () => {
const fencedConnection = newUserConnection();
const neverReached = newUserConnection();
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
};
let resolveConnection: ((connection: MCPConnection) => void) | undefined;
const factoryResult = new Promise<MCPConnection>((resolve) => {
resolveConnection = resolve;
});
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock)
.mockReturnValueOnce(factoryResult)
.mockResolvedValue(neverReached);
const manager = await MCPManager.createInstance(newMCPServersConfig());
/** Callers resolve the config and credentials per request and hand them in; a mutation
* teardown invalidates both, and only the caller can resolve them again. */
const creation = manager.getUserConnection({
serverName,
user: mockUser,
serverConfig,
customUserVars: { API_KEY: 'revoked-key' },
});
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
await manager.disconnectUserConnection(userId, serverName);
resolveConnection?.(fencedConnection);
await expect(creation).rejects.toThrow('Connection creation was cancelled during teardown');
expect(fencedConnection.dispose).toHaveBeenCalledTimes(1);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
expect(manager.getUserConnections(userId)?.has(serverName) ?? false).toBe(false);
});
it('keeps the activity timestamp for a connection installed during a user-wide teardown', async () => {
const otherServer = 'other_server';
const installedConnection = newUserConnection();
let resolveDispose: (() => void) | undefined;
(installedConnection.dispose as jest.Mock).mockReturnValue(
new Promise<void>((resolve) => {
resolveDispose = () => resolve();
}),
);
const fencedConnection = newUserConnection();
const reestablishedConnection = newUserConnection();
let resolveConnection: ((connection: MCPConnection) => void) | undefined;
const factoryResult = new Promise<MCPConnection>((resolve) => {
resolveConnection = resolve;
});
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
});
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(installedConnection)
.mockReturnValueOnce(factoryResult)
.mockResolvedValue(reestablishedConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const creation = manager.getUserConnection({ serverName: otherServer, user: mockUser });
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length < 2) {
await new Promise((resolve) => setImmediate(resolve));
}
/** The sweep is still disposing the first connection when the fenced one re-establishes. */
const teardown = manager.disconnectUserConnections(userId, { reason: 'lifecycle' });
resolveConnection?.(fencedConnection);
await expect(creation).resolves.toBe(reestablishedConnection);
resolveDispose?.();
await teardown;
const internals = manager as unknown as { userLastActivity: Map<string, number> };
expect(manager.getUserConnections(userId)?.get(otherServer)).toBe(reestablishedConnection);
expect(internals.userLastActivity.has(userId)).toBe(true);
});
it('does not re-establish a lifecycle-fenced creation whose caller aborted', async () => {
const fencedConnection = newUserConnection();
const neverReached = newUserConnection();
let resolveConnection: ((connection: MCPConnection) => void) | undefined;
const factoryResult = new Promise<MCPConnection>((resolve) => {
resolveConnection = resolve;
});
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
});
(MCPConnectionFactory.create as jest.Mock)
.mockReturnValueOnce(factoryResult)
.mockResolvedValue(neverReached);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const controller = new AbortController();
const creation = manager.getUserConnection({
serverName,
user: mockUser,
signal: controller.signal,
});
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
controller.abort();
await manager.disconnectUserConnection(userId, serverName, { reason: 'lifecycle' });
resolveConnection?.(fencedConnection);
await expect(creation).rejects.toThrow('Connection creation was cancelled during teardown');
expect(fencedConnection.dispose).toHaveBeenCalledTimes(1);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
expect(manager.getUserConnections(userId)?.has(serverName) ?? false).toBe(false);
});
it('cancels pending tool publications before it starts disposing', async () => {
const connection = newUserConnection();
const cancelSpy = jest.spyOn(toolsChanged, 'cancelMCPToolsChanged');
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
cancelSpy.mockClear();
await manager.disconnectUserConnection(userId, serverName);
/** A creation re-established while disposal is still awaited publishes its own catalog;
* a cancellation issued after that point would drop the replacement's pending change. */
expect(cancelSpy).toHaveBeenNthCalledWith(1, {
userId,
serverName,
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
});
expect(cancelSpy).toHaveBeenNthCalledWith(2, {
userId,
serverName,
capabilityProfile: MCP_APPS_CAPABILITY_PROFILE,
});
expect(cancelSpy).toHaveBeenCalledTimes(2);
expect(cancelSpy.mock.invocationCallOrder[0]).toBeLessThan(
(connection.dispose as jest.Mock).mock.invocationCallOrder[0],
);
} finally {
cancelSpy.mockRestore();
}
});
it('clears catalog recovery suppression for mutations but preserves it for lifecycle cleanup', async () => {
const manager = await MCPManager.createInstance(newMCPServersConfig());
const clearRecoveryState = jest.spyOn(manager.getCatalogRecoveryTracker(), 'clear');
await manager.disconnectUserConnection(userId, serverName, { reason: 'lifecycle' });
expect(clearRecoveryState).not.toHaveBeenCalled();
await manager.disconnectUserConnection(userId, serverName);
expect(clearRecoveryState).toHaveBeenNthCalledWith(
1,
userId,
serverName,
undefined,
undefined,
);
expect(clearRecoveryState).toHaveBeenNthCalledWith(
2,
userId,
serverName,
undefined,
STANDARD_MCP_CAPABILITY_PROFILE,
);
expect(clearRecoveryState).toHaveBeenNthCalledWith(
3,
userId,
serverName,
undefined,
MCP_APPS_CAPABILITY_PROFILE,
);
expect(clearRecoveryState).toHaveBeenCalledTimes(3);
});
it('fails a creation that a lifecycle teardown keeps cancelling on every attempt', async () => {
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
(MCPConnectionFactory.create as jest.Mock).mockReset();
(MCPConnectionFactory.create as jest.Mock).mockImplementation(async () => {
const connection = newUserConnection();
await manager.disconnectUserConnection(userId, serverName, { reason: 'lifecycle' });
return connection;
});
await expect(manager.getUserConnection({ serverName, user: mockUser })).rejects.toThrow(
'Connection creation was cancelled during teardown',
);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(4);
expect(manager.getUserConnections(userId)?.has(serverName) ?? false).toBe(false);
});
it('disposes the tracked durable connection before a forced replacement', async () => {
const previousConnection = newUserConnection();
const replacementConnection = newUserConnection();
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
});
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(previousConnection)
.mockResolvedValueOnce(replacementConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const result = await manager.getUserConnection({
serverName,
user: mockUser,
forceNew: true,
});
expect(previousConnection.removeAllListeners).toHaveBeenCalledWith('toolsChanged');
expect(previousConnection.dispose).toHaveBeenCalledTimes(1);
expect((previousConnection.dispose as jest.Mock).mock.invocationCallOrder[0]).toBeLessThan(
(MCPConnectionFactory.create as jest.Mock).mock.invocationCallOrder[1],
);
expect(result).toBe(replacementConnection);
expect(manager.getUserConnections(userId)?.get(serverName)).toBe(replacementConnection);
});
it('serializes an ordinary load with multiple queued forced replacements', async () => {
const initial = newUserConnection();
const firstReplacement = newUserConnection();
const secondReplacement = newUserConnection();
let resolveFirst: ((connection: MCPConnection) => void) | undefined;
let resolveSecond: ((connection: MCPConnection) => void) | undefined;
const firstFactoryResult = new Promise<MCPConnection>((resolve) => {
resolveFirst = resolve;
});
const secondFactoryResult = new Promise<MCPConnection>((resolve) => {
resolveSecond = resolve;
});
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
});
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(initial)
.mockReturnValueOnce(firstFactoryResult)
.mockReturnValueOnce(secondFactoryResult);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const firstForced = manager.getUserConnection({ serverName, user: mockUser, forceNew: true });
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length < 2) {
await new Promise((resolve) => setImmediate(resolve));
}
const ordinary = manager.getUserConnection({ serverName, user: mockUser });
const secondForced = manager.getUserConnection({
serverName,
user: mockUser,
forceNew: true,
});
resolveFirst?.(firstReplacement);
await expect(firstForced).resolves.toBe(firstReplacement);
await expect(ordinary).resolves.toBe(firstReplacement);
while ((MCPConnectionFactory.create as jest.Mock).mock.calls.length < 3) {
await new Promise((resolve) => setImmediate(resolve));
}
resolveSecond?.(secondReplacement);
await expect(secondForced).resolves.toBe(secondReplacement);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(3);
expect(firstReplacement.dispose).toHaveBeenCalledTimes(1);
expect(manager.getUserConnections(userId)?.get(serverName)).toBe(secondReplacement);
});
it('disposes a retained disconnected connection before recreating it', async () => {
const createConnection = (connected: boolean) =>
({
isConnected: jest.fn().mockResolvedValue(connected),
isStale: jest.fn().mockReturnValue(false),
disconnect: jest.fn().mockResolvedValue(undefined),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
}) as unknown as MCPConnection;
const disconnectedConnection = createConnection(false);
const replacementConnection = createConnection(true);
(disconnectedConnection.isConnected as jest.Mock)
.mockResolvedValueOnce(true)
.mockResolvedValue(false);
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
});
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(disconnectedConnection)
.mockResolvedValueOnce(replacementConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const result = await manager.getUserConnection({ serverName, user: mockUser });
expect(disconnectedConnection.removeAllListeners).toHaveBeenCalledWith('toolsChanged');
expect(disconnectedConnection.dispose).toHaveBeenCalledTimes(1);
expect(
(disconnectedConnection.dispose as jest.Mock).mock.invocationCallOrder[0],
).toBeLessThan((MCPConnectionFactory.create as jest.Mock).mock.invocationCallOrder[1]);
expect(result).toBe(replacementConnection);
expect(manager.getUserConnections(userId)?.get(serverName)).toBe(replacementConnection);
});
it('binds durable tool publications to the generation captured before connection creation', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const notifySpy = jest
.spyOn(toolsChanged, 'notifyMCPToolsChanged')
.mockResolvedValue(undefined);
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
get: jest.fn().mockResolvedValue(null),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
const expectedToolFunctions: t.LCAvailableTools = {
[`current_mcp_${serverName}`]: {
type: 'function',
function: {
name: `current_mcp_${serverName}`,
description: '',
parameters: { type: 'object' },
},
},
};
(MCPServerInspector.getToolCatalog as jest.Mock).mockResolvedValue({
tools: expectedToolFunctions,
});
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const listener = (mockConnection.on as jest.Mock).mock.calls.find(
([eventName]) => eventName === 'toolsChanged',
)?.[1];
const tools: t.MCPTool[] = [{ name: 'current', inputSchema: { type: 'object' } }];
listener(tools);
const deadlineMs = Date.now() + 3000;
const snapshot = await manager.getServerToolFunctionsSnapshot(
userId,
serverName,
undefined,
{
deadlineMs,
},
);
expect(generationSpy).toHaveBeenCalledWith({ userId, serverName });
expect(snapshot).toEqual({
tools: expectedToolFunctions,
publicationGeneration: 'generation-a',
});
expect(MCPServerInspector.getToolCatalog).toHaveBeenCalledWith(
serverName,
mockConnection,
deadlineMs,
expect.any(AbortSignal),
);
expect(notifySpy).toHaveBeenCalledWith({
tools,
userId,
serverName,
serverConfig,
publicationGeneration: 'generation-a',
capabilityProfile: STANDARD_MCP_CAPABILITY_PROFILE,
});
} finally {
generationSpy.mockRestore();
notifySpy.mockRestore();
}
});
it('rejects a live snapshot after another replica rotates its publication generation', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValueOnce('generation-a')
.mockResolvedValue('generation-b');
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'user',
dbId: 'server-1',
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
await expect(
manager.getServerToolFunctionsSnapshot(userId, serverName, serverConfig),
).resolves.toEqual({ tools: null });
expect(MCPServerInspector.getToolCatalog).not.toHaveBeenCalled();
expect(connection.dispose).toHaveBeenCalledTimes(1);
} finally {
generationSpy.mockRestore();
}
});
it('rejects an old-config connection even when Redis generation rotation failed', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const oldConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://old.example.com/mcp',
source: 'user',
dbId: 'server-1',
};
const committedConfig: t.ParsedServerConfig = {
...oldConfig,
url: 'https://new.example.com/mcp',
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(oldConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser, serverConfig: oldConfig });
await expect(
manager.getServerToolFunctionsSnapshot(userId, serverName, committedConfig),
).resolves.toEqual({ tools: null });
expect(MCPServerInspector.getToolCatalog).not.toHaveBeenCalled();
expect(connection.dispose).toHaveBeenCalledTimes(1);
} finally {
generationSpy.mockRestore();
}
});
it('rejects a connection for a deleted config even when Redis generation rotation failed', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const oldConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://old.example.com/mcp',
source: 'user',
dbId: 'server-1',
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(oldConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser, serverConfig: oldConfig });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(null);
await expect(manager.getServerToolFunctionsSnapshot(userId, serverName)).resolves.toEqual({
tools: null,
});
expect(MCPServerInspector.getToolCatalog).not.toHaveBeenCalled();
expect(connection.dispose).toHaveBeenCalledTimes(1);
} finally {
generationSpy.mockRestore();
}
});
it('renews the publication lease when an active durable connection is reused', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(true);
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const internals = manager as unknown as {
toolPublicationLeaseRefreshes: WeakMap<MCPConnection, number>;
};
renewalSpy.mockClear();
internals.toolPublicationLeaseRefreshes.set(mockConnection, 0);
await manager.getUserConnection({ serverName, user: mockUser });
expect(renewalSpy).toHaveBeenCalledWith({
userId,
serverName,
publicationGeneration: 'generation-a',
});
expect(renewalSpy).toHaveBeenCalledTimes(1);
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('disposes and rejects a reused connection after lease renewal loses ownership', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(true);
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const internals = manager as unknown as {
toolPublicationLeaseRefreshes: WeakMap<MCPConnection, number>;
};
internals.toolPublicationLeaseRefreshes.set(connection, 0);
renewalSpy.mockResolvedValue(false);
await expect(manager.getUserConnection({ serverName, user: mockUser })).rejects.toThrow(
'Publication lease is no longer current',
);
expect(connection.removeAllListeners).toHaveBeenCalledWith('toolsChanged');
expect(connection.dispose).toHaveBeenCalled();
expect(manager.getUserConnections(userId)?.has(serverName) ?? false).toBe(false);
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('leases a new connection under the generation its own credential refresh published', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(true);
const { serverConfig, flowManager } = refreshingOAuthServer();
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
flowManager,
serverConfig,
onOAuthCredentialsChanging: async () => async () => 'generation-b',
});
expect(renewalSpy).toHaveBeenCalledWith({
userId,
serverName,
publicationGeneration: 'generation-b',
});
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('still fences a new connection when a rotation follows its own credential refresh', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(false);
const { serverConfig, flowManager, connection } = refreshingOAuthServer();
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
flowManager,
serverConfig,
onOAuthCredentialsChanging: async () => async () => 'generation-b',
}),
).rejects.toThrow('Publication lease is no longer current');
expect(renewalSpy).toHaveBeenCalledWith({
userId,
serverName,
publicationGeneration: 'generation-b',
});
expect(connection.dispose).toHaveBeenCalled();
expect(manager.getUserConnections(userId)?.has(serverName) ?? false).toBe(false);
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('leases a new connection under the carried generation while it is the one currently stored', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(true);
const { serverConfig, flowManager } = adoptingOAuthServer(async (options) => {
generationSpy.mockResolvedValue('generation-b');
await options.onOAuthCredentialsAdopted?.('generation-b');
});
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser, flowManager, serverConfig });
expect(renewalSpy).toHaveBeenCalledWith({
userId,
serverName,
publicationGeneration: 'generation-b',
});
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('keeps its captured generation when the carried one is no longer stored', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(true);
const { serverConfig, flowManager } = adoptingOAuthServer((options) =>
options.onOAuthCredentialsAdopted?.('generation-b'),
);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser, flowManager, serverConfig });
expect(renewalSpy).toHaveBeenCalledWith({
userId,
serverName,
publicationGeneration: 'generation-a',
});
expect(renewalSpy).not.toHaveBeenCalledWith(
expect.objectContaining({ publicationGeneration: 'generation-b' }),
);
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('lets an ephemeral flow owner carry the peer generation to persistent waiters', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('peer-generation');
let captured: string | void;
const { serverConfig, flowManager } = adoptingOAuthServer(async (options) => {
captured = await options.onOAuthCredentialsInvalidated?.();
});
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
flowManager,
serverConfig,
ephemeralConnection: true,
});
expect(captured!).toBe('peer-generation');
} finally {
generationSpy.mockRestore();
}
});
it('re-captures the generation before re-reading credentials a change invalidated', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(true);
const { serverConfig, flowManager } = adoptingOAuthServer(async (options) => {
generationSpy.mockResolvedValue('generation-c');
await options.onOAuthCredentialsInvalidated?.();
});
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser, flowManager, serverConfig });
expect(renewalSpy).toHaveBeenCalledWith({
userId,
serverName,
publicationGeneration: 'generation-c',
});
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('does not return a reused connection cancelled while its lease renewal is pending', async () => {
const generationSpy = jest
.spyOn(toolsChanged, 'getMCPToolsChangedGeneration')
.mockResolvedValue('generation-a');
const renewalSpy = jest
.spyOn(toolsChanged, 'renewMCPToolsChangedGeneration')
.mockResolvedValue(true);
let resolveRenewal: ((renewed: boolean) => void) | undefined;
const pendingRenewal = new Promise<boolean>((resolve) => {
resolveRenewal = resolve;
});
const connection = {
isConnected: jest.fn().mockResolvedValue(true),
isStale: jest.fn().mockReturnValue(false),
refreshToolList: jest.fn().mockResolvedValue(undefined),
on: jest.fn(),
removeAllListeners: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const serverConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://mcp.example.com/mcp',
source: 'yaml',
startup: false,
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(serverConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(connection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({ serverName, user: mockUser });
const internals = manager as unknown as {
toolPublicationLeaseRefreshes: WeakMap<MCPConnection, number>;
};
internals.toolPublicationLeaseRefreshes.set(connection, 0);
renewalSpy.mockClear();
renewalSpy.mockReturnValue(pendingRenewal);
const reuse = manager.getUserConnection({ serverName, user: mockUser });
while (renewalSpy.mock.calls.length === 0) {
await new Promise((resolve) => setImmediate(resolve));
}
await manager.disconnectUserConnection(userId, serverName);
resolveRenewal?.(true);
await expect(reuse).rejects.toThrow('Connection creation was cancelled during teardown');
expect(connection.dispose).toHaveBeenCalled();
} finally {
generationSpy.mockRestore();
renewalSpy.mockRestore();
}
});
it('should detect OAuth after resolving trusted runtime URL placeholders', async () => {
const runtimeUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/users/{{LIBRECHAT_USER_ID}}/mcp',
source: 'yaml',
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(runtimeUrlConfig);
mockProcessMCPEnv.mockImplementation(({ options, user }) => ({
...options,
...('url' in options && {
url: options.url?.replace('{{LIBRECHAT_USER_ID}}', user?.id ?? ''),
}),
}));
mockDetectOAuthRequirement.mockResolvedValue({
requiresOAuth: true,
method: 'protected-resource-metadata',
});
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
expect(getMCPToolApprovalAuthKind(runtimeUrlConfig)).toBeUndefined();
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
flowManager: mockFlowManager as unknown as t.UserMCPConnectionOptions['flowManager'],
});
expect(mockDetectOAuthRequirement).toHaveBeenCalledWith(
'https://api.example.com/users/test-user-123/mcp',
null,
null,
);
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({
serverConfig: expect.objectContaining({
requiresOAuth: true,
}),
}),
expect.objectContaining({ useOAuth: true }),
);
const runtime = (MCPConnectionFactory.create as jest.Mock).mock.calls[0][0];
expect(runtime.serverDefinition).toBe(runtimeUrlConfig);
expect(getMCPToolApprovalAuthKind(runtime.serverDefinition)).toBeUndefined();
expect(getMCPToolApprovalAuthKind(runtime.serverConfig)).toBe('oauth');
});
it('should reject disallowed runtime URLs before OAuth detection probes them', async () => {
const runtimeUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://{{LIBRECHAT_BODY_CONVERSATIONID}}.example.com/mcp',
source: 'yaml',
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(runtimeUrlConfig);
(mockRegistryInstance.getAllowedDomains as jest.Mock).mockReturnValue(['*.example.com']);
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace(
'{{LIBRECHAT_BODY_CONVERSATIONID}}',
body?.conversationId ?? '',
),
}),
}));
mockIsMCPDomainAllowed.mockResolvedValue(false);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { conversationId: 'evil.com/path' },
flowManager: mockFlowManager as unknown as t.UserMCPConnectionOptions['flowManager'],
}),
).rejects.toThrow('not allowed by the configured domain policy');
expect(mockDetectOAuthRequirement).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('should reject resolved runtime URLs that fail MCP domain policy', async () => {
const runtimeUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://{{LIBRECHAT_BODY_CONVERSATIONID}}.example.com/mcp',
source: 'yaml',
requiresOAuth: false,
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(runtimeUrlConfig);
(mockRegistryInstance.getAllowedDomains as jest.Mock).mockReturnValue(['*.example.com']);
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace(
'{{LIBRECHAT_BODY_CONVERSATIONID}}',
body?.conversationId ?? '',
),
}),
}));
mockIsMCPDomainAllowed.mockResolvedValue(false);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { conversationId: 'evil.com/path' },
}),
).rejects.toThrow('not allowed by the configured domain policy');
expect(mockIsMCPDomainAllowed).toHaveBeenCalledWith(
expect.objectContaining({
url: 'https://evil.com/path.example.com/mcp',
}),
['*.example.com'],
null,
);
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('should validate resolved runtime URLs without passing resolved configs to the factory', async () => {
const runtimeUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://{{LIBRECHAT_BODY_CONVERSATIONID}}.example.com/mcp',
source: 'yaml',
requiresOAuth: false,
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(runtimeUrlConfig);
(mockRegistryInstance.getAllowedDomains as jest.Mock).mockReturnValue(['*.example.com']);
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace(
'{{LIBRECHAT_BODY_CONVERSATIONID}}',
body?.conversationId ?? '',
),
}),
}));
mockIsMCPDomainAllowed.mockResolvedValue(true);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { conversationId: 'tenant-a' },
});
expect(mockIsMCPDomainAllowed).toHaveBeenCalledWith(
expect.objectContaining({
url: 'https://tenant-a.example.com/mcp',
}),
['*.example.com'],
null,
);
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({
serverConfig: expect.objectContaining({
url: 'https://{{LIBRECHAT_BODY_CONVERSATIONID}}.example.com/mcp',
}),
}),
expect.objectContaining({
requestBody: { conversationId: 'tenant-a' },
}),
);
});
it('should keep graph placeholders unresolved for user-sourced connection configs', async () => {
const graphConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/mcp',
source: 'user',
dbId: 'user-server-id',
requiresOAuth: false,
headers: {
Authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
},
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(graphConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
graphTokenResolver: jest.fn(),
});
expect(graphUtils.preProcessGraphTokens).not.toHaveBeenCalled();
expect(MCPConnectionFactory.create).toHaveBeenCalledWith(
expect.objectContaining({
serverConfig: expect.objectContaining({
headers: {
Authorization: 'Bearer {{LIBRECHAT_GRAPH_ACCESS_TOKEN}}',
},
}),
}),
expect.any(Object),
);
});
it('should not cache connections when request body placeholders affect the URL', async () => {
const bodyUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
requiresOAuth: false,
};
const firstConnection = {
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
} as unknown as MCPConnection;
const secondConnection = {
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
} as unknown as MCPConnection;
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(bodyUrlConfig);
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace('{{LIBRECHAT_BODY_MESSAGEID}}', body?.messageId ?? ''),
}),
}));
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(firstConnection)
.mockResolvedValueOnce(secondConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const first = await manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { messageId: 'message-1' },
});
const second = await manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { messageId: 'message-2' },
});
expect(first).toBe(firstConnection);
expect(second).toBe(secondConnection);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(2);
});
it('isolates an unattended probe from a live user connection', async () => {
const config: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/mcp',
source: 'user',
requiresOAuth: false,
};
const live = {
isConnected: jest.fn().mockResolvedValue(true),
refreshToolList: jest.fn().mockResolvedValue({ tools: [], complete: true }),
on: jest.fn(),
disconnect: jest.fn(),
dispose: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
const probe = {
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
} as unknown as MCPConnection;
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(config);
(MCPConnectionFactory.create as jest.Mock)
.mockResolvedValueOnce(live)
.mockResolvedValueOnce(probe);
const manager = await MCPManager.createInstance(newMCPServersConfig());
expect(await manager.getUserConnection({ serverName, user: mockUser })).toBe(live);
const requestScopedConnections: t.RequestScopedMCPConnectionStore = {
connections: new Map(),
pending: new Map(),
};
expect(
await manager.getUserConnection({
serverName,
user: mockUser,
ephemeralConnection: true,
requestScopedConnections,
}),
).toBe(probe);
expect(await manager.getUserConnection({ serverName, user: mockUser })).toBe(live);
expect(live.disconnect).not.toHaveBeenCalled();
expect(
requestScopedConnections.connections.get(
getMCPUserConnectionPoolKey(mockUser.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
),
).toBe(probe);
});
it('should reuse BODY-scoped connections within a request-scoped connection store', async () => {
const bodyUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
requiresOAuth: false,
};
const requestScopedConnection = {
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
} as unknown as MCPConnection;
const requestScopedConnections: t.RequestScopedMCPConnectionStore = {
connections: new Map(),
pending: new Map(),
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(bodyUrlConfig);
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace('{{LIBRECHAT_BODY_MESSAGEID}}', body?.messageId ?? ''),
}),
}));
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(requestScopedConnection);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const first = await manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { messageId: 'message-1' },
requestScopedConnections,
});
const second = await manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { messageId: 'message-1' },
requestScopedConnections,
});
expect(first).toBe(requestScopedConnection);
expect(second).toBe(requestScopedConnection);
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
expect(
requestScopedConnections.connections.get(
getMCPUserConnectionPoolKey(mockUser.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
),
).toBe(requestScopedConnection);
});
it('rechecks the request-scoped owner after a late connection replacement', async () => {
let finishProbe: ((connected: boolean) => void) | undefined;
const oldConnection = {
isConnected: jest.fn().mockReturnValue(
new Promise<boolean>((resolve) => {
finishProbe = resolve;
}),
),
isStale: jest.fn().mockReturnValue(false),
} as unknown as MCPConnection;
const replacement = newUserConnection();
const store = {
connections: new Map([
[
getMCPUserConnectionPoolKey(mockUser.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
oldConnection,
],
]),
pending: new Map(),
};
const manager = await MCPManager.createInstance(newMCPServersConfig());
const checkout = manager.getUserConnection({
serverName,
user: mockUser,
serverConfig: {
type: 'streamable-http',
url: 'https://mcp.example.com',
source: 'yaml',
headers: { 'X-Conversation': '{{LIBRECHAT_BODY_CONVERSATIONID}}' },
},
requestBody: { conversationId: 'conversation-1' },
requestScopedConnections: store,
});
await new Promise((resolve) => setImmediate(resolve));
expect(oldConnection.isConnected).toHaveBeenCalledTimes(1);
store.connections.set(
getMCPUserConnectionPoolKey(mockUser.id, serverName, STANDARD_MCP_CAPABILITY_PROFILE),
replacement,
);
finishProbe?.(true);
await expect(checkout).resolves.toBe(replacement);
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('does not create a connection in a request-scoped store after cleanup starts', async () => {
const bodyUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
requiresOAuth: false,
};
const requestScopedConnections: t.RequestScopedMCPConnectionStore = {
connections: new Map(),
pending: new Map(),
cleanupStarted: true,
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
serverConfig: bodyUrlConfig,
requestBody: { messageId: 'message-1' },
requestScopedConnections,
}),
).rejects.toThrow('Request-scoped connection context is closed');
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
expect(requestScopedConnections.connections.size).toBe(0);
expect(requestScopedConnections.pending.size).toBe(0);
});
it.each(['cleanup', 'mutation'] as const)(
'disposes a request-scoped connection that finishes after %s',
async (teardown) => {
const bodyUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
requiresOAuth: false,
};
const lateConnection = {
dispose: jest.fn().mockResolvedValue(undefined),
isConnected: jest.fn().mockResolvedValue(true),
on: jest.fn(),
refreshToolList: jest.fn().mockResolvedValue(undefined),
} as unknown as MCPConnection;
let finishCreation: ((connection: MCPConnection) => void) | undefined;
const creation = new Promise<MCPConnection>((resolve) => {
finishCreation = resolve;
});
const requestScopedConnections: t.RequestScopedMCPConnectionStore = {
connections: new Map(),
pending: new Map(),
cleanupStarted: false,
};
mockAppConnections({ has: jest.fn().mockResolvedValue(false) });
(graphUtils.preProcessGraphTokens as jest.Mock).mockImplementation(
async (config) => config,
);
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace('{{LIBRECHAT_BODY_MESSAGEID}}', body?.messageId ?? ''),
}),
}));
(MCPConnectionFactory.create as jest.Mock).mockReturnValue(creation);
const manager = await MCPManager.createInstance(newMCPServersConfig());
const connectionPromise = manager.getUserConnection({
serverName,
user: mockUser,
serverConfig: bodyUrlConfig,
requestBody: { messageId: 'message-1' },
requestScopedConnections,
});
for (
let attempt = 0;
attempt < 20 && !(MCPConnectionFactory.create as jest.Mock).mock.calls.length;
attempt++
) {
await new Promise((resolve) => setImmediate(resolve));
}
expect(MCPConnectionFactory.create).toHaveBeenCalledTimes(1);
if (teardown === 'cleanup') {
requestScopedConnections.cleanupStarted = true;
} else {
await manager.disconnectUserConnection(mockUser.id, serverName);
}
finishCreation?.(lateConnection);
await expect(connectionPromise).rejects.toThrow(
teardown === 'cleanup'
? 'Request-scoped connection context is closed'
: 'cancelled during teardown',
);
expect(lateConnection.dispose).toHaveBeenCalledTimes(1);
expect(requestScopedConnections.connections.size).toBe(0);
expect(requestScopedConnections.pending.size).toBe(0);
},
);
it('should not clear server cooldowns for ephemeral runtime connections', async () => {
const bodyUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
requiresOAuth: false,
};
const clearCooldownSpy = jest.spyOn(MCPConnection, 'clearCooldown');
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(bodyUrlConfig);
mockProcessMCPEnv.mockImplementation(({ options, body }) => ({
...options,
...('url' in options && {
url: options.url?.replace('{{LIBRECHAT_BODY_MESSAGEID}}', body?.messageId ?? ''),
}),
}));
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { messageId: 'message-1' },
});
expect(clearCooldownSpy).not.toHaveBeenCalled();
} finally {
clearCooldownSpy.mockRestore();
}
});
it('should still clear server cooldowns for explicit forceNew connections', async () => {
const staticConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/mcp',
source: 'yaml',
requiresOAuth: false,
};
const clearCooldownSpy = jest.spyOn(MCPConnection, 'clearCooldown');
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(staticConfig);
(MCPConnectionFactory.create as jest.Mock).mockResolvedValue(mockConnection);
try {
const manager = await MCPManager.createInstance(newMCPServersConfig());
await manager.getUserConnection({
serverName,
user: mockUser,
forceNew: true,
});
expect(clearCooldownSpy).toHaveBeenCalledWith(serverName);
} finally {
clearCooldownSpy.mockRestore();
}
});
it('should reject BODY-scoped connections without request body context', async () => {
const bodyUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
requiresOAuth: false,
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(bodyUrlConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
}),
).rejects.toThrow('Request body field(s) required');
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('should reject BODY-scoped connections when a referenced body field is missing', async () => {
const bodyUrlConfig: t.ParsedServerConfig = {
type: 'streamable-http',
url: 'https://api.example.com/messages/{{LIBRECHAT_BODY_MESSAGEID}}/mcp',
source: 'yaml',
requiresOAuth: false,
};
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue(bodyUrlConfig);
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
requestBody: { conversationId: 'conv-123' },
}),
).rejects.toThrow('messageId');
expect(MCPConnectionFactory.create).not.toHaveBeenCalled();
});
it('should throw when OAuth server lacks flowManager', async () => {
mockAppConnections({
has: jest.fn().mockResolvedValue(false),
});
(mockRegistryInstance.getServerConfig as jest.Mock).mockResolvedValue({
type: 'sse',
url: 'https://oauth-mcp.example.com',
requiresOAuth: true,
});
const manager = await MCPManager.createInstance(newMCPServersConfig());
await expect(
manager.getUserConnection({
serverName,
user: mockUser,
}),
).rejects.toThrow('requires a flowManager');
});
});
});