@1mcp/agent 0.16.0 → 0.17.0

package/build/server.js

@@ -4,30 +4,103 @@ import { createTransports } from './transport/transportFactory.js';
 import { ClientManager } from './core/client/clientManager.js';
 import { ServerManager } from './core/server/serverManager.js';
 import { McpConfigManager } from './config/mcpConfigManager.js';
+import { AgentConfigManager } from './core/server/agentConfig.js';
 import configReloadService from './services/configReloadService.js';
+import { McpLoadingManager } from './core/loading/mcpLoadingManager.js';
+import { AsyncLoadingOrchestrator } from './core/capabilities/asyncLoadingOrchestrator.js';
 /**
  * Main function to set up the MCP server
+ * Conditionally uses async or legacy loading based on configuration
  */
 async function setupServer() {
     try {
         const mcpConfig = McpConfigManager.getInstance().getTransportConfig();
+        const agentConfig = AgentConfigManager.getInstance();
+        const asyncLoadingEnabled = agentConfig.isAsyncLoadingEnabled();
         // Create transports from configuration
         const transports = createTransports(mcpConfig);
         logger.info(`Created ${Object.keys(transports).length} transports`);
-        // Create clients for each transport
-        const clientManager = ClientManager.getOrCreateInstance();
-        const clients = await clientManager.createClients(transports);
-        logger.info(`Created ${clients.size} clients`);
-        const serverManager = ServerManager.getOrCreateInstance({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, { capabilities: MCP_SERVER_CAPABILITIES }, clients, transports);
-        // Initialize config reload service at server startup
-        configReloadService.initialize(transports);
-        logger.info('Server setup completed successfully');
-        return serverManager;
+        if (asyncLoadingEnabled) {
+            logger.info('Using async loading mode - HTTP server will start immediately, MCP servers load in background');
+            return setupServerAsync(transports);
+        }
+        else {
+            logger.info('Using legacy synchronous loading mode - waiting for all MCP servers before starting HTTP server');
+            return setupServerSync(transports);
+        }
     }
     catch (error) {
         logger.error(`Failed to set up server: ${error}`);
         throw error;
     }
 }
-export { setupServer };
+/**
+ * Set up server with async loading (new mode)
+ * HTTP server starts immediately, MCP servers load in background
+ */
+async function setupServerAsync(transports) {
+    // Initialize client manager without connecting (for async loading)
+    const clientManager = ClientManager.getOrCreateInstance();
+    const clients = clientManager.initializeClientsAsync(transports);
+    logger.info(`Initialized storage for ${Object.keys(transports).length} MCP servers`);
+    // Create server manager with empty clients initially
+    const serverManager = ServerManager.getOrCreateInstance({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, { capabilities: MCP_SERVER_CAPABILITIES }, clients, transports);
+    // Initialize config reload service
+    configReloadService.initialize(transports);
+    // Create loading manager for async MCP server initialization
+    const loadingManager = new McpLoadingManager(clientManager);
+    // Create async loading orchestrator for capability tracking and notifications
+    const asyncOrchestrator = new AsyncLoadingOrchestrator(clients, serverManager, loadingManager);
+    asyncOrchestrator.initialize();
+    // Start async loading (non-blocking)
+    const loadingPromise = loadingManager
+        .startAsyncLoading(transports)
+        .then(() => {
+        logger.info('All MCP servers finished loading (successfully or failed)');
+    })
+        .catch((error) => {
+        logger.error('MCP loading process encountered an error:', error);
+    });
+    logger.info('Async server setup completed - HTTP server ready, MCP servers loading in background');
+    return {
+        serverManager,
+        loadingManager,
+        loadingPromise,
+        asyncOrchestrator,
+    };
+}
+/**
+ * Set up server with legacy synchronous loading
+ * Waits for all MCP servers to load before returning
+ */
+async function setupServerSync(transports) {
+    // Use the standard synchronous client creation
+    const clientManager = ClientManager.getOrCreateInstance();
+    const clients = await clientManager.createClients(transports);
+    logger.info(`Connected to ${clients.size} MCP servers synchronously`);
+    // Create server manager with connected clients
+    const serverManager = ServerManager.getOrCreateInstance({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, { capabilities: MCP_SERVER_CAPABILITIES }, clients, transports);
+    // Initialize config reload service
+    configReloadService.initialize(transports);
+    // Create a dummy loading manager for compatibility
+    const loadingManager = new McpLoadingManager(clientManager);
+    const loadingPromise = Promise.resolve(); // Already loaded
+    logger.info('Synchronous server setup completed - all MCP servers connected');
+    return {
+        serverManager,
+        loadingManager,
+        loadingPromise,
+    };
+}
+/**
+ * Legacy function for backward compatibility
+ * @deprecated Use setupServer() which returns ServerSetupResult
+ */
+async function setupServerLegacy() {
+    const result = await setupServer();
+    // Wait for loading to complete for legacy behavior
+    await result.loadingPromise;
+    return result.serverManager;
+}
+export { setupServer, setupServerLegacy };
 //# sourceMappingURL=server.js.map

package/build/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,mBAAmB,MAAM,mCAAmC,CAAC;AAEpE;;GAEG;AACH,KAAK,UAAU,WAAW;IACxB,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,gBAAgB,CAAC,WAAW,EAAE,CAAC,kBAAkB,EAAE,CAAC;QACtE,uCAAuC;QACvC,MAAM,UAAU,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,aAAa,CAAC,CAAC;QAEpE,oCAAoC;QACpC,MAAM,aAAa,GAAG,aAAa,CAAC,mBAAmB,EAAE,CAAC;QAC1D,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QAC9D,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,IAAI,UAAU,CAAC,CAAC;QAE/C,MAAM,aAAa,GAAG,aAAa,CAAC,mBAAmB,CACrD,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,EAAE,EACtD,EAAE,YAAY,EAAE,uBAAuB,EAAE,EACzC,OAAO,EACP,UAAU,CACX,CAAC;QAEF,qDAAqD;QACrD,mBAAmB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAE3C,MAAM,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;QACnD,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,4BAA4B,KAAK,EAAE,CAAC,CAAC;QAClD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC9F,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,mBAAmB,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAC;AAgB3F;;;GAGG;AACH,KAAK,UAAU,WAAW;IACxB,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,gBAAgB,CAAC,WAAW,EAAE,CAAC,kBAAkB,EAAE,CAAC;QACtE,MAAM,WAAW,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC;QACrD,MAAM,mBAAmB,GAAG,WAAW,CAAC,qBAAqB,EAAE,CAAC;QAEhE,uCAAuC;QACvC,MAAM,UAAU,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,aAAa,CAAC,CAAC;QAEpE,IAAI,mBAAmB,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,+FAA+F,CAAC,CAAC;YAC7G,OAAO,gBAAgB,CAAC,UAAU,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,iGAAiG,CAAC,CAAC;YAC/G,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,4BAA4B,KAAK,EAAE,CAAC,CAAC;QAClD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,gBAAgB,CAAC,UAA+B;IAC7D,mEAAmE;IACnE,MAAM,aAAa,GAAG,aAAa,CAAC,mBAAmB,EAAE,CAAC;IAC1D,MAAM,OAAO,GAAG,aAAa,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC;IACjE,MAAM,CAAC,IAAI,CAAC,2BAA2B,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,cAAc,CAAC,CAAC;IAErF,qDAAqD;IACrD,MAAM,aAAa,GAAG,aAAa,CAAC,mBAAmB,CACrD,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,EAAE,EACtD,EAAE,YAAY,EAAE,uBAAuB,EAAE,EACzC,OAAO,EACP,UAAU,CACX,CAAC;IAEF,mCAAmC;IACnC,mBAAmB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAE3C,6DAA6D;IAC7D,MAAM,cAAc,GAAG,IAAI,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAE5D,8EAA8E;IAC9E,MAAM,iBAAiB,GAAG,IAAI,wBAAwB,CAAC,OAAO,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC;IAC/F,iBAAiB,CAAC,UAAU,EAAE,CAAC;IAE/B,qCAAqC;IACrC,MAAM,cAAc,GAAG,cAAc;SAClC,iBAAiB,CAAC,UAAU,CAAC;SAC7B,IAAI,CAAC,GAAG,EAAE;QACT,MAAM,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;IAC3E,CAAC,CAAC;SACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACf,MAAM,CAAC,KAAK,CAAC,2CAA2C,EAAE,KAAK,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;IAEL,MAAM,CAAC,IAAI,CAAC,qFAAqF,CAAC,CAAC;IAEnG,OAAO;QACL,aAAa;QACb,cAAc;QACd,cAAc;QACd,iBAAiB;KAClB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,eAAe,CAAC,UAA+B;IAC5D,+CAA+C;IAC/C,MAAM,aAAa,GAAG,aAAa,CAAC,mBAAmB,EAAE,CAAC;IAC1D,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAC9D,MAAM,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,IAAI,4BAA4B,CAAC,CAAC;IAEtE,+CAA+C;IAC/C,MAAM,aAAa,GAAG,aAAa,CAAC,mBAAmB,CACrD,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,EAAE,EACtD,EAAE,YAAY,EAAE,uBAAuB,EAAE,EACzC,OAAO,EACP,UAAU,CACX,CAAC;IAEF,mCAAmC;IACnC,mBAAmB,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAE3C,mDAAmD;IACnD,MAAM,cAAc,GAAG,IAAI,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC5D,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,iBAAiB;IAE3D,MAAM,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAE9E,OAAO;QACL,aAAa;QACb,cAAc;QACd,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,iBAAiB;IAC9B,MAAM,MAAM,GAAG,MAAM,WAAW,EAAE,CAAC;IACnC,mDAAmD;IACnD,MAAM,MAAM,CAAC,cAAc,CAAC;IAC5B,OAAO,MAAM,CAAC,aAAa,CAAC;AAC9B,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,CAAC"}

package/build/transport/http/middlewares/mcpAvailabilityMiddleware.d.ts

@@ -0,0 +1,79 @@
+import { Request, Response, NextFunction } from 'express';
+import { McpLoadingManager } from '../../../core/loading/mcpLoadingManager.js';
+/**
+ * Extended request interface to include MCP loading information
+ */
+export interface McpRequest extends Request {
+    mcpAvailability?: {
+        availableServers: string[];
+        unavailableServers: string[];
+        loadingServers: string[];
+        oauthRequiredServers: string[];
+        hasPartialAvailability: boolean;
+        allServersReady: boolean;
+        requestedTags?: string[];
+        totalServersBeforeFiltering?: number;
+    };
+}
+/**
+ * Middleware options for MCP availability checking
+ */
+export interface McpAvailabilityOptions {
+    /** Whether to allow requests when some servers are still loading */
+    allowPartialAvailability?: boolean;
+    /** Whether to include OAuth-required servers as available */
+    includeOAuthServers?: boolean;
+    /** Custom error message for unavailable servers */
+    unavailableMessage?: string;
+    /** Custom error message for loading servers */
+    loadingMessage?: string;
+}
+/**
+ * Creates middleware that checks MCP server availability before processing requests
+ *
+ * This middleware examines the loading state of MCP servers and provides different
+ * behaviors based on server availability and configuration options.
+ *
+ * @param loadingManager - The MCP loading manager instance
+ * @param options - Configuration options for availability checking
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * const availabilityMiddleware = createMcpAvailabilityMiddleware(loadingManager, {
+ *   allowPartialAvailability: true,
+ *   includeOAuthServers: false,
+ * });
+ *
+ * router.post('/mcp', availabilityMiddleware, (req, res) => {
+ *   // Handle MCP request with availability info in req.mcpAvailability
+ * });
+ * ```
+ */
+export declare function createMcpAvailabilityMiddleware(loadingManager?: McpLoadingManager, options?: McpAvailabilityOptions): (req: McpRequest, res: Response, next: NextFunction) => void;
+/**
+ * Utility function to get MCP availability info from request
+ */
+export declare function getMcpAvailability(req: Request): {
+    availableServers: string[];
+    unavailableServers: string[];
+    loadingServers: string[];
+    oauthRequiredServers: string[];
+    hasPartialAvailability: boolean;
+    allServersReady: boolean;
+    requestedTags?: string[];
+    totalServersBeforeFiltering?: number;
+} | undefined;
+/**
+ * Utility function to check if all MCP servers are ready
+ */
+export declare function areAllMcpServersReady(req: Request): boolean;
+/**
+ * Utility function to get list of available MCP servers
+ */
+export declare function getAvailableMcpServers(req: Request): string[];
+/**
+ * Utility function to get list of loading MCP servers
+ */
+export declare function getLoadingMcpServers(req: Request): string[];
+//# sourceMappingURL=mcpAvailabilityMiddleware.d.ts.map

package/build/transport/http/middlewares/mcpAvailabilityMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpAvailabilityMiddleware.d.ts","sourceRoot":"","sources":["../../../../src/transport/http/middlewares/mcpAvailabilityMiddleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AAK/E;;GAEG;AACH,MAAM,WAAW,UAAW,SAAQ,OAAO;IACzC,eAAe,CAAC,EAAE;QAChB,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAC3B,kBAAkB,EAAE,MAAM,EAAE,CAAC;QAC7B,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,oBAAoB,EAAE,MAAM,EAAE,CAAC;QAC/B,sBAAsB,EAAE,OAAO,CAAC;QAChC,eAAe,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,2BAA2B,CAAC,EAAE,MAAM,CAAC;KACtC,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,6DAA6D;IAC7D,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAYD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,+BAA+B,CAC7C,cAAc,CAAC,EAAE,iBAAiB,EAClC,OAAO,GAAE,sBAA2B,IAI5B,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UA4M3D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO;sBAhRzB,MAAM,EAAE;wBACN,MAAM,EAAE;oBACZ,MAAM,EAAE;0BACF,MAAM,EAAE;4BACN,OAAO;qBACd,OAAO;oBACR,MAAM,EAAE;kCACM,MAAM;cA2QvC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAG3D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAG7D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAG3D"}

package/build/transport/http/middlewares/mcpAvailabilityMiddleware.js

@@ -0,0 +1,243 @@
+import logger from '../../../logger/logger.js';
+import { LoadingState } from '../../../core/loading/loadingStateTracker.js';
+import { getValidatedTags } from './scopeAuthMiddleware.js';
+import { McpConfigManager } from '../../../config/mcpConfigManager.js';
+/**
+ * Default options for MCP availability middleware
+ */
+const DEFAULT_OPTIONS = {
+    allowPartialAvailability: true,
+    includeOAuthServers: false,
+    unavailableMessage: 'Some requested MCP servers are not available',
+    loadingMessage: 'Some requested MCP servers are still loading',
+};
+/**
+ * Creates middleware that checks MCP server availability before processing requests
+ *
+ * This middleware examines the loading state of MCP servers and provides different
+ * behaviors based on server availability and configuration options.
+ *
+ * @param loadingManager - The MCP loading manager instance
+ * @param options - Configuration options for availability checking
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * const availabilityMiddleware = createMcpAvailabilityMiddleware(loadingManager, {
+ *   allowPartialAvailability: true,
+ *   includeOAuthServers: false,
+ * });
+ *
+ * router.post('/mcp', availabilityMiddleware, (req, res) => {
+ *   // Handle MCP request with availability info in req.mcpAvailability
+ * });
+ * ```
+ */
+export function createMcpAvailabilityMiddleware(loadingManager, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    return (req, res, next) => {
+        try {
+            // If no loading manager, assume all servers are available (legacy mode)
+            if (!loadingManager) {
+                logger.debug('No loading manager - assuming all servers available');
+                next();
+                return;
+            }
+            // Get requested tags from scope auth middleware
+            const requestedTags = getValidatedTags(res);
+            // If no specific tags requested, get all servers
+            const stateTracker = loadingManager.getStateTracker();
+            const allStates = stateTracker.getAllServerStates();
+            // Filter servers based on requested tags
+            // Tags are used to control which MCP servers are available for requests.
+            // When tags are specified, only servers that have ALL the requested tags will be included.
+            const allServers = Array.from(allStates.keys());
+            let relevantServers;
+            if (requestedTags && requestedTags.length > 0) {
+                // Get server configurations to access tags
+                const configManager = McpConfigManager.getInstance();
+                const transportConfig = configManager.getTransportConfig();
+                // Filter servers that have ALL requested tags
+                // This implements the "AND" logic: servers must have every requested tag
+                relevantServers = allServers.filter((serverName) => {
+                    const serverConfig = transportConfig[serverName];
+                    if (!serverConfig || !serverConfig.tags) {
+                        // Server has no tags, so it doesn't match any tag request
+                        return false;
+                    }
+                    // Check if server has ALL requested tags (case-insensitive matching)
+                    const serverTags = serverConfig.tags.map((tag) => tag.toLowerCase());
+                    const requestedTagsLower = requestedTags.map((tag) => tag.toLowerCase());
+                    return requestedTagsLower.every((requestedTag) => serverTags.includes(requestedTag));
+                });
+                logger.debug(`Filtered ${relevantServers.length}/${allServers.length} servers ` + `with tags: ${requestedTags.join(', ')}`);
+            }
+            else {
+                relevantServers = allServers;
+                logger.debug(`Checking availability for all ${relevantServers.length} servers`);
+            }
+            // Categorize servers by state
+            const availableServers = [];
+            const unavailableServers = [];
+            const loadingServers = [];
+            const oauthRequiredServers = [];
+            for (const serverName of relevantServers) {
+                const serverInfo = stateTracker.getServerState(serverName);
+                if (!serverInfo) {
+                    unavailableServers.push(serverName);
+                    continue;
+                }
+                switch (serverInfo.state) {
+                    case LoadingState.Ready:
+                        availableServers.push(serverName);
+                        break;
+                    case LoadingState.Loading:
+                    case LoadingState.Pending:
+                        loadingServers.push(serverName);
+                        break;
+                    case LoadingState.AwaitingOAuth:
+                        if (opts.includeOAuthServers) {
+                            availableServers.push(serverName);
+                        }
+                        else {
+                            oauthRequiredServers.push(serverName);
+                        }
+                        break;
+                    case LoadingState.Failed:
+                    case LoadingState.Cancelled:
+                    default:
+                        unavailableServers.push(serverName);
+                        break;
+                }
+            }
+            // Calculate availability metrics
+            const hasPartialAvailability = availableServers.length > 0;
+            const allServersReady = relevantServers.length > 0 && availableServers.length === relevantServers.length;
+            // Add availability info to request
+            req.mcpAvailability = {
+                availableServers,
+                unavailableServers,
+                loadingServers,
+                oauthRequiredServers,
+                hasPartialAvailability,
+                allServersReady,
+                requestedTags: requestedTags && requestedTags.length > 0 ? requestedTags : undefined,
+                totalServersBeforeFiltering: requestedTags && requestedTags.length > 0 ? allServers.length : undefined,
+            };
+            // Log availability status
+            const tagInfo = requestedTags && requestedTags.length > 0
+                ? ` (filtered by tags: ${requestedTags.join(', ')}, ${allServers.length} total)`
+                : '';
+            logger.debug(`MCP Availability: ${availableServers.length}/${relevantServers.length} ready, ` +
+                `${loadingServers.length} loading, ${unavailableServers.length} failed, ` +
+                `${oauthRequiredServers.length} OAuth required${tagInfo}`);
+            // Decide whether to proceed based on availability
+            if (relevantServers.length === 0) {
+                // No servers configured - proceed normally
+                next();
+                return;
+            }
+            if (allServersReady) {
+                // All servers ready - proceed normally
+                next();
+                return;
+            }
+            if (!hasPartialAvailability) {
+                // No servers available - return error
+                logger.warn('No MCP servers available for request');
+                res.status(503).json({
+                    error: 'service_unavailable',
+                    message: 'No MCP servers are currently available',
+                    details: {
+                        total: relevantServers.length,
+                        available: availableServers.length,
+                        loading: loadingServers.length,
+                        failed: unavailableServers.length,
+                        oauthRequired: oauthRequiredServers.length,
+                    },
+                    loading: {
+                        isComplete: stateTracker.isLoadingComplete(),
+                        summary: loadingManager.getSummary(),
+                    },
+                    timestamp: new Date().toISOString(),
+                });
+                return;
+            }
+            if (opts.allowPartialAvailability) {
+                // Some servers available - proceed with warning
+                logger.info(`Proceeding with partial MCP availability: ${availableServers.length}/${relevantServers.length} servers ready`);
+                // Add warning headers
+                res.setHeader('X-MCP-Partial-Availability', 'true');
+                res.setHeader('X-MCP-Available-Count', availableServers.length.toString());
+                res.setHeader('X-MCP-Total-Count', relevantServers.length.toString());
+                if (loadingServers.length > 0) {
+                    res.setHeader('X-MCP-Loading-Count', loadingServers.length.toString());
+                }
+                next();
+                return;
+            }
+            else {
+                // Partial availability not allowed - return error
+                logger.warn('Partial MCP availability not allowed - blocking request');
+                const primaryReason = loadingServers.length > 0 ? 'loading' : 'unavailable';
+                const message = primaryReason === 'loading' ? opts.loadingMessage : opts.unavailableMessage;
+                res.status(primaryReason === 'loading' ? 202 : 503).json({
+                    error: primaryReason === 'loading' ? 'servers_loading' : 'servers_unavailable',
+                    message,
+                    details: {
+                        total: relevantServers.length,
+                        available: availableServers.length,
+                        loading: loadingServers.length,
+                        failed: unavailableServers.length,
+                        oauthRequired: oauthRequiredServers.length,
+                        availableList: availableServers,
+                        loadingList: loadingServers,
+                        failedList: unavailableServers,
+                        oauthRequiredList: oauthRequiredServers,
+                    },
+                    loading: {
+                        isComplete: stateTracker.isLoadingComplete(),
+                        summary: loadingManager.getSummary(),
+                    },
+                    retryAfter: primaryReason === 'loading' ? 30 : undefined, // Suggest retry in 30 seconds for loading
+                    timestamp: new Date().toISOString(),
+                });
+                return;
+            }
+        }
+        catch (error) {
+            logger.error('MCP availability check failed:', error);
+            // On error, proceed normally to avoid blocking requests
+            // This ensures the system remains functional even if availability checking fails
+            next();
+        }
+    };
+}
+/**
+ * Utility function to get MCP availability info from request
+ */
+export function getMcpAvailability(req) {
+    return req.mcpAvailability;
+}
+/**
+ * Utility function to check if all MCP servers are ready
+ */
+export function areAllMcpServersReady(req) {
+    const availability = getMcpAvailability(req);
+    return availability?.allServersReady ?? true; // Assume ready if no availability info
+}
+/**
+ * Utility function to get list of available MCP servers
+ */
+export function getAvailableMcpServers(req) {
+    const availability = getMcpAvailability(req);
+    return availability?.availableServers ?? [];
+}
+/**
+ * Utility function to get list of loading MCP servers
+ */
+export function getLoadingMcpServers(req) {
+    const availability = getMcpAvailability(req);
+    return availability?.loadingServers ?? [];
+}
+//# sourceMappingURL=mcpAvailabilityMiddleware.js.map

package/build/transport/http/middlewares/mcpAvailabilityMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpAvailabilityMiddleware.js","sourceRoot":"","sources":["../../../../src/transport/http/middlewares/mcpAvailabilityMiddleware.ts"],"names":[],"mappings":"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"}

package/build/transport/http/routes/healthRoutes.d.ts

@@ -1,7 +1,8 @@
 import { Router } from 'express';
+import { McpLoadingManager } from '../../../core/loading/mcpLoadingManager.js';
 /**
  * Creates health check routes
  */
-export declare function createHealthRoutes(): Router;
+export declare function createHealthRoutes(loadingManager?: McpLoadingManager): Router;
 export default createHealthRoutes;
 //# sourceMappingURL=healthRoutes.d.ts.map

package/build/transport/http/routes/healthRoutes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"healthRoutes.d.ts","sourceRoot":"","sources":["../../../../src/transport/http/routes/healthRoutes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqC,MAAM,SAAS,CAAC;AAKpE;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAwH3C;AAGD,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"healthRoutes.d.ts","sourceRoot":"","sources":["../../../../src/transport/http/routes/healthRoutes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqC,MAAM,SAAS,CAAC;AAIpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AAG/E;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAgT7E;AAGD,eAAe,kBAAkB,CAAC"}