@loop_ouroboros/mcp-hub-lite 1.0.1 → 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,22 +28,21 @@ 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.
  *
  * 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
  *
@@ -59,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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,IAAI,QAAQ,EAAE,CAqDrD;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"}