@loop_ouroboros/mcp-hub-lite 1.0.2 → 1.1.0

package/dist/server/src/services/hub-tools/instance-matcher.js

@@ -0,0 +1,132 @@
+/**
+ * Instance Matcher Service
+ * Provides intelligent instance selection based on tags and connection status.
+ */
+/**
+ * Calculates the match score between an instance and requested tags.
+ *
+ * The score ranges from 0.0 (no match) to 1.0 (perfect match).
+ * Calculated as the ratio of matching tags to total requested tags.
+ *
+ * @param instance - The service instance to evaluate
+ * @param requestedTags - The tags to match against
+ * @returns Match score between 0.0 and 1.0
+ */
+export function calculateMatchScore(instance, requestedTags) {
+    // If no tags requested, perfect match
+    if (!requestedTags || Object.keys(requestedTags).length === 0) {
+        return 1.0;
+    }
+    const instanceTags = instance.tags || {};
+    const requestedTagKeys = Object.keys(requestedTags);
+    if (requestedTagKeys.length === 0) {
+        return 1.0;
+    }
+    // Count matching tags
+    let matchCount = 0;
+    for (const [key, value] of Object.entries(requestedTags)) {
+        if (instanceTags[key] === value) {
+            matchCount++;
+        }
+    }
+    return matchCount / requestedTagKeys.length;
+}
+/**
+ * Filters instances to only include enabled ones.
+ *
+ * @param instances - Array of instances to filter
+ * @returns Array of enabled instances
+ */
+export function filterEnabledInstances(instances) {
+    return instances.filter((instance) => instance.enabled !== false);
+}
+/**
+ * Sorts instances by connection status (connected first).
+ *
+ * Preserves the original order within each status group.
+ *
+ * @param instances - Array of instances with connection status
+ * @returns Sorted array with connected instances first
+ */
+export function sortByConnectionStatus(instances) {
+    const connected = [];
+    const disconnected = [];
+    for (const instance of instances) {
+        if (instance.connected === true) {
+            connected.push(instance);
+        }
+        else {
+            disconnected.push(instance);
+        }
+    }
+    return [...connected, ...disconnected];
+}
+/**
+ * Selects the best matching instance based on tags and connection status.
+ *
+ * Selection priority:
+ * 1. Only consider enabled instances
+ * 2. Prioritize connected instances over disconnected ones (ALWAYS prefer connected if available)
+ * 3. Among connected instances, select the one with highest tag match score
+ * 4. Among disconnected instances, select the one with highest tag match score
+ * 5. Only return undefined if NO connected instances AND tags requested but no match
+ *
+ * @param instances - Array of instances to choose from
+ * @param requestedTags - Optional tags to match
+ * @returns The best matching instance, or undefined if no suitable instance found
+ */
+export function selectBestMatch(instances, requestedTags) {
+    if (instances.length === 0) {
+        return undefined;
+    }
+    // Filter to only enabled instances
+    const enabledInstances = filterEnabledInstances(instances);
+    if (enabledInstances.length === 0) {
+        return undefined;
+    }
+    // Check if tags are requested
+    const hasRequestedTags = !!(requestedTags && Object.keys(requestedTags).length > 0);
+    // Sort by connection status (connected first)
+    const sortedInstances = sortByConnectionStatus(enabledInstances);
+    // Group by connection status
+    const connectedInstances = sortedInstances.filter((i) => i.connected === true);
+    const disconnectedInstances = sortedInstances.filter((i) => i.connected !== true);
+    // Always prefer connected instances if available, even with 0 tag match
+    if (connectedInstances.length > 0) {
+        // For connected instances, always return the best one (never undefined for connected)
+        return findBestMatchingInstance(connectedInstances, requestedTags, false);
+    }
+    // Only for disconnected instances, return undefined if tags requested but no match
+    if (disconnectedInstances.length > 0) {
+        return findBestMatchingInstance(disconnectedInstances, requestedTags, hasRequestedTags);
+    }
+    return undefined;
+}
+/**
+ * Helper to find the instance with the highest match score.
+ *
+ * @param instances - Array of instances to evaluate
+ * @param requestedTags - Tags to match against
+ * @param hasRequestedTags - Whether tags were explicitly requested
+ * @returns The instance with highest score, or undefined if no match found and tags requested
+ */
+function findBestMatchingInstance(instances, requestedTags, hasRequestedTags) {
+    if (instances.length === 0) {
+        return undefined;
+    }
+    let bestInstance;
+    let bestScore = -1;
+    for (const instance of instances) {
+        const score = calculateMatchScore(instance, requestedTags);
+        if (score > bestScore) {
+            bestScore = score;
+            bestInstance = instance;
+        }
+    }
+    // If tags were requested and best score is 0 (no match), return undefined
+    if (hasRequestedTags && bestScore === 0) {
+        return undefined;
+    }
+    // Otherwise return the best instance (or first instance if all scores equal)
+    return bestInstance || instances[0];
+}

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

