@loop_ouroboros/mcp-hub-lite 1.0.1 → 1.1.0

package/dist/server/src/services/hub-tools/resource-generator.js

@@ -1,17 +1,157 @@
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import fs from 'fs';
 import { hubManager } from '../hub-manager.service.js';
 import { mcpConnectionManager } from '../mcp-connection-manager.js';
-import { hasValidId, selectBestInstance } from './server-selector.js';
+import { hasValidId, selectBestInstance, getServerDescription } from './server-selector.js';
+/**
+ * Maps Hub URI to original MCP URI for resource forwarding.
+ * Key: Hub URI (e.g., "hub://servers/exa-ai/0/tools/list")
+ * Value: Original MCP URI (e.g., "exa://tools/list")
+ */
+const hubToMcpUriMap = new Map();
+/**
+ * Clears the Hub to MCP URI mapping.
+ * Should be called before regenerating resources.
+ */
+export function clearHubToMcpUriMap() {
+    hubToMcpUriMap.clear();
+}
+/**
+ * Maps an MCP native URI to hub format.
+ * Example: "exa://tools/list" -> "hub://servers/exa-ai/0/tools/list"
+ * Also registers the mapping in hubToMcpUriMap for reverse lookup.
+ *
+ * @param serverName - The server name
+ * @param instanceIndex - The instance index
+ * @param mcpUri - The native MCP URI (e.g., "exa://tools/list")
+ * @returns The hub-formatted URI
+ */
+function getMcpPathFromUri(mcpUri) {
+    return mcpUri.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:(\/\/)?/, '');
+}
+function mapMcpUriToHub(serverName, instanceIndex, mcpUri) {
+    // Remove the scheme prefix (e.g., "exa://" or "exa:")
+    const mcpPath = getMcpPathFromUri(mcpUri);
+    const hubUri = `hub://servers/${serverName}/${instanceIndex}/${mcpPath}`;
+    // Register mapping for reverse lookup in readResource
+    hubToMcpUriMap.set(hubUri, mcpUri);
+    return hubUri;
+}
+/**
+ * Restores a missing Hub -> MCP URI mapping by scanning the current instance resources.
+ */
+function restoreMcpUriMapping(serverName, instanceIndex, _instanceId, mcpPath) {
+    const instanceResources = mcpConnectionManager.getResources(serverName, instanceIndex);
+    for (const resource of instanceResources) {
+        const originalUri = resource.uri;
+        if (typeof originalUri !== 'string') {
+            continue;
+        }
+        if (getMcpPathFromUri(originalUri) !== mcpPath) {
+            continue;
+        }
+        const hubUri = `hub://servers/${serverName}/${instanceIndex}/${mcpPath}`;
+        hubToMcpUriMap.set(hubUri, originalUri);
+        return originalUri;
+    }
+    return null;
+}
+/**
+ * Parses a hub URI and extracts components.
+ * Supports:
+ * - hub://servers/{name} - Server metadata
+ * - hub://servers/{name}/tools - Tools list
+ * - hub://servers/{name}/resources - Resources list
+ * - hub://servers/{name}/{instanceIndex}/{mcpPath} - MCP native resource forwarding
+ *
+ * @param uri - The hub URI to parse
+ * @returns Parsed components, 'unknown' if format is valid but resource type is unknown, or null if format is invalid
+ */
+function parseHubUri(uri) {
+    if (!uri.startsWith('hub://')) {
+        return null;
+    }
+    const parts = uri.replace('hub://', '').split('/');
+    if (parts.length < 2 || parts[0] !== 'servers') {
+        return null;
+    }
+    const serverName = parts[1];
+    // hub://servers/{name} - no instance index
+    if (parts.length === 2) {
+        return { serverName };
+    }
+    // hub://servers/{name}/tools or hub://servers/{name}/resources
+    // These are list requests, not MCP forwarding
+    if (parts.length === 3) {
+        const resourceType = parts[2];
+        if (resourceType === 'tools' || resourceType === 'resources') {
+            return { serverName, listType: resourceType };
+        }
+        // Unknown resource type but valid URI format
+        return 'unknown';
+    }
+    // hub://servers/{name}/{instanceIndex}/{mcpPath}
+    const instanceIndex = parseInt(parts[2], 10);
+    if (isNaN(instanceIndex) || parts.length < 4) {
+        return null;
+    }
+    const mcpPath = parts.slice(3).join('/');
+    return { serverName, instanceIndex, mcpPath };
+}
+/**
+ * Path to the use guide Markdown file.
+ */
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const USE_GUIDE_PATH = join(__dirname, 'use-guide.md');
+/**
+ * Loads the use guide content from the Markdown file.
+ *
+ * @returns {string} Markdown formatted use guide content
+ */
+function loadUseGuideContent() {
+    try {
+        return fs.readFileSync(USE_GUIDE_PATH, 'utf-8');
+    }
+    catch {
+        // Fallback in case the file can't be read
+        return `# MCP Hub Lite Use Guide
+
+## Overview
+
+MCP Hub Lite is a lightweight MCP (Model Context Protocol) gateway that acts as a unified interface between AI assistants and multiple backend MCP servers.
+
+## Note
+
+The complete use guide is currently unavailable. Please check the MCP Hub Lite documentation at https://github.com/your-org/mcp-hub-lite for more information.
+`;
+    }
+}
+/**
+ * URI for the use guide resource.
+ */
+export const USE_GUIDE_URI = 'hub://use-guide';
+/**
+ * Name of the use guide resource.
+ */
+export const USE_GUIDE_NAME = 'MCP Hub Lite Use Guide';
+/**
+ * Description of the use guide resource.
+ */
+export const USE_GUIDE_DESCRIPTION = 'Comprehensive guide to using MCP Hub Lite gateway and its features';
+/**
+ * MIME type for the use guide resource.
+ */
+export const USE_GUIDE_MIME_TYPE = 'text/markdown';
 /**
  * Generates dynamic Hub resources based on currently connected MCP servers.
  *
  * This method creates virtual resources that represent the current state of connected
- * servers, including server metadata, available tools, and server resources. Each
- * resource has a unique URI following the hub://servers/{serverName}[/type] pattern.
+ * servers. Each resource has a unique URI following the hub://servers/{serverName} pattern.
  *
  * The generated resources include:
  * - Server metadata: hub://servers/{serverName}
- * - Tools list: hub://servers/{serverName}/tools
- * - Resources list: hub://servers/{serverName}/resources (only if server has resources)
  *
  * @returns {Resource[]} Array of dynamically generated MCP resource objects
  *
@@ -23,46 +163,57 @@ import { hasValidId, selectBestInstance } from './server-selector.js';
  */
 export function generateDynamicResources() {
     const resources = [];
+    clearHubToMcpUriMap();
+    // Add use-guide resource first - it's always available
+    resources.push({
+        uri: USE_GUIDE_URI,
+        name: USE_GUIDE_NAME,
+        description: USE_GUIDE_DESCRIPTION,
+        mimeType: USE_GUIDE_MIME_TYPE
+        // System resources don't have serverName/serverIndex
+    });
     // Use the same access pattern as tools - directly access manager cache
     const servers = hubManager.getAllServers();
     for (const server of servers) {
-        if (!hasValidId(server) || !server.config.enabled) {
+        if (!hasValidId(server)) {
             continue;
         }
-        const bestInstance = selectBestInstance(server.name);
-        if (!bestInstance || !bestInstance.instance.id) {
+        // Check if any instance is enabled
+        const hasEnabledInstance = server.config.instances.some((i) => i.enabled !== false);
+        if (!hasEnabledInstance) {
             continue;
         }
-        const instanceId = bestInstance.instance.id;
-        // Server metadata resource
-        resources.push({
-            uri: `hub://servers/${server.name}`,
-            name: `Server: ${server.name}`,
-            description: server.config.description || `Connected MCP server: ${server.name}`,
-            mimeType: 'application/json',
-            serverId: instanceId
-        });
-        // Tools resource - only add if server has tools
-        const tools = mcpConnectionManager.getTools(instanceId);
-        if (tools.length > 0) {
-            resources.push({
-                uri: `hub://servers/${server.name}/tools`,
-                name: `Tools: ${server.name}`,
-                description: `${tools.length} tools available from ${server.name}`,
-                mimeType: 'application/json',
-                serverId: instanceId
-            });
-        }
-        // Resources resource - only add if server has resources
-        const serverResources = mcpConnectionManager.getResources(instanceId);
-        if (serverResources.length > 0) {
-            resources.push({
-                uri: `hub://servers/${server.name}/resources`,
-                name: `Resources: ${server.name}`,
-                description: `${serverResources.length} resources available from ${server.name}`,
-                mimeType: 'application/json',
-                serverId: instanceId
-            });
+        // Iterate over all instances to expose each instance's resources
+        for (const instance of server.config.instances) {
+            if (instance.enabled === false) {
+                continue;
+            }
+            const instanceIndex = instance.index;
+            // Server metadata resource (one per server, not per instance)
+            if (instanceIndex === 0) {
+                resources.push({
+                    uri: `hub://servers/${server.name}`,
+                    name: `Server: ${server.name}`,
+                    description: getServerDescription(server.config, server.name),
+                    mimeType: 'application/json',
+                    serverName: server.name,
+                    serverIndex: instanceIndex
+                });
+            }
+            // Get MCP native resources and map to hub format
+            const instanceIdx = instanceIndex ?? 0;
+            const mcpResources = mcpConnectionManager.getResources(server.name, instanceIdx);
+            for (const res of mcpResources) {
+                // Format: Resource: {ServerName} - {Index}: {Native Name}
+                const displayName = `Resource：${server.name} - ${instanceIdx}：${res.name}`;
+                resources.push({
+                    uri: mapMcpUriToHub(server.name, instanceIdx, res.uri),
+                    name: displayName,
+                    description: res.description,
+                    mimeType: res.mimeType
+                    // No serverId - instanceIndex is embedded in the URI
+                });
+            }
         }
     }
     return resources;
@@ -98,44 +249,88 @@ export async function readResource(uri) {
     if (!uri.startsWith('hub://')) {
         throw new Error(`Invalid Hub resource URI: ${uri}. Must start with 'hub://'`);
     }
+    // Check for use-guide resource first
+    if (uri === USE_GUIDE_URI) {
+        return loadUseGuideContent();
+    }
     // Parse URI
-    const uriParts = uri.replace('hub://', '').split('/');
-    if (uriParts.length < 2 || uriParts[0] !== 'servers') {
+    const parsed = parseHubUri(uri);
+    if (!parsed) {
         throw new Error(`Invalid Hub resource URI format: ${uri}`);
     }
-    const serverName = uriParts[1];
-    const resourceType = uriParts[2]; // 'tools', 'resources', or undefined for server metadata
-    // Check if server exists and is connected
-    const serverInfo = selectBestInstance(serverName);
-    if (!serverInfo) {
-        throw new Error(`Server not found or not connected: ${serverName}`);
-    }
-    const instanceId = serverInfo.instance.id;
-    // Return appropriate content based on resource type
-    if (!resourceType) {
-        // Server metadata
-        const serverConfig = hubManager.getServerByName(serverName);
-        const tools = mcpConnectionManager.getTools(instanceId);
-        const resources = mcpConnectionManager.getResources(instanceId);
+    // Handle unknown resource type
+    if (parsed === 'unknown') {
+        const parts = uri.replace('hub://', '').split('/');
+        const resourceType = parts[2];
+        throw new Error(`Unknown resource type: ${resourceType}`);
+    }
+    const { serverName, instanceIndex, mcpPath, listType } = parsed;
+    // Find server config
+    const serverConfig = hubManager.getServerByName(serverName);
+    if (!serverConfig) {
+        throw new Error(`Server not found: ${serverName}`);
+    }
+    // If no instanceIndex, check if this is a list request or metadata request
+    if (instanceIndex === undefined) {
+        // Handle list requests first
+        if (listType) {
+            // Use selectBestInstance to get an instance for the list
+            const serverInfo = selectBestInstance(serverName);
+            if (!serverInfo) {
+                throw new Error(`Server not found or not connected: ${serverName}`);
+            }
+            const instanceIndex = serverInfo.instance.index;
+            if (listType === 'tools') {
+                return mcpConnectionManager.getTools(serverName, instanceIndex);
+            }
+            else {
+                return mcpConnectionManager.getResources(serverName, instanceIndex);
+            }
+        }
+        // Server metadata request - use selectBestInstance to get runtime properties
+        const serverInfo = selectBestInstance(serverName);
+        if (!serverInfo) {
+            throw new Error(`Server not found or not connected: ${serverName}`);
+        }
+        const instanceIndex = serverInfo.instance.index;
+        const tools = mcpConnectionManager.getTools(serverName, instanceIndex);
+        const resources = mcpConnectionManager.getResources(serverName, instanceIndex);
+        // Build tool name to description map
+        const toolsMap = {};
+        for (const tool of tools) {
+            toolsMap[tool.name] = tool.description || '';
+        }
         return {
             name: serverName,
             status: serverInfo.instance.status,
             toolsCount: tools.length,
+            tools: toolsMap,
             resourcesCount: resources.length,
-            tags: serverConfig?.tags || {},
+            tags: serverInfo.instance.tags || {},
             lastHeartbeat: serverInfo.instance.lastHeartbeat,
-            uptime: serverInfo.instance.uptime
+            uptime: serverInfo.instance.uptime,
+            description: getServerDescription(serverConfig, serverName)
         };
     }
-    else if (resourceType === 'tools') {
-        // Tools list
-        return mcpConnectionManager.getTools(instanceId);
+    // MCP native resource forwarding: hub://servers/{name}/{instanceIndex}/{mcpPath}
+    // Find the specific instance by index
+    const targetInstance = serverConfig.instances.find((i) => i.index === instanceIndex && i.enabled !== false);
+    if (!targetInstance) {
+        throw new Error(`Instance ${instanceIndex} not found or not enabled for server: ${serverName}`);
     }
-    else if (resourceType === 'resources') {
-        // Resources list
-        return mcpConnectionManager.getResources(instanceId);
+    const instanceId = targetInstance.id;
+    // If mcpPath is empty, return instance-level info
+    if (!mcpPath) {
+        return mcpConnectionManager.getResources(serverName, instanceIndex);
     }
-    else {
-        throw new Error(`Unknown resource type: ${resourceType}`);
+    // Forward to MCP server for actual resource read
+    // Use the mapping to get the original MCP URI (hub://servers/exa-ai/0/tools/list -> exa://tools/list)
+    let originalMcpUri = hubToMcpUriMap.get(uri);
+    if (!originalMcpUri) {
+        originalMcpUri = restoreMcpUriMapping(serverName, instanceIndex, instanceId, mcpPath);
+    }
+    if (!originalMcpUri) {
+        throw new Error(`MCP URI not found in mapping for: ${uri}`);
     }
+    return mcpConnectionManager.readResource(serverName, instanceIndex, originalMcpUri);
 }

package/dist/server/src/services/hub-tools/server-selector.d.ts

@@ -1,4 +1,16 @@
 import type { RequestOptions, ServerInstanceInfo, ValidServer } from './types.js';
+/**
+ * Gets the description for a server, using a default if none is provided.
+ *
+ * @param serverConfig - Server configuration object (may contain description in template)
+ * @param serverName - Name of the server
+ * @returns The server description or a default one
+ */
+export declare function getServerDescription(serverConfig: {
+    template?: {
+        description?: string;
+    };
+} | undefined, serverName: string): string;
 /**
  * Type guard to validate that a server object has valid name and configuration.
  *
@@ -22,26 +34,24 @@ export declare function hasValidId(server: unknown): server is ValidServer;
  * Selects the best server instance based on server name and request options.
  *
  * This function resolves a server name to its configuration and instance details,
- * handling both single and multiple instance scenarios. Currently, it returns
- * the first instance for multi-instance servers, but the architecture supports
- * future extensions for intelligent instance selection based on session ID,
- * tags, client ID, or load conditions.
+ * handling both single and multiple instance scenarios using configurable instance
+ * selection strategies (random, round-robin, tag-match-unique).
  *
  * The function performs the following steps:
  * 1. Retrieves all instances of the specified server name
  * 2. Returns undefined if no instances are found
  * 3. Gets the server configuration from the hub manager
- * 4. For single-instance servers, returns the instance directly
- * 5. For multi-instance servers, currently returns the first instance (with future extension support)
+ * 4. Uses InstanceSelector to choose the best instance based on configured strategy
+ * 5. Handles errors based on the strictMode parameter
  *
- * Future extensions planned include:
- * - Session-aware instance selection based on sessionId
- * - Tag-based instance selection for matching specific requirements
- * - Load-balancing across multiple instances
- * - Client-specific instance assignment
+ * Supported instance selection strategies:
+ * - random: Randomly selects from enabled instances
+ * - round-robin: Cycles through enabled instances in order
+ * - tag-match-unique: Selects instance that uniquely matches request tags
  *
  * @param {string} serverName - Name of the server to select an instance for
  * @param {RequestOptions} [requestOptions] - Optional request options for instance selection
+ * @param {boolean} [strictMode=true] - Whether to throw errors for tag-match-unique failures (default: true)
  * @returns {{ name: string; config: ServerConfig; instance: ServerInstanceConfig & Record<string, unknown> } | undefined}
  * Server information with configuration and instance details, or undefined if not found
  *
@@ -52,12 +62,15 @@ export declare function hasValidId(server: unknown): server is ValidServer;
  *   console.log(`Selected instance: ${serverInfo.instance.id}`);
  * }
  *
- * // With request options (future extension)
+ * // With request options for tag matching
  * const serverInfoWithOptions = selectBestInstance('my-mcp-server', {
  *   sessionId: 'session-123',
  *   tags: { environment: 'production' }
  * });
+ *
+ * // Non-strict mode for management operations
+ * const serverInfoNonStrict = selectBestInstance('my-mcp-server', undefined, false);
  * ```
  */
-export declare function selectBestInstance(serverName: string, requestOptions?: RequestOptions): ServerInstanceInfo | undefined;
+export declare function selectBestInstance(serverName: string, requestOptions?: RequestOptions, strictMode?: boolean): ServerInstanceInfo | undefined;
 //# sourceMappingURL=server-selector.d.ts.map

package/dist/server/src/services/hub-tools/server-selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-selector.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/server-selector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,WAAW,CAMjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,cAAc,GAC9B,kBAAkB,GAAG,SAAS,CA+ChC"}
+{"version":3,"file":"server-selector.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/server-selector.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAElF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE;IAAE,QAAQ,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,SAAS,EACjE,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,WAAW,CAMjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,cAAc,EAC/B,UAAU,GAAE,OAAc,GACzB,kBAAkB,GAAG,SAAS,CA8ChC"}

package/dist/server/src/services/hub-tools/server-selector.js

@@ -1,4 +1,17 @@
 import { hubManager } from '../hub-manager.service.js';
+import { InstanceSelector, TagMatchUniqueError } from './instance-selector.js';
+import { logger } from '../../utils/logger.js';
+import { LOG_MODULES } from '../../utils/logger/log-modules.js';
+/**
+ * Gets the description for a server, using a default if none is provided.
+ *
+ * @param serverConfig - Server configuration object (may contain description in template)
+ * @param serverName - Name of the server
+ * @returns The server description or a default one
+ */
+export function getServerDescription(serverConfig, serverName) {
+    return serverConfig?.template?.description || `Connected MCP server: ${serverName}`;
+}
 /**
  * Type guard to validate that a server object has valid name and configuration.
  *
@@ -28,26 +41,24 @@ export function hasValidId(server) {
  * Selects the best server instance based on server name and request options.
  *
  * This function resolves a server name to its configuration and instance details,
- * handling both single and multiple instance scenarios. Currently, it returns
- * the first instance for multi-instance servers, but the architecture supports
- * future extensions for intelligent instance selection based on session ID,
- * tags, client ID, or load conditions.
+ * handling both single and multiple instance scenarios using configurable instance
+ * selection strategies (random, round-robin, tag-match-unique).
  *
  * The function performs the following steps:
  * 1. Retrieves all instances of the specified server name
  * 2. Returns undefined if no instances are found
  * 3. Gets the server configuration from the hub manager
- * 4. For single-instance servers, returns the instance directly
- * 5. For multi-instance servers, currently returns the first instance (with future extension support)
+ * 4. Uses InstanceSelector to choose the best instance based on configured strategy
+ * 5. Handles errors based on the strictMode parameter
  *
- * Future extensions planned include:
- * - Session-aware instance selection based on sessionId
- * - Tag-based instance selection for matching specific requirements
- * - Load-balancing across multiple instances
- * - Client-specific instance assignment
+ * Supported instance selection strategies:
+ * - random: Randomly selects from enabled instances
+ * - round-robin: Cycles through enabled instances in order
+ * - tag-match-unique: Selects instance that uniquely matches request tags
  *
  * @param {string} serverName - Name of the server to select an instance for
  * @param {RequestOptions} [requestOptions] - Optional request options for instance selection
+ * @param {boolean} [strictMode=true] - Whether to throw errors for tag-match-unique failures (default: true)
  * @returns {{ name: string; config: ServerConfig; instance: ServerInstanceConfig & Record<string, unknown> } | undefined}
  * Server information with configuration and instance details, or undefined if not found
  *
@@ -58,16 +69,19 @@ export function hasValidId(server) {
  *   console.log(`Selected instance: ${serverInfo.instance.id}`);
  * }
  *
- * // With request options (future extension)
+ * // With request options for tag matching
  * const serverInfoWithOptions = selectBestInstance('my-mcp-server', {
  *   sessionId: 'session-123',
  *   tags: { environment: 'production' }
  * });
+ *
+ * // Non-strict mode for management operations
+ * const serverInfoNonStrict = selectBestInstance('my-mcp-server', undefined, false);
  * ```
  */
-export function selectBestInstance(serverName, requestOptions) {
+export function selectBestInstance(serverName, requestOptions, strictMode = true) {
     // Get all instances of the server
-    const instances = hubManager.getServerInstanceByName(serverName);
+    const instances = hubManager.getServerInstancesByName(serverName);
     if (instances.length === 0) {
         return undefined;
     }
@@ -76,33 +90,26 @@ export function selectBestInstance(serverName, requestOptions) {
     if (!serverConfig) {
         return undefined;
     }
-    // If there's only one instance, return it directly
-    if (instances.length === 1) {
+    try {
+        // Use the new instance selector
+        const selectedInstance = InstanceSelector.selectInstance(serverName, serverConfig, requestOptions);
+        if (!selectedInstance) {
+            return undefined;
+        }
         return {
             name: serverName,
             config: serverConfig,
-            instance: instances[0]
+            instance: selectedInstance
         };
     }
-    // Multi-instance selection logic (for future extension)
-    // Currently simplified implementation: return the first instance
-    // Future extensions could support:
-    // - Selecting specific instance based on sessionId
-    // - Selecting optimal instance based on tags matching
-    // - Selecting dedicated instance based on client ID
-    // - Selecting instance based on load conditions
-    // Although requestOptions is not currently used, it's kept for future extension
-    if (requestOptions?.sessionId) {
-        // In the future, specific instance can be selected based on sessionId
-        // Currently return the first instance temporarily
-    }
-    if (requestOptions?.tags) {
-        // In the future, optimal instance can be selected based on tags matching
-        // Currently return the first instance temporarily
+    catch (error) {
+        // In strict mode, re-throw tag matching errors to maintain correct semantics
+        if (strictMode && error instanceof TagMatchUniqueError) {
+            // Re-throw with server context added to message
+            throw new Error(`[${serverName}] ${error.message}`);
+        }
+        // Handle other errors or non-strict mode gracefully
+        logger.error(`Instance selection failed for server ${serverName}:`, error, LOG_MODULES.SERVER_SELECTOR);
+        return undefined;
     }
-    return {
-        name: serverName,
-        config: serverConfig,
-        instance: instances[0] // Will be extended to intelligent selection logic later
-    };
 }

package/dist/server/src/services/hub-tools/system-tool-definitions.d.ts

@@ -27,12 +27,9 @@ export interface SystemToolDefinition {
  *
  * The method implements all standard system tools:
  * - list-servers: List all connected servers
- * - find-servers: Find servers matching a pattern
- * - list-all-tools-in-server: List tools from a specific server
- * - find-tools-in-server: Find tools in a specific server
+ * - list-tools-in-server: List tools from a specific server
  * - get-tool: Get complete tool schema
  * - call-tool: Call a specific tool from a specific server
- * - find-tools: Find tools across all servers
  *
  * @returns {Array<{ name: string; description: string; inputSchema: JsonSchema; annotations?: ToolAnnotations }>}
  * Array of system tool configurations

package/dist/server/src/services/hub-tools/system-tool-definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-tool-definitions.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/system-tool-definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAY/D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,EAAE,CAwMvD"}
+{"version":3,"file":"system-tool-definitions.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/system-tool-definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAU/D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,EAAE,CA6IvD"}