diff --git a/api/server/services/ToolService.js b/api/server/services/ToolService.js index b6b9f4c96a..fbab10584a 100644 --- a/api/server/services/ToolService.js +++ b/api/server/services/ToolService.js @@ -14,6 +14,7 @@ const { createAuthIdentityContext, selectMCPUpstreamTokenProvider, loadToolDefinitions, + orderMCPServerNames, createMCPToolApprovalMetadata, GenerationJobManager, isActionDomainAllowed, @@ -1403,6 +1404,7 @@ async function loadToolDefinitionsWrapper({ mcpToolAliases, mcpResolution, oauthActionToolNames, + mcpServerLookupOrder, } = await loadToolDefinitions( { userId: req.user.id, @@ -1420,6 +1422,7 @@ async function loadToolDefinitionsWrapper({ mcpServerNames, rawServerNames: mcpRawServerNames, accessibleServerNames: defsAccessibleServerNames, + mcpCatalogLookups: appConfig?.concurrency?.mcpCatalogLookups, }, { isBuiltInTool, @@ -1443,7 +1446,7 @@ async function loadToolDefinitionsWrapper({ } if (pendingOAuthServers.size > 0 && (res || streamId)) { - const serverNames = Array.from(pendingOAuthServers); + const serverNames = orderMCPServerNames(pendingOAuthServers, mcpServerLookupOrder); logger.info( `[Tool Definitions] MCP OAuth required for ${serverNames.length} server(s); emitting events and waiting`, ); @@ -1518,6 +1521,7 @@ async function loadToolDefinitionsWrapper({ mcpServerNames, rawServerNames: mcpRawServerNames, accessibleServerNames: defsAccessibleServerNames, + mcpCatalogLookups: appConfig?.concurrency?.mcpCatalogLookups, }, { isBuiltInTool, diff --git a/api/server/services/__tests__/ToolService.spec.js b/api/server/services/__tests__/ToolService.spec.js index 0872784d06..089eda792d 100644 --- a/api/server/services/__tests__/ToolService.spec.js +++ b/api/server/services/__tests__/ToolService.spec.js @@ -1799,6 +1799,120 @@ describe('ToolService - Action Capability Gating', () => { ]); }); + it('numbers the pending MCP OAuth login steps in the order the loader looked the servers up', async () => { + const req = createMockReq([AgentCapabilities.tools]); + const res = { writableEnded: false }; + const servers = ['ELI', 'Vespa']; + mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools])); + mockResolveConfigServers.mockResolvedValue( + Object.fromEntries( + servers.map((serverName) => [ + serverName, + { + type: 'streamable-http', + url: `https://mcp.example.com/${serverName}`, + requiresOAuth: true, + }, + ]), + ), + ); + + mockLoadToolDefinitions + .mockImplementationOnce(async (_args, deps) => { + /** Lookups run together, so the second server can be the first to need its sign-in. */ + await deps.getOrFetchMCPServerTools(req.user.id, servers[1]); + await deps.getOrFetchMCPServerTools(req.user.id, servers[0]); + return { + toolDefinitions: [], + toolRegistry: new Map(), + hasDeferredTools: false, + mcpServerLookupOrder: servers, + }; + }) + .mockResolvedValue({ + toolDefinitions: [], + toolRegistry: new Map(), + hasDeferredTools: false, + }); + + reinitMCPServer.mockImplementation( + async ({ serverName, returnOnOAuth, oauthStart, oauthEnd }) => { + if (returnOnOAuth === false) { + await oauthStart(`https://auth.example.com/${serverName}`); + await oauthEnd(); + return { availableTools: { [`tool_${serverName}`]: {} } }; + } + + await oauthStart(`https://auth.example.com/${serverName}`); + return { availableTools: null }; + }, + ); + + await loadAgentTools({ + req, + res, + agent: { + id: 'agent_123', + tools: servers.map((server) => `search${Constants.mcp_delimiter}${server}`), + }, + definitionsOnly: true, + }); + + const stepIndexes = Object.fromEntries( + mockSendEvent.mock.calls + .map(([, event]) => event) + .filter((event) => event.data?.stepDetails?.type === 'tool_calls') + .map((event) => [event.data.id, event.data.index]), + ); + expect(stepIndexes).toEqual({ step_oauth_login_ELI: 0, step_oauth_login_Vespa: 1 }); + }); + + it('passes the configured MCP catalog lookup bound to the definitions loader and to its reload after OAuth', async () => { + const req = createMockReq([AgentCapabilities.tools]); + req.config.concurrency = { mcpCatalogLookups: 2 }; + const res = { writableEnded: false }; + const serverName = 'ELI'; + mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig([AgentCapabilities.tools])); + mockResolveConfigServers.mockResolvedValue({ + [serverName]: { + type: 'streamable-http', + url: `https://mcp.example.com/${serverName}`, + requiresOAuth: true, + }, + }); + + mockLoadToolDefinitions + .mockImplementationOnce(async (params, deps) => { + await deps.getOrFetchMCPServerTools(params.userId, serverName); + return { toolDefinitions: [], toolRegistry: new Map(), hasDeferredTools: false }; + }) + .mockResolvedValue({ + toolDefinitions: [], + toolRegistry: new Map(), + hasDeferredTools: false, + }); + + reinitMCPServer.mockImplementation(async ({ returnOnOAuth, oauthStart, oauthEnd }) => { + await oauthStart(`https://auth.example.com/${serverName}`); + if (returnOnOAuth === false) { + await oauthEnd(); + return { availableTools: { [`tool_${serverName}`]: {} } }; + } + return { availableTools: null }; + }); + + await loadAgentTools({ + req, + res, + agent: { id: 'agent_123', tools: [`search${Constants.mcp_delimiter}${serverName}`] }, + definitionsOnly: true, + }); + + expect( + mockLoadToolDefinitions.mock.calls.map(([params]) => params.mcpCatalogLookups), + ).toEqual([2, 2]); + }); + it('does not count an empty post-OAuth catalog as tools available or reload definitions', async () => { const req = createMockReq([AgentCapabilities.tools]); const res = { writableEnded: false }; diff --git a/e2e/specs/mock/scenarios/mcp-oauth-order.spec.ts b/e2e/specs/mock/scenarios/mcp-oauth-order.spec.ts new file mode 100644 index 0000000000..22459d6276 --- /dev/null +++ b/e2e/specs/mock/scenarios/mcp-oauth-order.spec.ts @@ -0,0 +1,113 @@ +import { expect, test } from '@playwright/test'; +import type { Page } from '@playwright/test'; +import type { Agents } from 'librechat-data-provider'; +import type { AgentDetail } from '../agents.helpers'; +import { cleanupAgent, openAgentBuilder, uniqueAgentName } from '../agents.helpers'; +import { + MOCK_ENDPOINTS, + NEW_CHAT_PATH, + fetchJson, + getAccessToken, + requestJson, + sendMessage, +} from '../helpers'; + +const SERVERS = ['e2e-oauth', 'e2e-oauth-deferred'] as const; +const SIGN_IN_BUTTON = /Sign-in to 127\.0\.0\.1/i; +const SIGN_IN_TOOL_PREFIX = 'oauth_mcp_'; + +type GenerationStatus = { + resumeState?: { + runSteps?: Agents.RunStep[]; + pendingOAuthPrompts?: Agents.PendingMCPOAuthPrompt[]; + }; +}; + +/** The agent is picked in the builder side panel, which the mobile layout keeps in a drawer. */ +test.use({ viewport: { width: 1280, height: 860 }, hasTouch: false, isMobile: false }); + +/** The sign-in tool calls of a turn, in the order of the steps that carry them. */ +function signInToolNames(runSteps: Agents.RunStep[] = []): string[] { + return [...runSteps] + .sort((a, b) => a.index - b.index) + .flatMap((step) => { + const details = step.stepDetails as { tool_calls?: Array<{ name?: string }> }; + return (details.tool_calls ?? []).map((call) => call.name ?? ''); + }) + .filter((name) => name.startsWith(SIGN_IN_TOOL_PREFIX)); +} + +/** + * Sends a turn to an agent whose tools come from each protected server in `servers`, in that + * order, and returns the sign-in prompts the turn holds on, once there is one per server. + */ +async function signInsFor(page: Page, servers: readonly string[]) { + await page.goto(NEW_CHAT_PATH, { timeout: 10000 }); + const token = await getAccessToken(page); + const agentName = uniqueAgentName('E2E OAuth Order Agent'); + const agent = await requestJson(page, { + path: '/api/agents', + token, + method: 'POST', + body: { + name: agentName, + description: + 'Verifies the order of the sign-in prompts for tools from two protected servers.', + instructions: 'Use the tools of both servers.', + provider: MOCK_ENDPOINTS[0].label, + model: MOCK_ENDPOINTS[0].model, + tools: servers.map((server) => `echo_mcp_${server}`), + }, + }); + + try { + const form = await openAgentBuilder(page); + await form.getByRole('combobox', { name: 'Agent', exact: true }).click(); + await page.getByRole('option', { name: agentName }).click(); + await expect(form.getByLabel('Agent name')).toHaveValue(agentName); + await form.getByRole('button', { name: 'Select Agent' }).click(); + + const label = `${Date.now()}-${Math.floor(Math.random() * 1e4)}`; + const admission = await sendMessage(page, `Use both servers ${label}`); + expect(admission.ok()).toBeTruthy(); + const { conversationId } = (await admission.json()) as { conversationId?: string }; + expect(conversationId).toBeTruthy(); + + await expect(page.getByRole('button', { name: SIGN_IN_BUTTON })).toHaveCount(servers.length, { + timeout: 30000, + }); + + const status = await fetchJson( + page, + `/api/agents/chat/status/${encodeURIComponent(conversationId!)}`, + token, + ); + return { + steps: signInToolNames(status.resumeState?.runSteps), + prompts: [...(status.resumeState?.pendingOAuthPrompts ?? [])] + .sort((a, b) => a.index - b.index) + .map((prompt) => prompt.toolName), + }; + } finally { + const stop = page.getByRole('button', { name: 'Stop generating' }); + if (await stop.isVisible({ timeout: 1000 }).catch(() => false)) { + await stop.click(); + await expect(stop).toBeHidden({ timeout: 10000 }); + } + await cleanupAgent(page, agent.id); + } +} + +test('an agent with tools from two protected servers asks to sign in to each, in the order of its tools @scenario:mcp-two-protected-servers-sign-in-in-tool-order', async ({ + page, +}) => { + test.setTimeout(240000); + + for (const servers of [SERVERS, [...SERVERS].reverse()]) { + const expected = servers.map((server) => `${SIGN_IN_TOOL_PREFIX}${server}`); + const { steps, prompts } = await signInsFor(page, servers); + + expect(steps).toEqual(expected); + expect(prompts).toEqual(expected); + } +}); diff --git a/librechat.example.yaml b/librechat.example.yaml index d500db8375..e787b91954 100644 --- a/librechat.example.yaml +++ b/librechat.example.yaml @@ -592,7 +592,7 @@ registration: # Upper bounds on independent lookups a request runs at once (1 to 32). Each omitted key keeps the default shown. # concurrency: # connectedAgentLoads: 4 # connected agents initialized together per level of a handoff graph -# mcpCatalogLookups: 4 # MCP tool catalog reads when assembling an ephemeral or added agent +# mcpCatalogLookups: 4 # MCP tool catalog reads when assembling an agent's tools # skillNameLookups: 8 # model spec skill name resolutions # skillFileInspections: 4 # bundled skill file inspections before a skill is primed # resumeAgentLoads: 4 # agent reads while building the resume snapshot of a paused run diff --git a/packages/api/src/tools/definitions.spec.ts b/packages/api/src/tools/definitions.spec.ts index fa87c3c6e2..2746687ca9 100644 --- a/packages/api/src/tools/definitions.spec.ts +++ b/packages/api/src/tools/definitions.spec.ts @@ -1,13 +1,15 @@ import { Providers, WebSearchToolDefinition, GitHubCompareToolDefinition } from '@librechat/agents'; import type { LoadToolDefinitionsParams, + LoadToolDefinitionsResult, LoadToolDefinitionsDeps, ActionToolDefinition, + MCPServerTools, } from './definitions'; +import { loadToolDefinitions, orderMCPServerNames } from './definitions'; import { toolkitExpansion, toolkitParent } from './toolkits/mapping'; import { getToolDefinition } from './registry/definitions'; import { getToolApprovalIdentity } from './approval'; -import { loadToolDefinitions } from './definitions'; import { formatMCPServerTools } from '~/mcp/tools'; import { getToolApprovalName } from './approval'; @@ -1128,6 +1130,592 @@ describe('definitions.ts', () => { }); }); + describe('concurrent MCP and action resolution', () => { + type Fetched = MCPServerTools | null; + type FetchMock = jest.Mock, [string, string]>; + + const settle = (): Promise => new Promise((resolve) => setImmediate(resolve)); + + function deferred() { + let resolve!: (value: T) => void; + let reject!: (error: Error) => void; + const promise = new Promise((yes, no) => { + resolve = yes; + reject = no; + }); + return { promise, resolve, reject }; + } + + /** One tool per name, keyed the way a server catalog builds its keys. */ + function catalogOf(serverName: string, ...names: string[]): MCPServerTools { + const catalog: MCPServerTools = {}; + for (const name of names) { + const key = `${name}_mcp_${serverName}`; + catalog[key] = { + function: { + name: key, + description: `${name} on ${serverName}`, + parameters: { type: 'object', properties: {} }, + }, + }; + } + return catalog; + } + + const calledServers = (fetch: FetchMock): string[] => + fetch.mock.calls.map(([, serverName]) => serverName); + + const toolNames = (result: Pick): string[] => + result.toolDefinitions.map(({ name }) => name); + + const toolServers = ( + result: Pick, + ): [string, string | undefined][] => + result.toolDefinitions.map((def) => [ + def.name, + 'serverName' in def ? def.serverName : undefined, + ]); + + const baseParams = { userId: 'user-123', agentId: 'agent-123' }; + + it('starts the fetch for every distinct server before any of them resolves', async () => { + const alpha = deferred(); + const beta = deferred(); + const fetch: FetchMock = jest.fn((_userId, serverName) => + serverName === 'alpha' ? alpha.promise : beta.promise, + ); + + const loading = loadToolDefinitions( + { ...baseParams, tools: ['search_mcp_alpha', 'list_mcp_beta'] }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + await settle(); + + try { + expect(calledServers(fetch)).toEqual(['alpha', 'beta']); + } finally { + alpha.resolve(catalogOf('alpha', 'search')); + beta.resolve(catalogOf('beta', 'list')); + } + + const result = await loading; + expect(toolNames(result)).toEqual(['search_mcp_alpha', 'list_mcp_beta']); + expect(result.mcpResolution).toEqual({ expectedToolCount: 2, resolvedToolCount: 2 }); + }); + + it('fetches a server once however many of its tools are selected', async () => { + const fetch: FetchMock = jest.fn(async (_userId, serverName) => + catalogOf(serverName, 'search', 'list'), + ); + + const result = await loadToolDefinitions( + { ...baseParams, tools: ['search_mcp_alpha', 'list_mcp_beta', 'list_mcp_alpha'] }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + + expect(calledServers(fetch).sort()).toEqual(['alpha', 'beta']); + expect(toolNames(result)).toEqual(['search_mcp_alpha', 'list_mcp_beta', 'list_mcp_alpha']); + expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 3 }); + }); + + it('keeps tool order in the output whatever order the fetches settle in', async () => { + const gates = new Map([ + ['alpha', deferred()], + ['beta', deferred()], + ['gamma', deferred()], + ]); + const fetch: FetchMock = jest.fn( + (_userId, serverName) => gates.get(serverName)?.promise ?? Promise.resolve(null), + ); + + const loading = loadToolDefinitions( + { ...baseParams, tools: ['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma'] }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + await settle(); + + try { + expect(calledServers(fetch)).toEqual(['alpha', 'beta', 'gamma']); + } finally { + gates.get('gamma')?.resolve(catalogOf('gamma', 'c')); + gates.get('alpha')?.resolve(catalogOf('alpha', 'a')); + gates.get('beta')?.resolve(catalogOf('beta', 'b')); + } + + const result = await loading; + expect(toolNames(result)).toEqual(['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma']); + }); + + it('holds a lookup back until one of the allowed number has settled', async () => { + const gates = new Map([ + ['alpha', deferred()], + ['beta', deferred()], + ['gamma', deferred()], + ]); + const fetch: FetchMock = jest.fn( + (_userId, serverName) => gates.get(serverName)?.promise ?? Promise.resolve(null), + ); + + const loading = loadToolDefinitions( + { + ...baseParams, + tools: ['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma'], + mcpCatalogLookups: 2, + }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + await settle(); + + try { + expect(calledServers(fetch)).toEqual(['alpha', 'beta']); + gates.get('beta')?.resolve(catalogOf('beta', 'b')); + await settle(); + expect(calledServers(fetch)).toEqual(['alpha', 'beta', 'gamma']); + } finally { + gates.get('alpha')?.resolve(catalogOf('alpha', 'a')); + gates.get('beta')?.resolve(catalogOf('beta', 'b')); + gates.get('gamma')?.resolve(catalogOf('gamma', 'c')); + } + + const result = await loading; + expect(toolNames(result)).toEqual(['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma']); + }); + + it('looks servers up one after another when the bound is 1', async () => { + const alpha = deferred(); + const fetch: FetchMock = jest.fn((_userId, serverName) => + serverName === 'alpha' ? alpha.promise : Promise.resolve(catalogOf('beta', 'list')), + ); + + const loading = loadToolDefinitions( + { ...baseParams, tools: ['search_mcp_alpha', 'list_mcp_beta'], mcpCatalogLookups: 1 }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + await settle(); + + try { + expect(calledServers(fetch)).toEqual(['alpha']); + } finally { + alpha.resolve(catalogOf('alpha', 'search')); + } + + const result = await loading; + expect(calledServers(fetch)).toEqual(['alpha', 'beta']); + expect(toolNames(result)).toEqual(['search_mcp_alpha', 'list_mcp_beta']); + }); + + it('reports the looked-up servers in tool order whatever order they settle in', async () => { + const gates = new Map([ + ['alpha', deferred()], + ['beta', deferred()], + ['gamma', deferred()], + ]); + const fetch: FetchMock = jest.fn( + (_userId, serverName) => gates.get(serverName)?.promise ?? Promise.resolve(null), + ); + + const loading = loadToolDefinitions( + { ...baseParams, tools: ['a_mcp_alpha', 'b_mcp_beta', 'c_mcp_gamma', 'd_mcp_alpha'] }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + await settle(); + gates.get('gamma')?.resolve(catalogOf('gamma', 'c')); + gates.get('beta')?.resolve(null); + gates.get('alpha')?.resolve(catalogOf('alpha', 'a', 'd')); + + const result = await loading; + expect(result.mcpServerLookupOrder).toEqual(['alpha', 'beta', 'gamma']); + }); + + describe('alias fallback', () => { + const aliasParams = { + ...baseParams, + mcpServerNames: ['alpha', 'Connector__Company', 'Other__Server'], + rawServerNames: ['alpha', 'Connector: Company', 'Other: Server'], + accessibleServerNames: ['alpha', 'Other__Server', 'Other: Server'], + }; + + it('falls back to the raw alias only for a parsed name that is not a known server', async () => { + const fetch: FetchMock = jest.fn(async (_userId, serverName) => { + if (serverName === 'alpha') { + return catalogOf('alpha', 'search'); + } + return serverName === 'Connector: Company' + ? catalogOf('Connector__Company', 'find') + : null; + }); + + const result = await loadToolDefinitions( + { + ...aliasParams, + tools: ['search_mcp_alpha', 'find_mcp_Connector__Company', 'ping_mcp_Other__Server'], + }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + + expect(calledServers(fetch).sort()).toEqual([ + 'Connector: Company', + 'Connector__Company', + 'Other__Server', + 'alpha', + ]); + expect(toolServers(result)).toEqual([ + ['search_mcp_alpha', 'alpha'], + ['find_mcp_Connector__Company', 'Connector: Company'], + ]); + expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 2 }); + }); + + it('shares one in-flight fetch between a direct lookup and an alias fallback to the same server', async () => { + /** `Connector__Company` is not a known server, so it falls back to its raw alias, + * which the second tool key is already looking up directly. */ + const normalized = deferred(); + const raw = deferred(); + const fetch: FetchMock = jest.fn((_userId, serverName) => + serverName === 'Connector__Company' ? normalized.promise : raw.promise, + ); + + const loading = loadToolDefinitions( + { + ...aliasParams, + tools: ['search_mcp_Connector__Company', 'lookup_mcp_Connector: Company'], + }, + { getOrFetchMCPServerTools: fetch, isBuiltInTool: () => false }, + ); + await settle(); + normalized.resolve(null); + await settle(); + raw.resolve({ + ...catalogOf('Connector__Company', 'search'), + ...catalogOf('Connector: Company', 'lookup'), + }); + + const result = await loading; + expect(calledServers(fetch)).toEqual(['Connector__Company', 'Connector: Company']); + expect(toolServers(result)).toEqual([ + ['search_mcp_Connector__Company', 'Connector: Company'], + ['lookup_mcp_Connector: Company', 'Connector: Company'], + ]); + }); + }); + + it('keeps definition order, counts and OAuth action names for a mixed tool list', async () => { + const fetch: FetchMock = jest.fn(async (_userId, serverName) => + serverName === 'alpha' ? catalogOf('alpha', 'search') : catalogOf('beta', 'list', 'get'), + ); + const getActionToolDefinitions = jest.fn< + Promise, + [string, string[]] + >(async () => [ + { name: 'getWeather_action_weather_com', description: 'Get weather' }, + { name: 'sendMail_action_mail_example_com', description: 'Send an email', oauth: true }, + ]); + + const result = await loadToolDefinitions( + { + ...baseParams, + tools: [ + 'calculator', + 'search_mcp_alpha', + 'getWeather_action_weather---com', + 'sys__all__sys_mcp_beta', + 'web_search', + 'ghost_mcp_alpha', + 'sys__server__sys_mcp_alpha', + 'sendMail_action_mail---example---com', + 'not_a_builtin', + ], + }, + { + getOrFetchMCPServerTools: fetch, + getActionToolDefinitions, + isBuiltInTool: (name) => name === 'calculator' || name === 'web_search', + }, + ); + + expect(toolNames(result)).toEqual([ + 'search_mcp_alpha', + 'list_mcp_beta', + 'get_mcp_beta', + 'getWeather_action_weather_com', + 'sendMail_action_mail_example_com', + 'calculator', + 'web_search', + ]); + expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 3 }); + expect(result.oauthActionToolNames).toEqual(['sendMail_action_mail_example_com']); + expect(calledServers(fetch).sort()).toEqual(['alpha', 'beta']); + expect(getActionToolDefinitions).toHaveBeenCalledWith('agent-123', [ + 'getWeather_action_weather---com', + 'sendMail_action_mail---example---com', + ]); + }); + + it('starts the action definition fetch while MCP fetches are still pending', async () => { + const alpha = deferred(); + const actions = deferred(); + const fetch = jest.fn, [string, string]>(() => alpha.promise); + const getActionToolDefinitions = jest.fn< + Promise, + [string, string[]] + >(() => actions.promise); + + const loading = loadToolDefinitions( + { ...baseParams, tools: ['search_mcp_alpha', 'getWeather_action_weather---com'] }, + { getOrFetchMCPServerTools: fetch, getActionToolDefinitions, isBuiltInTool: () => false }, + ); + await settle(); + + try { + expect(getActionToolDefinitions).toHaveBeenCalledWith('agent-123', [ + 'getWeather_action_weather---com', + ]); + expect(calledServers(fetch)).toEqual(['alpha']); + } finally { + actions.resolve([{ name: 'getWeather_action_weather_com', description: 'Get weather' }]); + alpha.resolve(catalogOf('alpha', 'search')); + } + + const result = await loading; + expect(toolNames(result)).toEqual(['search_mcp_alpha', 'getWeather_action_weather_com']); + }); + + describe('failures', () => { + const failureTools = ['a_mcp_alpha', 'b_mcp_beta']; + + it('rejects with the error of a rejecting fetch, while a null fetch only leaves the server empty', async () => { + const failure = new Error('registry down'); + + await expect( + loadToolDefinitions( + { ...baseParams, tools: failureTools }, + { + getOrFetchMCPServerTools: async (_userId, serverName) => { + if (serverName === 'alpha') { + throw failure; + } + return catalogOf('beta', 'b'); + }, + isBuiltInTool: () => false, + }, + ), + ).rejects.toBe(failure); + + const unavailable = await loadToolDefinitions( + { ...baseParams, tools: failureTools }, + { getOrFetchMCPServerTools: async () => null, isBuiltInTool: () => false }, + ); + expect(unavailable.toolDefinitions).toEqual([]); + expect(unavailable.mcpResolution).toEqual({ expectedToolCount: 2, resolvedToolCount: 0 }); + }); + + it('rejects with the error of the action fetch', async () => { + const failure = new Error('actions unavailable'); + + await expect( + loadToolDefinitions( + { ...baseParams, tools: ['a_mcp_alpha', 'getWeather_action_weather---com'] }, + { + getOrFetchMCPServerTools: async () => catalogOf('alpha', 'a'), + getActionToolDefinitions: async () => { + throw failure; + }, + isBuiltInTool: () => false, + }, + ), + ).rejects.toBe(failure); + }); + + it('leaves no unhandled rejection when the other fetches fail after the first failure', async () => { + /** jest-circus fails the running test on an unhandled rejection, so finishing this one + * after the late failures have fired is the assertion. */ + const failLater: Array<() => void> = []; + const failLate = (label: string): Promise => + new Promise((_resolve, reject) => { + failLater.push(() => reject(new Error(`${label} failed late`))); + }); + const fetch: FetchMock = jest.fn((_userId, serverName) => + serverName === 'alpha' + ? Promise.reject(new Error('alpha failed')) + : failLate(serverName), + ); + const getActionToolDefinitions = jest.fn< + Promise, + [string, string[]] + >(() => failLate('actions')); + + await expect( + loadToolDefinitions( + { + ...baseParams, + tools: [ + 'a_mcp_alpha', + 'b_mcp_beta', + 'c_mcp_gamma', + 'getWeather_action_weather---com', + ], + }, + { + getOrFetchMCPServerTools: fetch, + getActionToolDefinitions, + isBuiltInTool: () => false, + }, + ), + ).rejects.toThrow('alpha failed'); + + expect(failLater).toHaveLength(3); + failLater.forEach((fail) => fail()); + await settle(); + await settle(); + }); + }); + + describe('refresh', () => { + it('stays serial and happens once per server', async () => { + const staleAlpha = catalogOf('alpha', 'list'); + const staleBeta = catalogOf('beta', 'list'); + const alphaRefresh = deferred(); + const betaRefresh = deferred(); + const refresh: FetchMock = jest.fn((_userId, serverName) => + serverName === 'alpha' ? alphaRefresh.promise : betaRefresh.promise, + ); + + const loading = loadToolDefinitions( + { ...baseParams, tools: ['run_mcp_alpha', 'run_mcp_beta', 'other_mcp_alpha'] }, + { + getOrFetchMCPServerTools: async (_userId, serverName) => + serverName === 'alpha' ? staleAlpha : staleBeta, + refreshMCPServerTools: refresh, + isBuiltInTool: () => false, + }, + ); + await settle(); + expect(calledServers(refresh)).toEqual(['alpha']); + + alphaRefresh.resolve({ ...staleAlpha, ...catalogOf('alpha', 'run', 'other') }); + await settle(); + expect(calledServers(refresh)).toEqual(['alpha', 'beta']); + + betaRefresh.resolve({ ...staleBeta, ...catalogOf('beta', 'run') }); + const result = await loading; + + expect(calledServers(refresh)).toEqual(['alpha', 'beta']); + expect(toolNames(result)).toEqual(['run_mcp_alpha', 'run_mcp_beta', 'other_mcp_alpha']); + }); + + it('resolves a later spelling of a refreshed server against the refreshed catalog', async () => { + /** The refreshed catalog is what a later lookup of the same server returns, as it is + * for the request-scoped tool memory the real loader dependency keeps. */ + let current: MCPServerTools = catalogOf('Connector__Company', 'other'); + const refreshed: MCPServerTools = { + ...current, + ...catalogOf('Connector__Company', 'search'), + ...catalogOf('Connector: Company', 'lookup'), + }; + + const result = await loadToolDefinitions( + { + ...baseParams, + tools: ['search_mcp_Connector__Company', 'lookup_mcp_Connector: Company'], + mcpServerNames: ['Connector__Company'], + rawServerNames: ['Connector: Company'], + }, + { + getOrFetchMCPServerTools: async (_userId, serverName) => + serverName === 'Connector: Company' ? current : null, + refreshMCPServerTools: async () => { + current = refreshed; + return refreshed; + }, + isBuiltInTool: () => false, + }, + ); + + expect(toolNames(result)).toEqual([ + 'search_mcp_Connector__Company', + 'lookup_mcp_Connector: Company', + ]); + expect(result.mcpResolution).toEqual({ expectedToolCount: 2, resolvedToolCount: 2 }); + }); + + it('resolves a later spelling again after a refresh made its server available', async () => { + /** `legacy_mcp_Other: Server` names the raw server, unavailable until its refresh; + * `search_mcp_Other__Server` reaches the same server through its alias. */ + let available = false; + const catalog: MCPServerTools = { + ...catalogOf('Other__Server', 'search'), + ...catalogOf('Other: Server', 'legacy'), + }; + const refresh: FetchMock = jest.fn(async (_userId, serverName) => { + if (serverName !== 'Other: Server') { + return null; + } + available = true; + return catalog; + }); + + const result = await loadToolDefinitions( + { + ...baseParams, + tools: ['legacy_mcp_Other: Server', 'search_mcp_Other__Server'], + mcpServerNames: ['Other__Server'], + rawServerNames: ['Other: Server'], + }, + { + getOrFetchMCPServerTools: async (_userId, serverName) => + serverName === 'Other: Server' && available ? catalog : null, + refreshMCPServerTools: refresh, + isBuiltInTool: () => false, + }, + ); + + expect(calledServers(refresh)).toEqual(['Other: Server']); + expect(toolServers(result)).toEqual([ + ['legacy_mcp_Other: Server', 'Other: Server'], + ['search_mcp_Other__Server', 'Other: Server'], + ]); + }); + + it('keeps an earlier spelling on the catalog it was resolved with', async () => { + /** A tool only the refreshed catalog holds stays unresolved under the spelling that + * was already resolved: a refresh through the other spelling does not rewrite it. */ + let current: MCPServerTools = catalogOf('Connector__Company', 't2'); + const refreshed: MCPServerTools = { + ...catalogOf('Connector__Company', 't2', 't3'), + ...catalogOf('Connector: Company', 't3'), + }; + + const result = await loadToolDefinitions( + { + ...baseParams, + tools: [ + 't2_mcp_Connector__Company', + 't3_mcp_Connector: Company', + 't3_mcp_Connector__Company', + ], + mcpServerNames: ['Connector__Company'], + rawServerNames: ['Connector: Company'], + }, + { + getOrFetchMCPServerTools: async (_userId, serverName) => + serverName === 'Connector: Company' ? current : null, + refreshMCPServerTools: async () => { + current = refreshed; + return refreshed; + }, + isBuiltInTool: () => false, + }, + ); + + expect(toolNames(result)).toEqual([ + 't2_mcp_Connector__Company', + 't3_mcp_Connector: Company', + ]); + expect(result.mcpResolution).toEqual({ expectedToolCount: 3, resolvedToolCount: 2 }); + }); + }); + }); + describe('toolkit expansion', () => { it('should expand image_gen_oai to include image_edit_oai', async () => { mockIsBuiltInTool.mockImplementation((name) => name === 'image_gen_oai'); @@ -1345,3 +1933,28 @@ test('live catalog reassignment changes consent while retaining the same display getToolApprovalIdentity(first.toolDefinitions[0]), ); }); + +describe('orderMCPServerNames', () => { + it('puts the names in lookup order', () => { + expect( + orderMCPServerNames(new Set(['gamma', 'alpha', 'beta']), ['alpha', 'beta', 'gamma']), + ).toEqual(['alpha', 'beta', 'gamma']); + }); + + it('keeps names that were never looked up after the rest, in the order given', () => { + expect(orderMCPServerNames(['late', 'beta', 'other', 'alpha'], ['alpha', 'beta'])).toEqual([ + 'alpha', + 'beta', + 'late', + 'other', + ]); + }); + + it('returns nothing for no names', () => { + expect(orderMCPServerNames([], ['alpha'])).toEqual([]); + }); + + it('returns the names as given when no lookup order is known', () => { + expect(orderMCPServerNames(new Set(['beta', 'alpha']))).toEqual(['beta', 'alpha']); + }); +}); diff --git a/packages/api/src/tools/definitions.ts b/packages/api/src/tools/definitions.ts index ebbcfa3b0f..41b83f8c82 100644 --- a/packages/api/src/tools/definitions.ts +++ b/packages/api/src/tools/definitions.ts @@ -21,6 +21,8 @@ import type { CodeEnvironmentConfig, CodeExecutionContext } from '~/agents/execu import type { CodeCapabilityConfigLoader } from '~/code/capabilities'; import type { MCPToolAlias, ToolDefinition } from './classification'; import { resolveJsonSchemaRefs, normalizeJsonSchema, sanitizeGeminiSchema } from '~/mcp/zod'; +import { DEFAULT_LOOKUP_CONCURRENCY } from '~/utils/concurrency'; +import { mapWithConcurrency } from '~/utils/promise'; import { buildToolClassification } from './classification'; import { getToolDefinition } from './registry/definitions'; import { toolkitExpansion } from './toolkits/mapping'; @@ -77,6 +79,12 @@ export interface LoadToolDefinitionsParams { * unavailable server's names. */ accessibleServerNames?: readonly string[]; + /** + * Upper bound on MCP server catalog lookups in flight at once: the deployment's + * `concurrency.mcpCatalogLookups`. A cold lookup can reconnect a server or spawn its process, + * so one request does not start them all together. `1` looks servers up one after another. + */ + mcpCatalogLookups?: number; } export interface ActionToolDefinition { @@ -89,13 +97,15 @@ export interface ActionToolDefinition { } export interface LoadToolDefinitionsDeps { - /** Gets MCP server tools - first checks cache, then initializes server if needed */ + /** Gets MCP server tools - first checks cache, then initializes server if needed. Called + * concurrently for different servers; a server is looked up again only after its refresh. */ getOrFetchMCPServerTools: (userId: string, serverName: string) => Promise; /** Bypasses a non-empty stale catalog when it does not contain a selected tool. */ refreshMCPServerTools?: (userId: string, serverName: string) => Promise; /** Checks if a tool name is a known built-in tool */ isBuiltInTool: (toolName: string) => boolean; - /** Loads action tool definitions (schemas) from OpenAPI specs */ + /** Loads action tool definitions (schemas) from OpenAPI specs. Started together with the + * MCP server lookups. */ getActionToolDefinitions?: ( agentId: string, actionToolNames: string[], @@ -112,16 +122,105 @@ export interface LoadToolDefinitionsResult { expectedToolCount: number; resolvedToolCount: number; }; - /** Action tool names backed by OAuth — excluded from background dispatch. */ + /** Action tool names backed by OAuth; excluded from background dispatch. */ oauthActionToolNames: string[]; + /** + * Every server name that was looked up, in tool order: each parsed key, then its raw alias + * when that was tried. Lookups settle in any order, so work that follows them and must stay in + * tool order (the OAuth sign-in prompts) takes its order from this list. + */ + mcpServerLookupOrder: string[]; +} + +/** + * `names` in the order of `lookupOrder`; names it does not list keep their relative order after + * the listed ones, so without a lookup order the names come back as given. + */ +export function orderMCPServerNames( + names: Iterable, + lookupOrder: readonly string[] = [], +): string[] { + const rank = new Map(lookupOrder.map((name, index) => [name, index])); + const listed: string[] = []; + const unlisted: string[] = []; + for (const name of names) { + (rank.has(name) ? listed : unlisted).push(name); + } + listed.sort((a, b) => (rank.get(a) ?? 0) - (rank.get(b) ?? 0)); + return [...listed, ...unlisted]; } const mcpToolPattern = /_mcp_/; const mcpServerPinPrefix = `${Constants.mcp_server}${Constants.mcp_delimiter}`; +interface ServerCatalog { + serverKey: string; + /** Server names the lookup asked for: the key, then its alias when that was tried. */ + lookups: string[]; + tools: MCPServerTools; + /** The RAW server name the key resolved to (direct-first). */ + resolvedName: string; +} + +/** + * Fetches the catalog of every distinct parsed server key, at most `concurrency` keys at a time. + * Each key resolves DIRECT-FIRST: the parsed name as-is, then, only when it is not a known + * accessible server, its raw alias. Within one resolution a fetch is shared by server name, so a + * direct lookup and an alias fallback that land on the same server make one call instead of + * racing two reconnects. + * + * A rejected fetch rejects the whole resolution. The others keep running but stay observed, so + * a later failure cannot surface as an unhandled rejection. + */ +async function resolveServerCatalogs({ + userId, + serverKeys, + concurrency, + accessibleServerNames, + serverNameAliases, + getOrFetchMCPServerTools, +}: { + userId: string; + serverKeys: readonly string[]; + concurrency: number; + accessibleServerNames?: readonly string[]; + serverNameAliases: ReadonlyMap; + getOrFetchMCPServerTools: LoadToolDefinitionsDeps['getOrFetchMCPServerTools']; +}): Promise { + const inFlight = new Map>(); + const fetchOnce = (serverName: string): Promise => { + const pending = inFlight.get(serverName) ?? getOrFetchMCPServerTools(userId, serverName); + inFlight.set(serverName, pending); + return pending; + }; + + return mapWithConcurrency(serverKeys, concurrency, async (serverKey): Promise => { + let resolvedName = serverKey; + const lookups = [serverKey]; + let fetched = await fetchOnce(serverKey); + if (!fetched) { + /** Alias fallback is for "server not found" ONLY: when the parsed name is a known + * accessible server, a null fetch means it is temporarily unavailable (OAuth pending, + * missing user variables, disconnected) and rerouting to the alias would emit the OTHER + * server's definitions under this server's names. */ + const parsedIsKnownServer = accessibleServerNames?.includes(serverKey) === true; + const aliased = serverNameAliases.get(serverKey); + if (!parsedIsKnownServer && aliased != null && aliased !== serverKey) { + lookups.push(aliased); + fetched = await fetchOnce(aliased); + if (fetched) { + resolvedName = aliased; + } + } + } + return { serverKey, lookups, tools: fetched || {}, resolvedName }; + }); +} + /** * Loads tool definitions without creating tool instances. * This is the efficient path for event-driven mode where tools are loaded on-demand. + * MCP servers and action definitions are resolved concurrently. */ export async function loadToolDefinitions( params: LoadToolDefinitionsParams, @@ -142,6 +241,7 @@ export async function loadToolDefinitions( mcpServerNames, rawServerNames, accessibleServerNames, + mcpCatalogLookups = DEFAULT_LOOKUP_CONCURRENCY.mcpCatalogLookups, } = params; const { getOrFetchMCPServerTools, @@ -169,6 +269,7 @@ export async function loadToolDefinitions( mcpToolAliases: [], mcpResolution: { expectedToolCount: 0, resolvedToolCount: 0 }, oauthActionToolNames: [], + mcpServerLookupOrder: [], }; if (!tools || tools.length === 0) { @@ -181,8 +282,11 @@ export async function loadToolDefinitions( const resolvedServerNames = new Map(); const mcpToolDefs: ToolDefinition[] = []; const builtInToolDefs: ToolDefinition[] = []; - let actionToolDefs: ToolDefinition[] = []; const actionToolNames: string[] = []; + /** Tools that get a definition built, in selection order; `serverKey` is set for MCP tools. */ + const selectedTools: { toolName: string; serverKey?: string }[] = []; + /** Distinct parsed server keys, in first-seen order. */ + const serverKeys = new Set(); let expectedMCPToolCount = 0; let resolvedMCPToolCount = 0; @@ -196,6 +300,66 @@ export async function loadToolDefinitions( } if (!mcpToolPattern.test(toolName)) { + selectedTools.push({ toolName }); + continue; + } + + if (toolName.startsWith(mcpServerPinPrefix)) { + continue; + } + + /** Keys carry the normalized server name (raw in pre-normalization data), + * so both spellings resolve the boundary. Resolution is DIRECT-FIRST: a + * server that resolves under the parsed name as-is wins (a user-DB + * server may be named exactly like an operator server's normalized + * form), and only when that yields nothing is the parsed name treated + * as a normalized spelling of a raw config name. The resolved RAW name + * feeds config lookups and definition metadata (`serverName`, then + * `mcpRawServerName`); server instructions are keyed by it. */ + const [, parsedServerName] = splitMCPToolKey(toolName, [ + ...(mcpServerNames ?? []), + ...(rawServerNames ?? []), + ]); + const serverKey = parsedServerName ?? toolName; + serverKeys.add(serverKey); + selectedTools.push({ toolName, serverKey }); + } + + const loadActionDefinitions = async (): Promise => + actionToolNames.length > 0 && getActionToolDefinitions + ? getActionToolDefinitions(agentId, actionToolNames) + : []; + + const resolveKeys = (keys: readonly string[]): Promise => + resolveServerCatalogs({ + userId, + serverKeys: keys, + concurrency: mcpCatalogLookups, + accessibleServerNames, + serverNameAliases, + getOrFetchMCPServerTools, + }); + /** Server names each key asked for, to find the keys a refreshed server concerns. */ + const lookedUp = new Map(); + const adopt = (catalogs: ServerCatalog[]): void => { + for (const catalog of catalogs) { + mcpServerToolsCache.set(catalog.serverKey, catalog.tools); + resolvedServerNames.set(catalog.serverKey, catalog.resolvedName); + lookedUp.set(catalog.serverKey, catalog.lookups); + } + }; + + const [catalogs, fetchedActionDefs] = await Promise.all([ + resolveKeys(Array.from(serverKeys)), + loadActionDefinitions(), + ]); + adopt(catalogs); + const mcpServerLookupOrder = Array.from(new Set(catalogs.flatMap((catalog) => catalog.lookups))); + /** Keys whose first tool has been handled: their catalog is settled for the rest of the load. */ + const builtKeys = new Set(); + + for (const { toolName, serverKey: parsed } of selectedTools) { + if (parsed == null) { if (!isBuiltInTool(toolName)) { continue; } @@ -225,47 +389,8 @@ export async function loadToolDefinitions( continue; } - if (toolName.startsWith(mcpServerPinPrefix)) { - continue; - } - expectedMCPToolCount++; - - /** Keys carry the normalized server name (raw in pre-normalization data), - * so both spellings resolve the boundary. Resolution is DIRECT-FIRST: a - * server that resolves under the parsed name as-is wins (a user-DB - * server may be named exactly like an operator server's normalized - * form), and only when that yields nothing is the parsed name treated - * as a normalized spelling of a raw config name. The resolved RAW name - * feeds config lookups and definition metadata (`serverName`, then - * `mcpRawServerName`) — server instructions are keyed by it. */ - const [, parsedServerName] = splitMCPToolKey(toolName, [ - ...(mcpServerNames ?? []), - ...(rawServerNames ?? []), - ]); - const parsed = parsedServerName ?? toolName; - - if (!mcpServerToolsCache.has(parsed)) { - let resolvedName = parsed; - let fetched = await getOrFetchMCPServerTools(userId, parsed); - if (!fetched) { - /** Alias fallback is for "server not found" ONLY: when the parsed - * name is a known accessible server, a null fetch means it is - * temporarily unavailable (OAuth pending, missing user variables, - * disconnected) and rerouting to the alias would emit the OTHER - * server's definitions under this server's names. */ - const parsedIsKnownServer = accessibleServerNames?.includes(parsed) === true; - const aliased = serverNameAliases.get(parsed); - if (!parsedIsKnownServer && aliased != null && aliased !== parsed) { - fetched = await getOrFetchMCPServerTools(userId, aliased); - if (fetched) { - resolvedName = aliased; - } - } - } - mcpServerToolsCache.set(parsed, fetched || {}); - resolvedServerNames.set(parsed, resolvedName); - } + builtKeys.add(parsed); const serverName = resolvedServerNames.get(parsed) ?? parsed; let serverTools = mcpServerToolsCache.get(parsed); @@ -311,6 +436,14 @@ export async function loadToolDefinitions( if (refreshedTools != null) { mcpServerToolsCache.set(parsed, refreshedTools); serverTools = refreshedTools; + /** The normalized and raw spellings of one server are separate keys. A key not handled + * yet that looked this server up resolves again, now that it is refreshed. */ + const unbuiltKeys = Array.from(serverKeys).filter( + (key) => !builtKeys.has(key) && lookedUp.get(key)?.includes(serverName), + ); + if (unbuiltKeys.length > 0) { + adopt(await resolveKeys(unbuiltKeys)); + } } } @@ -375,19 +508,16 @@ export async function loadToolDefinitions( } const oauthActionToolNames: string[] = []; - if (actionToolNames.length > 0 && getActionToolDefinitions) { - const fetchedActionDefs = await getActionToolDefinitions(agentId, actionToolNames); - actionToolDefs = fetchedActionDefs.map((def) => { - if (def.oauth === true) { - oauthActionToolNames.push(def.name); - } - return { - name: def.name, - description: def.description, - parameters: def.parameters, - }; - }); - } + const actionToolDefs: ToolDefinition[] = fetchedActionDefs.map((def) => { + if (def.oauth === true) { + oauthActionToolNames.push(def.name); + } + return { + name: def.name, + description: def.description, + parameters: def.parameters, + }; + }); const loadedTools = mcpToolDefs.map((def) => bindToolApproval( @@ -462,5 +592,6 @@ export async function loadToolDefinitions( resolvedToolCount: resolvedMCPToolCount, }, oauthActionToolNames, + mcpServerLookupOrder, }; } diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index 4adb129256..11e485eb40 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -2790,7 +2790,7 @@ export const lookupConcurrencySchema = z.object({ permissionPrincipalLookups: lookupConcurrency, /** Connected agents initialized together per level while discovering a handoff graph. */ connectedAgentLoads: lookupConcurrency, - /** MCP tool catalog reads when assembling an ephemeral or added agent. */ + /** MCP tool catalog reads when assembling an agent's tools. */ mcpCatalogLookups: lookupConcurrency, /** Model spec skill name resolutions. */ skillNameLookups: lookupConcurrency,