@@ -0,0 +1,29 @@
+import type { ServerConfig, ServerInstance } from '../../../shared/models/server.model.js';
+/**
+ * Error thrown when tag-match-unique instance selection fails.
+ * Passes raw data so the error class itself can format the message.
+ */
+export declare class TagMatchUniqueError extends Error {
+    readonly instanceCount: number;
+    readonly requestTags?: Record<string, string> | undefined;
+    readonly availableInstances?: Record<number, Record<string, string>> | undefined;
+    constructor(instanceCount: number, requestTags?: Record<string, string> | undefined, availableInstances?: Record<number, Record<string, string>> | undefined);
+}
+/**
+ * Instance selector for multi-instance servers
+ * Implements three selection strategies: random, round-robin, and tag-match-unique
+ */
+export declare class InstanceSelector {
+    private static roundRobinCounters;
+    /**
+     * Select best instance based on configured strategy
+     */
+    static selectInstance(serverName: string, serverConfig: ServerConfig, requestOptions?: {
+        sessionId?: string;
+        tags?: Record<string, string>;
+    }): ServerInstance | undefined;
+    private static selectRandomInstance;
+    private static selectRoundRobinInstance;
+    private static selectTagMatchUniqueInstance;
+}
+//# sourceMappingURL=instance-selector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instance-selector.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/instance-selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGnF;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,aAAa,EAAE,MAAM;aACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;aACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAF3D,aAAa,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAAA,EACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,YAAA;CAmB9E;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAA6B;IAE9D;;OAEG;IACH,MAAM,CAAC,cAAc,CACnB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,YAAY,EAC1B,cAAc,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GACrE,cAAc,GAAG,SAAS;IA+B7B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAKnC,OAAO,CAAC,MAAM,CAAC,wBAAwB;IAUvC,OAAO,CAAC,MAAM,CAAC,4BAA4B;CAiC5C"}

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

@@ -0,0 +1,103 @@
+import { InstanceSelectionStrategy } from '../../models/server.model.js';
+/**
+ * Error thrown when tag-match-unique instance selection fails.
+ * Passes raw data so the error class itself can format the message.
+ */
+export class TagMatchUniqueError extends Error {
+    instanceCount;
+    requestTags;
+    availableInstances;
+    constructor(instanceCount, requestTags, availableInstances) {
+        let message;
+        if (!requestTags) {
+            // Format available instances as index:tags for easy selection
+            const instancesStr = availableInstances
+                ? Object.entries(availableInstances)
+                    .map(([index, tags]) => `${index}:${JSON.stringify(tags)}`)
+                    .join(', ')
+                : '';
+            message = `No tags provided for tag-match-unique strategy with ${instanceCount} instances. Available: [${instancesStr}]. Pass matching tags to select.`;
+        }
+        else if (instanceCount === 0) {
+            message = `No instance found matching tags: ${JSON.stringify(requestTags)}`;
+        }
+        else {
+            message = `Multiple instances match tags: ${JSON.stringify(requestTags)}. Expected unique match.`;
+        }
+        super(message);
+        this.instanceCount = instanceCount;
+        this.requestTags = requestTags;
+        this.availableInstances = availableInstances;
+        this.name = 'TagMatchUniqueError';
+    }
+}
+/**
+ * Instance selector for multi-instance servers
+ * Implements three selection strategies: random, round-robin, and tag-match-unique
+ */
+export class InstanceSelector {
+    static roundRobinCounters = new Map();
+    /**
+     * Select best instance based on configured strategy
+     */
+    static selectInstance(serverName, serverConfig, requestOptions) {
+        const { instances } = serverConfig;
+        const instanceSelectionStrategy = serverConfig.template.instanceSelectionStrategy || InstanceSelectionStrategy.RANDOM;
+        // Filter enabled instances
+        const enabledInstances = instances.filter((instance) => instance.enabled !== false);
+        if (enabledInstances.length === 0) {
+            return undefined;
+        }
+        // Single instance case - return directly
+        if (enabledInstances.length === 1) {
+            return enabledInstances[0];
+        }
+        switch (instanceSelectionStrategy) {
+            case InstanceSelectionStrategy.RANDOM:
+                return this.selectRandomInstance(enabledInstances);
+            case InstanceSelectionStrategy.ROUND_ROBIN:
+                return this.selectRoundRobinInstance(serverName, enabledInstances);
+            case InstanceSelectionStrategy.TAG_MATCH_UNIQUE:
+                return this.selectTagMatchUniqueInstance(enabledInstances, requestOptions?.tags);
+            default:
+                return enabledInstances[0]; // Fallback to first instance
+        }
+    }
+    static selectRandomInstance(instances) {
+        const randomIndex = Math.floor(Math.random() * instances.length);
+        return instances[randomIndex];
+    }
+    static selectRoundRobinInstance(serverName, instances) {
+        const counter = this.roundRobinCounters.get(serverName) || 0;
+        const selectedInstance = instances[counter % instances.length];
+        this.roundRobinCounters.set(serverName, (counter + 1) % instances.length);
+        return selectedInstance;
+    }
+    static selectTagMatchUniqueInstance(instances, requestTags) {
+        // Build available instances map with index:tags format
+        const availableInstances = {};
+        instances.forEach((instance, index) => {
+            availableInstances[index] = instance.tags || {};
+        });
+        if (!requestTags || Object.keys(requestTags).length === 0) {
+            // If no request tags provided, must have exactly one instance to avoid ambiguity
+            if (instances.length === 1) {
+                return instances[0];
+            }
+            else {
+                throw new TagMatchUniqueError(instances.length, undefined, availableInstances);
+            }
+        }
+        const matchingInstances = instances.filter((instance) => {
+            if (!instance.tags)
+                return false;
+            // Check if all request tags match instance tags
+            return Object.entries(requestTags).every(([key, value]) => instance.tags[key] === value);
+        });
+        // Must have exactly one matching instance
+        if (matchingInstances.length !== 1) {
+            throw new TagMatchUniqueError(matchingInstances.length, requestTags, availableInstances);
+        }
+        return matchingInstances[0];
+    }
+}

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

@@ -1,5 +1,26 @@
 import type { Resource } from '../../../shared/models/resource.model.js';
 import type { ServerStatus } from '../../../shared/types/common.types.js';
+/**
+ * Clears the Hub to MCP URI mapping.
+ * Should be called before regenerating resources.
+ */
+export declare function clearHubToMcpUriMap(): void;
+/**
+ * URI for the use guide resource.
+ */
+export declare const USE_GUIDE_URI = "hub://use-guide";
+/**
+ * Name of the use guide resource.
+ */
+export declare const USE_GUIDE_NAME = "MCP Hub Lite Use Guide";
+/**
+ * Description of the use guide resource.
+ */
+export declare const USE_GUIDE_DESCRIPTION = "Comprehensive guide to using MCP Hub Lite gateway and its features";
+/**
+ * MIME type for the use guide resource.
+ */
+export declare const USE_GUIDE_MIME_TYPE = "text/markdown";
 /**
  * Server metadata resource content.
  */
@@ -7,10 +28,12 @@ export interface ServerMetadata {
     name: string;
     status: ServerStatus;
     toolsCount: number;
+    tools: Record<string, string>;
     resourcesCount: number;
     tags: Record<string, string>;
     lastHeartbeat: number;
     uptime: number;
+    description: string;
 }
 /**
  * Generates dynamic Hub resources based on currently connected MCP servers.
@@ -56,5 +79,5 @@ export declare function generateDynamicResources(): Resource[];
  * const tools = await readResource('hub://servers/my-mcp-server/tools');
  * ```
  */
-export declare function readResource(uri: string): Promise<ServerMetadata | Resource[]>;
+export declare function readResource(uri: string): Promise<ServerMetadata | Resource[] | string | unknown>;
 //# sourceMappingURL=resource-generator.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"resource-generator.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/resource-generator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGlE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,IAAI,QAAQ,EAAE,CA6BrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,QAAQ,EAAE,CAAC,CAgDpF"}
+{"version":3,"file":"resource-generator.d.ts","sourceRoot":"","sources":["../../../../../src/services/hub-tools/resource-generator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAUlE;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AA6ID;;GAEG;AACH,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,cAAc,2BAA2B,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,qBAAqB,uEACoC,CAAC;AAEvE;;GAEG;AACH,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,IAAI,QAAQ,EAAE,CAgErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,GAAG,QAAQ,EAAE,GAAG,MAAM,GAAG,OAAO,CAAC,CAyGzD"}

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

@@ -1,6 +1,149 @@
+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.
  *
@@ -20,25 +163,58 @@ 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
-        });
+        // 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;
 }
@@ -73,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);
 }