@samanhappy/mcphub 1.0.42 → 1.0.44

package/dist/services/mcpService.js

@@ -1,3 +1,4 @@
+import { getMcpRequestGroup } from '../utils/mcpRequestGroup.js';
 import { LegacyMcpClient } from '../clients/legacyMcpClient.js';
 import { LEGACY_PROTOCOL_VERSIONS } from '../utils/mcpProtocol.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -24,7 +25,7 @@ import config from '../config/index.js';
 import { validateServerName } from '../utils/serverNameValidation.js';
 import { getGroup } from './sseService.js';
 import { getServerConfigInGroup, normalizeGroupServers } from './groupService.js';
-import { removeServerToolEmbeddings, saveToolsAsVectorEmbeddings } from './vectorSearchService.js';
+import { removeServerToolEmbeddings, removeToolEmbeddings, saveToolsAsVectorEmbeddings, } from './vectorSearchService.js';
 import { OpenAPIClient } from '../clients/openapi.js';
 import { RequestContextService } from './requestContextService.js';
 import { getDataService } from './services.js';
@@ -517,7 +518,24 @@ const applyDescriptionOverridesForEmbedding = async (serverName, tools) => {
             : tool;
     });
 };
-const syncToolsAsVectorEmbeddings = async (serverName, tools, options) => {
+// Tail of the embedding tasks queued per server. A per-user connect and a
+// reindex, or two users connecting at once, often race on the same tool set;
+// queued behind the first run, the second one hits the skip check in
+// saveToolsAsVectorEmbeddings instead of embedding every tool a second time.
+const embeddingSyncTails = new Map();
+// Run `task` after every embedding task already queued for the server. A task
+// must not wait for another queued task of the same server, or both stall.
+const enqueueEmbeddingTask = (serverName, task) => {
+    const run = (embeddingSyncTails.get(serverName) ?? Promise.resolve()).then(task);
+    const tail = run.catch(() => undefined);
+    embeddingSyncTails.set(serverName, tail);
+    void tail.then(() => {
+        if (embeddingSyncTails.get(serverName) === tail)
+            embeddingSyncTails.delete(serverName);
+    });
+    return run;
+};
+export const syncToolsAsVectorEmbeddings = (serverName, tools, options) => enqueueEmbeddingTask(serverName, async () => {
     const toolsWithOverrides = await applyDescriptionOverridesForEmbedding(serverName, tools);
     const modelVisibleTools = filterModelVisibleTools(toolsWithOverrides);
     if (modelVisibleTools.length === 0) {
@@ -527,6 +545,38 @@ const syncToolsAsVectorEmbeddings = async (serverName, tools, options) => {
         return;
     }
     await saveToolsAsVectorEmbeddings(serverName, modelVisibleTools, options);
+});
+/**
+ * Embed the tools of a credential server, which never connects globally.
+ * Tools disabled in the server's tools config are never embedded: search
+ * filters them out of the hits anyway, but only after they have taken result
+ * slots. A toggle reaches the index without extra wiring: the tools config is
+ * part of the runtime revision, so the next acquire reconnects and re-syncs.
+ *
+ * Two callers, two scopes:
+ * - `partial: true` (every per-user connect): the list is what one user's
+ *   credentials show, and users may see different tools. The rows of the
+ *   listed, enabled tools are added or refreshed and nothing else is pruned,
+ *   so tools only other users see stay indexed. The listed tools that are
+ *   disabled are removed by name, queued before the sync.
+ * - otherwise (the reindex endpoint, which passes the union of every binding's
+ *   tools): the list is complete, so rows of tools outside it are pruned.
+ *
+ * Resolves to the number of tools handed to the vector store.
+ */
+export const syncCredentialServerToolEmbeddings = async (serverName, tools, options) => {
+    const enabledTools = await filterToolsByConfig(serverName, tools);
+    if (options?.partial) {
+        const enabledNames = new Set(enabledTools.map((tool) => tool.name));
+        const disabledNames = tools
+            .map((tool) => tool.name)
+            .filter((toolName) => !enabledNames.has(toolName));
+        if (disabledNames.length > 0) {
+            void enqueueEmbeddingTask(serverName, () => removeToolEmbeddings(serverName, disabledNames)).catch(() => undefined);
+        }
+    }
+    await syncToolsAsVectorEmbeddings(serverName, enabledTools, options);
+    return enabledTools.length;
 };
 // Normalize prompt payload to satisfy MCP ListPrompts response schema
 const normalizePromptForList = (prompt) => {
@@ -652,6 +702,65 @@ const getVisibleServerByName = (name) => {
 const sessionIsolatedClients = new Map();
 // Locks to prevent concurrent creation of the same isolated client
 const isolatedClientCreationLocks = new Map();
+// Explicit application state for modern clients, independent of MCP transports.
+// Active calls pin entries; idle state expires and admission is bounded.
+const CLIENT_STATE_IDLE_MS = 30 * 60 * 1000;
+const MAX_CLIENT_STATES = 1000;
+const clientStates = new Map();
+let clientStateSweep;
+const removeClientState = (id) => {
+    const state = clientStates.get(id);
+    if (!state)
+        return;
+    clientStates.delete(id);
+    cleanupIsolatedSession(id);
+    for (const client of state.cookieClients)
+        client.clearSessionCookies(id);
+};
+const acquireClientState = (serverInfo) => {
+    const contextService = RequestContextService.getInstance();
+    const scope = contextService.getRequestContext()?.clientStateScope;
+    const handle = contextService.getHeader('x-mcphub-state-id');
+    if (!scope ||
+        typeof handle !== 'string' ||
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(handle)) {
+        throw new Error('Stateful tools on stateless MCP require authenticated bearer access and X-MCPHub-State-Id (UUID v4)');
+    }
+    const id = `client-state:${scope}:${handle.toLowerCase()}`;
+    let state = clientStates.get(id);
+    if (state && state.active === 0 && Date.now() - state.lastUsed >= CLIENT_STATE_IDLE_MS) {
+        removeClientState(id);
+        state = undefined;
+    }
+    if (!state) {
+        if (clientStates.size >= MAX_CLIENT_STATES) {
+            throw new Error('Client state capacity reached; retry after idle state expires');
+        }
+        state = { active: 0, lastUsed: Date.now(), cookieClients: new Set() };
+        clientStates.set(id, state);
+    }
+    if (!clientStateSweep) {
+        clientStateSweep = setInterval(() => {
+            for (const [key, entry] of clientStates) {
+                if (entry.active === 0 && Date.now() - entry.lastUsed >= CLIENT_STATE_IDLE_MS) {
+                    removeClientState(key);
+                }
+            }
+        }, 60 * 1000);
+        clientStateSweep.unref();
+    }
+    if (serverInfo.openApiClient)
+        state.cookieClients.add(serverInfo.openApiClient);
+    state.active++;
+    const entry = state;
+    return {
+        id,
+        release: () => {
+            entry.active--;
+            entry.lastUsed = Date.now();
+        },
+    };
+};
 export const connectClientWithDiagnostics = async (client, transport, options) => {
     try {
         await client.connect(transport, options);
@@ -789,6 +898,11 @@ export const connected = () => {
 // Global cleanup function to close all connections
 export const cleanupAllServers = () => {
     stopPackageUpdateSweep();
+    if (clientStateSweep)
+        clearInterval(clientStateSweep);
+    clientStateSweep = undefined;
+    for (const id of clientStates.keys())
+        removeClientState(id);
     principalRuntimes.invalidate();
     for (const serverInfo of serverInfos) {
         try {
@@ -2880,17 +2994,7 @@ const projectToolForDownstream = (serverName, tool, appsRouteContext, serverConf
         name: projectNameForGroup(projectedTool.name, serverName, serverConfig),
     };
 };
-const handleListToolsRequestImpl = async (_, extra) => {
-    const sessionId = extra.sessionId || '';
-    const group = getGroup(sessionId);
-    logger.log(`Handling ListToolsRequest for group: ${group}`);
-    // Special handling for $smart group to return smart routing tools
-    // Support both $smart and $smart/{group} patterns
-    if (isSmartRoutingGroup(group)) {
-        return getSmartRoutingTools(group);
-    }
-    const { filteredServerInfos, serverConfigsByName } = await getFilteredServerInfosForGroup(group);
-    const appsRouteContext = await getMcpAppsRouteContext(sessionId, group);
+const listGroupTools = async (group, filteredServerInfos, serverConfigsByName, appsRouteContext) => {
     // If the startup prime of an on-demand server is still in flight, wait for it
     // so this list reflects the freshly cached tools instead of returning empty.
     // No wake is triggered from list itself; the prime handles that. See #1029.
@@ -2920,8 +3024,60 @@ const handleListToolsRequestImpl = async (_, extra) => {
             }));
         }
     }
+    return allTools;
+};
+// Names the call handler always routes to a meta-tool on a Smart Routing session,
+// whichever of them the current mode lists (see handleCallToolRequestImpl)
+const SMART_ROUTING_META_TOOL_NAMES = new Set(['search_tools', 'describe_tool', 'call_tool']);
+// Tools a $smart/<group> lists next to its meta-tools: each member's pinnedTools,
+// narrowed to its tools selection and then run through the same filtering and
+// projection as a direct group listing.
+const getPinnedSmartRoutingTools = async (group) => {
+    const lookupGroup = getGroupLookupName(group);
+    if (!lookupGroup) {
+        return [];
+    }
+    const { filteredServerInfos, serverConfigsByName } = await getFilteredServerInfosForGroup(lookupGroup);
+    const pinnedConfigsByName = new Map();
+    for (const [serverName, serverConfig] of serverConfigsByName) {
+        const selection = serverConfig.tools;
+        const pinnedTools = (serverConfig.pinnedTools ?? []).filter((toolName) => !Array.isArray(selection) || selection.includes(toolName));
+        if (pinnedTools.length > 0) {
+            pinnedConfigsByName.set(serverName, { ...serverConfig, tools: pinnedTools });
+        }
+    }
+    if (pinnedConfigsByName.size === 0) {
+        return [];
+    }
+    return listGroupTools(lookupGroup, filteredServerInfos.filter((serverInfo) => pinnedConfigsByName.has(serverInfo.name)), pinnedConfigsByName, { enabled: false });
+};
+const handleListToolsRequestImpl = async (_, extra) => {
+    const sessionId = extra.sessionId || '';
+    const group = getMcpRequestGroup(extra);
+    logger.log(`Handling ListToolsRequest for group: ${group}`);
+    // Special handling for $smart group to return smart routing tools
+    // Support both $smart and $smart/{group} patterns
+    if (isSmartRoutingGroup(group)) {
+        const smartRoutingTools = await getSmartRoutingTools(group);
+        let pinnedTools = [];
+        try {
+            // A pin named like a meta-tool (e.g. alias "describe" + separator "_" +
+            // tool "tool") would be intercepted by it on call, even in a mode that
+            // does not list that meta-tool, so it is not listed at all
+            pinnedTools = (await getPinnedSmartRoutingTools(group)).filter((tool) => !SMART_ROUTING_META_TOOL_NAMES.has(tool.name));
+        }
+        catch (error) {
+            // Pins are an optimisation: failing to resolve them must not cost the meta-tools
+            logger.warn(`Failed to list pinned tools for ${group}; returning meta-tools only`, error);
+        }
+        return pinnedTools.length > 0
+            ? { tools: [...smartRoutingTools.tools, ...pinnedTools] }
+            : smartRoutingTools;
+    }
+    const { filteredServerInfos, serverConfigsByName } = await getFilteredServerInfosForGroup(group);
+    const appsRouteContext = await getMcpAppsRouteContext(sessionId, group);
     return {
-        tools: allTools,
+        tools: await listGroupTools(group, filteredServerInfos, serverConfigsByName, appsRouteContext),
     };
 };
 const handleCallToolRequestImpl = async (request, extra) => {
@@ -2946,7 +3102,7 @@ const handleCallToolRequestImpl = async (request, extra) => {
     ].find((id) => typeof id === 'string' && id.length > 0 && !isSyntheticSessionFallback(id));
     // Extract group and key info from request context (set by SSE/HTTP handlers)
     // Fallback to extra for backward compatibility (e.g., direct API calls)
-    const group = requestContextService.getGroupContext() || extra?.group || getGroup(sessionId) || undefined;
+    const group = getMcpRequestGroup(extra);
     const username = requestContextService.getUsernameContext() ||
         extra?.username ||
         (requestContextService.getKeyKindContext() === 'system' ? 'system' : undefined) ||
@@ -2957,6 +3113,13 @@ const handleCallToolRequestImpl = async (request, extra) => {
     const sourceIp = requestContextService.getRequestContext()?.remoteAddress || undefined;
     let hostedReservation = null;
     let releaseOnDemandToolCall;
+    let clientStateLease;
+    const getToolStateId = (info, legacyId) => {
+        if (!requestContextService.getRequestContext()?.stateless)
+            return legacyId;
+        clientStateLease ?? (clientStateLease = acquireClientState(info));
+        return clientStateLease.id;
+    };
     const reserveHostedIfNeeded = async (serverName, toolName) => {
         const hostedAuth = requestContextService.getHostedAuthContext();
         assertHostedToolAllowed(hostedAuth, serverName, toolName);
@@ -2977,12 +3140,12 @@ const handleCallToolRequestImpl = async (request, extra) => {
         // Special handling for smart routing tools
         if (request.params.name === 'search_tools') {
             const { query, limit = 10 } = request.params.arguments || {};
-            return await handleSearchToolsRequest(query, limit, sessionId);
+            return await handleSearchToolsRequest(query, limit, sessionId, group);
         }
         // Special handling for describe_tool (progressive disclosure mode)
         if (request.params.name === 'describe_tool') {
             const { toolName } = request.params.arguments || {};
-            return await handleDescribeToolRequest(toolName, sessionId);
+            return await handleDescribeToolRequest(toolName, sessionId, group);
         }
         // Special handling for call_tool
         if (request.params.name === 'call_tool') {
@@ -3080,8 +3243,14 @@ const handleCallToolRequestImpl = async (request, extra) => {
                         }
                     }
                 }
+                const stateId = targetServerInfo.config?.openapi?.cookieSession
+                    ? getToolStateId(targetServerInfo, cookieSessionId)
+                    : cookieSessionId;
+                if (targetServerInfo.config?.openapi?.cookieSession && !stateId) {
+                    throw new Error(`OpenAPI server '${targetServerInfo.name}' requires cookie-session state and is not yet available on stateless MCP requests`);
+                }
                 await reserveHostedIfNeeded(targetServerInfo.name, cleanToolName);
-                const result = await openApiClient.callTool(cleanToolName, finalArgs, passthroughHeaders, false, cookieSessionId);
+                const result = await openApiClient.callTool(cleanToolName, finalArgs, passthroughHeaders, false, stateId);
                 await settleHostedIfNeeded({
                     success: true,
                     requestContent: finalArgs,
@@ -3125,10 +3294,17 @@ const handleCallToolRequestImpl = async (request, extra) => {
             // For servers with perSessionClient: true, use a per-session dedicated client
             let isolatedCtx;
             if (targetServerInfo.config?.perSessionClient &&
-                !hasCredentialTemplate(targetServerInfo.config) &&
-                sessionId) {
-                const isolated = await getOrCreateIsolatedClient(sessionId, targetServerInfo);
-                isolatedCtx = { sessionId, client: isolated.client, transport: isolated.transport };
+                !hasCredentialTemplate(targetServerInfo.config)) {
+                const stateId = getToolStateId(targetServerInfo, sessionId);
+                if (!stateId) {
+                    throw new Error(`Server '${targetServerInfo.name}' requires per-session client isolation and is not yet available on stateless MCP requests`);
+                }
+                const isolated = await getOrCreateIsolatedClient(stateId, targetServerInfo);
+                isolatedCtx = {
+                    sessionId: stateId,
+                    client: isolated.client,
+                    transport: isolated.transport,
+                };
             }
             else if (!targetServerInfo.client) {
                 throw new Error(`Client not found for server: ${targetServerInfo.name}`);
@@ -3246,8 +3422,14 @@ const handleCallToolRequestImpl = async (request, extra) => {
                 }
             }
             const finalArgs = request.params.arguments || {};
+            const stateId = serverInfo.config?.openapi?.cookieSession
+                ? getToolStateId(serverInfo, cookieSessionId)
+                : cookieSessionId;
+            if (serverInfo.config?.openapi?.cookieSession && !stateId) {
+                throw new Error(`OpenAPI server '${serverInfo.name}' requires cookie-session state and is not yet available on stateless MCP requests`);
+            }
             await reserveHostedIfNeeded(serverInfo.name, cleanToolName);
-            const result = await openApiClient.callTool(cleanToolName, finalArgs, passthroughHeaders, false, cookieSessionId);
+            const result = await openApiClient.callTool(cleanToolName, finalArgs, passthroughHeaders, false, stateId);
             await settleHostedIfNeeded({
                 success: true,
                 requestContent: finalArgs,
@@ -3290,11 +3472,13 @@ const handleCallToolRequestImpl = async (request, extra) => {
         // Handle MCP servers
         // For servers with perSessionClient: true, use a per-session dedicated client
         let isolatedCtx;
-        if (serverInfo.config?.perSessionClient &&
-            !hasCredentialTemplate(serverInfo.config) &&
-            sessionId) {
-            const isolated = await getOrCreateIsolatedClient(sessionId, serverInfo);
-            isolatedCtx = { sessionId, client: isolated.client, transport: isolated.transport };
+        if (serverInfo.config?.perSessionClient && !hasCredentialTemplate(serverInfo.config)) {
+            const stateId = getToolStateId(serverInfo, sessionId);
+            if (!stateId) {
+                throw new Error(`Server '${serverInfo.name}' requires per-session client isolation and is not yet available on stateless MCP requests`);
+            }
+            const isolated = await getOrCreateIsolatedClient(stateId, serverInfo);
+            isolatedCtx = { sessionId: stateId, client: isolated.client, transport: isolated.transport };
         }
         else if (!serverInfo.client) {
             throw new Error(`Client not found for server: ${serverInfo.name}`);
@@ -3386,14 +3570,14 @@ const handleCallToolRequestImpl = async (request, extra) => {
         };
     }
     finally {
+        clientStateLease?.release();
         releaseOnDemandToolCall?.();
     }
 };
 const handleGetPromptRequestImpl = async (request, extra) => {
     try {
         const { name, arguments: promptArgs } = request.params;
-        const sessionId = extra?.sessionId || '';
-        const group = extra?.group || getGroup(sessionId) || undefined;
+        const group = getMcpRequestGroup(extra);
         // Check built-in prompts first
         const builtinPrompt = await getBuiltinPromptDao().findByName(name);
         if (builtinPrompt && builtinPrompt.enabled !== false) {
@@ -3479,8 +3663,7 @@ const handleGetPromptRequestImpl = async (request, extra) => {
     }
 };
 const handleListPromptsRequestImpl = async (_, extra) => {
-    const sessionId = extra.sessionId || '';
-    const group = getGroup(sessionId);
+    const group = getMcpRequestGroup(extra);
     const lookupGroup = getGroupLookupName(group);
     logger.log(`Handling ListPromptsRequest for group: ${group}`);
     // Start with built-in prompts (only enabled ones)
@@ -3524,7 +3707,7 @@ const handleListPromptsRequestImpl = async (_, extra) => {
 };
 const handleListResourcesRequestImpl = async (_, extra) => {
     const sessionId = extra.sessionId || '';
-    const group = getGroup(sessionId);
+    const group = getMcpRequestGroup(extra);
     const lookupGroup = getGroupLookupName(group);
     logger.log(`Handling ListResourcesRequest for group: ${group}`);
     const appsRouteContext = await getMcpAppsRouteContext(sessionId, group);
@@ -3569,7 +3752,7 @@ const handleListResourcesRequestImpl = async (_, extra) => {
 };
 const handleListResourceTemplatesRequestImpl = async (_, extra) => {
     const sessionId = extra.sessionId || '';
-    const group = getGroup(sessionId);
+    const group = getMcpRequestGroup(extra);
     const lookupGroup = getGroupLookupName(group);
     logger.log(`Handling ListResourceTemplatesRequest for group: ${group}`);
     const appsRouteContext = await getMcpAppsRouteContext(sessionId, group);
@@ -3594,7 +3777,7 @@ const handleReadResourceRequestImpl = async (request, extra) => {
     try {
         const { uri } = request.params;
         const sessionId = extra.sessionId || '';
-        const group = getGroup(sessionId);
+        const group = getMcpRequestGroup(extra);
         const lookupGroup = getGroupLookupName(group);
         const appsRouteContext = await getMcpAppsRouteContext(sessionId, group);
         // Check built-in resources first
@@ -3687,7 +3870,9 @@ const handleReadResourceRequestImpl = async (request, extra) => {
         };
     }
 };
-// Personal runtimes never enter serverInfos, config exports, or shared embedding caches.
+// Personal runtimes never enter serverInfos or config exports. Their tool list
+// is added to the rows under the server name, the index the reindex endpoint
+// rebuilds from every binding.
 const createPrincipalRuntime = async (name, resolvedConfig) => {
     const info = {
         name,
@@ -3769,6 +3954,12 @@ const createPrincipalRuntime = async (name, resolvedConfig) => {
             };
         }
         info.status = 'connected';
+        // A credential server never connects globally, so this is the only place
+        // its tools are seen outside a reindex. One user's list is not the whole
+        // server's, so this only adds and refreshes rows; unchanged ones are skipped.
+        syncCredentialServerToolEmbeddings(name, info.tools, { partial: true }).catch(() => {
+            logger.warn(`[EMBED_SYNC_ERROR] Failed to sync tool embeddings for "${name}"`);
+        });
         return info;
     }
     catch (error) {
@@ -3815,10 +4006,7 @@ const withPrincipalServers = (handler, operation) => async (request, extra) => {
         if (builtin && builtin.enabled !== false)
             return handler(request, extra);
     }
-    const group = RequestContextService.getInstance().getGroupContext() ||
-        extra?.group ||
-        getGroup(extra?.sessionId || '') ||
-        undefined;
+    const group = getMcpRequestGroup(extra);
     const { filteredServerInfos: candidates, serverConfigsByName } = await getFilteredServerInfosForGroup(getGroupLookupName(group));
     const requestedName = ['call_tool', 'describe_tool'].includes(request?.params?.name)
         ? request.params.arguments?.toolName