mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-18 22:14:27 +00:00
🔌 perf: Look Up MCP Server Catalogs Concurrently for Tool Definitions (#17973)
* perf: Look Up MCP Server Catalogs Concurrently for Tool Definitions * test: Cover MCP Sign-In Order for Concurrent Catalog Lookups * docs: Widen the mcpCatalogLookups Comment in the Example Config * test: Cover the Catalog Lookup Bound Passed to the Definitions Loader
This commit is contained in:
parent
0701ce70a7
commit
bcbb8290ec
7 changed files with 1036 additions and 61 deletions
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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 };
|
||||
|
|
|
|||
113
e2e/specs/mock/scenarios/mcp-oauth-order.spec.ts
Normal file
113
e2e/specs/mock/scenarios/mcp-oauth-order.spec.ts
Normal file
|
|
@ -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<AgentDetail>(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<GenerationStatus>(
|
||||
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);
|
||||
}
|
||||
});
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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<Promise<Fetched>, [string, string]>;
|
||||
|
||||
const settle = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
|
||||
|
||||
function deferred<T>() {
|
||||
let resolve!: (value: T) => void;
|
||||
let reject!: (error: Error) => void;
|
||||
const promise = new Promise<T>((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<LoadToolDefinitionsResult, 'toolDefinitions'>): string[] =>
|
||||
result.toolDefinitions.map(({ name }) => name);
|
||||
|
||||
const toolServers = (
|
||||
result: Pick<LoadToolDefinitionsResult, 'toolDefinitions'>,
|
||||
): [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<Fetched>();
|
||||
const beta = deferred<Fetched>();
|
||||
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<Fetched>()],
|
||||
['beta', deferred<Fetched>()],
|
||||
['gamma', deferred<Fetched>()],
|
||||
]);
|
||||
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<Fetched>()],
|
||||
['beta', deferred<Fetched>()],
|
||||
['gamma', deferred<Fetched>()],
|
||||
]);
|
||||
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<Fetched>();
|
||||
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<Fetched>()],
|
||||
['beta', deferred<Fetched>()],
|
||||
['gamma', deferred<Fetched>()],
|
||||
]);
|
||||
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<Fetched>();
|
||||
const raw = deferred<Fetched>();
|
||||
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<ActionToolDefinition[]>,
|
||||
[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<Fetched>();
|
||||
const actions = deferred<ActionToolDefinition[]>();
|
||||
const fetch = jest.fn<Promise<Fetched>, [string, string]>(() => alpha.promise);
|
||||
const getActionToolDefinitions = jest.fn<
|
||||
Promise<ActionToolDefinition[]>,
|
||||
[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<never> =>
|
||||
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<ActionToolDefinition[]>,
|
||||
[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<Fetched>();
|
||||
const betaRefresh = deferred<Fetched>();
|
||||
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']);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -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<MCPServerTools | null>;
|
||||
/** Bypasses a non-empty stale catalog when it does not contain a selected tool. */
|
||||
refreshMCPServerTools?: (userId: string, serverName: string) => Promise<MCPServerTools | null>;
|
||||
/** 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<string>,
|
||||
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<string, string>;
|
||||
getOrFetchMCPServerTools: LoadToolDefinitionsDeps['getOrFetchMCPServerTools'];
|
||||
}): Promise<ServerCatalog[]> {
|
||||
const inFlight = new Map<string, Promise<MCPServerTools | null>>();
|
||||
const fetchOnce = (serverName: string): Promise<MCPServerTools | null> => {
|
||||
const pending = inFlight.get(serverName) ?? getOrFetchMCPServerTools(userId, serverName);
|
||||
inFlight.set(serverName, pending);
|
||||
return pending;
|
||||
};
|
||||
|
||||
return mapWithConcurrency(serverKeys, concurrency, async (serverKey): Promise<ServerCatalog> => {
|
||||
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<string, string>();
|
||||
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<string>();
|
||||
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<ActionToolDefinition[]> =>
|
||||
actionToolNames.length > 0 && getActionToolDefinitions
|
||||
? getActionToolDefinitions(agentId, actionToolNames)
|
||||
: [];
|
||||
|
||||
const resolveKeys = (keys: readonly string[]): Promise<ServerCatalog[]> =>
|
||||
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<string, readonly string[]>();
|
||||
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<string>();
|
||||
|
||||
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,
|
||||
};
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue