@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/services/search/search-core.service.d.ts

@@ -0,0 +1,108 @@
+import { SearchResult, SearchOptions } from './types.js';
+/**
+ * Core search service that provides fuzzy search functionality across all available MCP tools.
+ *
+ * This service handles searching through tools from multiple MCP servers with intelligent
+ * scoring, caching, and pagination support. It automatically refreshes its cache when
+ * server configurations change to ensure search results remain up-to-date.
+ *
+ * The search algorithm uses a weighted scoring system that prioritizes:
+ * 1. Exact name matches (highest priority)
+ * 2. Name prefix matches
+ * 3. Name substring matches
+ * 4. Description matches (lower weight)
+ *
+ * Usage scenarios include:
+ * - Tool discovery in the web UI
+ * - Command-line tool search
+ * - API-based tool lookup
+ * - Integration with other services requiring tool search capabilities
+ */
+export declare class SearchCoreService {
+    private cacheService;
+    private scorer;
+    /**
+     * Initializes the search core service and sets up event listeners for cache invalidation.
+     *
+     * Subscribes to server lifecycle events (SERVER_UPDATED, SERVER_ADDED, SERVER_DELETED)
+     * to automatically clear the search cache when server configurations change, ensuring
+     * that search results always reflect the current state of available tools.
+     */
+    constructor();
+    /**
+     * Performs a fuzzy search across all available tools from connected MCP servers.
+     *
+     * This method supports both empty queries (returns all tools) and search queries
+     * with fuzzy matching. Results are scored based on relevance and returned in
+     * descending order of score.
+     *
+     * @param query - The search query string. Empty or whitespace-only queries return all tools.
+     * @param options - Optional search configuration including filters, pagination, and search mode.
+     * @returns A promise that resolves to an array of SearchResult objects containing tools and their relevance scores.
+     *
+     * @example
+     * // Search for tools containing "list"
+     * const results = await searchCoreService.search("list");
+     *
+     * // Get all tools with pagination
+     * const allTools = await searchCoreService.search("", { limit: 20, offset: 0 });
+     *
+     * @remarks
+     * - Results are automatically cached to improve performance on subsequent identical searches
+     * - Cache is invalidated when server configurations change
+     * - Empty queries return all tools with a score of 1
+     * - Non-empty queries perform fuzzy matching with weighted scoring
+     * - Results are automatically sorted by score (highest first) and paginated
+     */
+    search(query: string, options?: Partial<SearchOptions>): Promise<SearchResult[]>;
+    /**
+     * Retrieves all available tools with caching support.
+     *
+     * This method first checks if tools are available in the cache. If cached data exists,
+     * it returns the cached tools immediately. Otherwise, it fetches tools from all connected
+     * MCP servers, applies server-level filtering based on allowedTools configuration,
+     * caches the result, and returns the filtered tools.
+     *
+     * @returns A promise that resolves to an array of Tool objects from all connected servers.
+     *
+     * @remarks
+     * - Tools are filtered based on each server's allowedTools configuration
+     * - If allowedTools is null or undefined, all tools from that server are included
+     * - If allowedTools is an empty array, no tools from that server are included
+     * - Tools are filtered using strict name matching against the allowedTools list
+     */
+    private getToolsWithCache;
+    /**
+     * Applies search filters to the provided tools array.
+     *
+     * Currently, this method serves as a placeholder for future filter implementation.
+     * The comment indicates that serverId and status fields have been removed from the
+     * Tool interface, so alternative filtering methods will be needed in the future.
+     *
+     * @param tools - The array of tools to filter
+     * @param filters - Optional filter criteria from SearchOptions
+     * @returns The filtered array of tools (currently returns input unchanged)
+     *
+     * @todo Implement actual filtering logic once the Tool interface is updated
+     */
+    private applyFilters;
+    /**
+     * Performs fuzzy search on the provided tools array using the configured scorer.
+     *
+     * This method iterates through all tools and calculates a relevance score for each
+     * tool against the search query using the SearchScorer. Only tools with a score
+     * greater than 0 are included in the results.
+     *
+     * @param tools - The array of tools to search through
+     * @param query - The normalized search query string (lowercase, trimmed)
+     * @returns An array of SearchResult objects containing tools with positive scores
+     *
+     * @remarks
+     * - The query parameter should already be normalized (lowercase and trimmed)
+     * - Tools with a score of 0 or less are excluded from results
+     * - Scoring is handled by the SearchScorer instance with weighted field matching
+     */
+    private performFuzzySearch;
+}
+export declare const searchCoreService: SearchCoreService;
+//# sourceMappingURL=search-core.service.d.ts.map

package/dist/server/src/services/search/search-core.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-core.service.d.ts","sourceRoot":"","sources":["../../../../../src/services/search/search-core.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAMzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,MAAM,CAAsB;IAEpC;;;;;;OAMG;;IAoBH;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA8BtF;;;;;;;;;;;;;;;OAeG;YACW,iBAAiB;IAwB/B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kBAAkB;CAgB3B;AAED,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}

package/dist/server/src/services/search/search-core.service.js

@@ -0,0 +1,187 @@
+import { mcpConnectionManager } from '../mcp-connection-manager.js';
+import { hubManager } from '../hub-manager.service.js';
+import { SearchScorer } from './search-scorer.js';
+import { SearchCacheService } from './search-cache.js';
+import { eventBus, EventTypes } from '../event-bus.service.js';
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+/**
+ * Core search service that provides fuzzy search functionality across all available MCP tools.
+ *
+ * This service handles searching through tools from multiple MCP servers with intelligent
+ * scoring, caching, and pagination support. It automatically refreshes its cache when
+ * server configurations change to ensure search results remain up-to-date.
+ *
+ * The search algorithm uses a weighted scoring system that prioritizes:
+ * 1. Exact name matches (highest priority)
+ * 2. Name prefix matches
+ * 3. Name substring matches
+ * 4. Description matches (lower weight)
+ *
+ * Usage scenarios include:
+ * - Tool discovery in the web UI
+ * - Command-line tool search
+ * - API-based tool lookup
+ * - Integration with other services requiring tool search capabilities
+ */
+export class SearchCoreService {
+    cacheService = new SearchCacheService();
+    scorer = new SearchScorer();
+    /**
+     * Initializes the search core service and sets up event listeners for cache invalidation.
+     *
+     * Subscribes to server lifecycle events (SERVER_UPDATED, SERVER_ADDED, SERVER_DELETED)
+     * to automatically clear the search cache when server configurations change, ensuring
+     * that search results always reflect the current state of available tools.
+     */
+    constructor() {
+        // Listen for server update events and clear search cache to ensure results are up-to-date
+        eventBus.subscribe(EventTypes.SERVER_UPDATED, () => {
+            logger.debug('Server updated event received, clearing search cache', LOG_MODULES.SEARCH);
+            this.cacheService.invalidate();
+        });
+        // Listen for server add/delete events and also clear cache
+        eventBus.subscribe(EventTypes.SERVER_ADDED, () => {
+            logger.debug('Server added event received, clearing search cache', LOG_MODULES.SEARCH);
+            this.cacheService.invalidate();
+        });
+        eventBus.subscribe(EventTypes.SERVER_DELETED, () => {
+            logger.debug('Server deleted event received, clearing search cache', LOG_MODULES.SEARCH);
+            this.cacheService.invalidate();
+        });
+    }
+    /**
+     * Performs a fuzzy search across all available tools from connected MCP servers.
+     *
+     * This method supports both empty queries (returns all tools) and search queries
+     * with fuzzy matching. Results are scored based on relevance and returned in
+     * descending order of score.
+     *
+     * @param query - The search query string. Empty or whitespace-only queries return all tools.
+     * @param options - Optional search configuration including filters, pagination, and search mode.
+     * @returns A promise that resolves to an array of SearchResult objects containing tools and their relevance scores.
+     *
+     * @example
+     * // Search for tools containing "list"
+     * const results = await searchCoreService.search("list");
+     *
+     * // Get all tools with pagination
+     * const allTools = await searchCoreService.search("", { limit: 20, offset: 0 });
+     *
+     * @remarks
+     * - Results are automatically cached to improve performance on subsequent identical searches
+     * - Cache is invalidated when server configurations change
+     * - Empty queries return all tools with a score of 1
+     * - Non-empty queries perform fuzzy matching with weighted scoring
+     * - Results are automatically sorted by score (highest first) and paginated
+     */
+    async search(query, options) {
+        const startTime = Date.now();
+        const tools = await this.getToolsWithCache();
+        const filteredTools = this.applyFilters(tools, options?.filters);
+        let results = [];
+        if (!query.trim()) {
+            results = filteredTools.map((tool) => ({
+                tool,
+                score: 1
+            }));
+        }
+        else {
+            results = this.performFuzzySearch(filteredTools, query.trim().toLowerCase());
+        }
+        const sortedResults = results.sort((a, b) => b.score - a.score);
+        const limit = options?.limit || 50;
+        const offset = options?.offset || 0;
+        const paginatedResults = sortedResults.slice(offset, offset + limit);
+        const processingTime = Date.now() - startTime;
+        logger.debug(`Search completed in ${processingTime}ms`, LOG_MODULES.SEARCH);
+        return paginatedResults;
+    }
+    /**
+     * Retrieves all available tools with caching support.
+     *
+     * This method first checks if tools are available in the cache. If cached data exists,
+     * it returns the cached tools immediately. Otherwise, it fetches tools from all connected
+     * MCP servers, applies server-level filtering based on allowedTools configuration,
+     * caches the result, and returns the filtered tools.
+     *
+     * @returns A promise that resolves to an array of Tool objects from all connected servers.
+     *
+     * @remarks
+     * - Tools are filtered based on each server's allowedTools configuration
+     * - If allowedTools is null or undefined, all tools from that server are included
+     * - If allowedTools is an empty array, no tools from that server are included
+     * - Tools are filtered using strict name matching against the allowedTools list
+     */
+    async getToolsWithCache() {
+        const cached = this.cacheService.get();
+        if (cached) {
+            return cached;
+        }
+        // Use new server name-level cache to get all tools
+        const tools = mcpConnectionManager.getAllToolsByServerName();
+        // Get configuration based on server name and apply allowedTools filtering
+        const filteredTools = tools.filter((tool) => {
+            const serverConfig = hubManager.getServerByName(tool.serverName);
+            if (!serverConfig)
+                return true;
+            const allowed = serverConfig.allowedTools;
+            if (allowed == null)
+                return true; // No allowedTools configured, show all tools
+            if (allowed.length === 0)
+                return false; // Empty array, don't show any tools
+            return allowed.includes(tool.name); // Strict filtering
+        });
+        this.cacheService.set(filteredTools);
+        return filteredTools;
+    }
+    /**
+     * Applies search filters to the provided tools array.
+     *
+     * Currently, this method serves as a placeholder for future filter implementation.
+     * The comment indicates that serverId and status fields have been removed from the
+     * Tool interface, so alternative filtering methods will be needed in the future.
+     *
+     * @param tools - The array of tools to filter
+     * @param filters - Optional filter criteria from SearchOptions
+     * @returns The filtered array of tools (currently returns input unchanged)
+     *
+     * @todo Implement actual filtering logic once the Tool interface is updated
+     */
+    applyFilters(tools, filters) {
+        if (!filters)
+            return tools;
+        const filtered = tools;
+        // serverId and status fields have been removed from Tool interface, use other methods for server or status filtering
+        return filtered;
+    }
+    /**
+     * Performs fuzzy search on the provided tools array using the configured scorer.
+     *
+     * This method iterates through all tools and calculates a relevance score for each
+     * tool against the search query using the SearchScorer. Only tools with a score
+     * greater than 0 are included in the results.
+     *
+     * @param tools - The array of tools to search through
+     * @param query - The normalized search query string (lowercase, trimmed)
+     * @returns An array of SearchResult objects containing tools with positive scores
+     *
+     * @remarks
+     * - The query parameter should already be normalized (lowercase and trimmed)
+     * - Tools with a score of 0 or less are excluded from results
+     * - Scoring is handled by the SearchScorer instance with weighted field matching
+     */
+    performFuzzySearch(tools, query) {
+        const results = [];
+        for (const tool of tools) {
+            const score = this.scorer.scoreTool(tool, query);
+            if (score > 0) {
+                results.push({
+                    tool,
+                    score
+                });
+            }
+        }
+        return results;
+    }
+}
+export const searchCoreService = new SearchCoreService();

package/dist/server/src/services/search/search-scorer.d.ts

@@ -0,0 +1,54 @@
+import type { Tool } from '../../../shared/models/tool.model.js';
+/**
+ * SearchScorer class provides relevance scoring functionality for search results.
+ * It calculates weighted scores for tools based on how well their fields (name, description)
+ * match against a given search query using different matching strategies.
+ *
+ * The scoring algorithm prioritizes matches in the following order:
+ * 1. Exact name matches (highest priority)
+ * 2. Name prefix matches (second highest priority)
+ * 3. Partial matches in name or description (lower priority)
+ *
+ * Each field has configurable weights that determine its importance in the final score.
+ * The name field typically has a higher weight than the description field to ensure
+ * that tools with relevant names appear higher in search results.
+ *
+ * This class is used by the SearchCoreService to rank and sort search results
+ * based on relevance to provide better user experience in tool discovery.
+ */
+export declare class SearchScorer {
+    /**
+     * Calculates the relevance score for a tool against a search query.
+     *
+     * The scoring logic ensures proper ranking by:
+     * - Giving exact name matches the highest possible score (120 points)
+     * - Ensuring name prefix matches have higher scores than any combination of
+     *   partial matches in other fields
+     * - Combining scores from multiple fields while maintaining proper priorities
+     *
+     * @param tool - The Tool object to score against the query
+     * @param query - The search query string to match against tool fields
+     * @returns A numerical score representing the relevance of the tool to the query
+     *          Higher scores indicate better matches
+     */
+    scoreTool(tool: Tool, query: string): number;
+    /**
+     * Calculates the score for a single text field against a search query.
+     *
+     * The scoring uses three levels of matching with decreasing priority:
+     * 1. Exact match: Returns 10 * weight (highest score)
+     * 2. Prefix match: Returns 5 * weight (medium score)
+     * 3. Contains match: Returns 3 * weight (lowest score)
+     * 4. No match: Returns 0
+     *
+     * This method performs case-insensitive matching by converting both
+     * the input text and query to lowercase before comparison.
+     *
+     * @param text - The text field to evaluate (e.g., tool name or description)
+     * @param query - The lowercase search query to match against
+     * @param weight - The importance weight for this field (higher = more important)
+     * @returns A numerical score based on the match type multiplied by the field weight
+     */
+    private scoreField;
+}
+//# sourceMappingURL=search-scorer.d.ts.map

package/dist/server/src/services/search/search-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-scorer.d.ts","sourceRoot":"","sources":["../../../../../src/services/search/search-scorer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAEzD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,YAAY;IACvB;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IAyB5C;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,UAAU;CAiBnB"}

package/dist/server/src/services/search/search-scorer.js

@@ -0,0 +1,83 @@
+/**
+ * SearchScorer class provides relevance scoring functionality for search results.
+ * It calculates weighted scores for tools based on how well their fields (name, description)
+ * match against a given search query using different matching strategies.
+ *
+ * The scoring algorithm prioritizes matches in the following order:
+ * 1. Exact name matches (highest priority)
+ * 2. Name prefix matches (second highest priority)
+ * 3. Partial matches in name or description (lower priority)
+ *
+ * Each field has configurable weights that determine its importance in the final score.
+ * The name field typically has a higher weight than the description field to ensure
+ * that tools with relevant names appear higher in search results.
+ *
+ * This class is used by the SearchCoreService to rank and sort search results
+ * based on relevance to provide better user experience in tool discovery.
+ */
+export class SearchScorer {
+    /**
+     * Calculates the relevance score for a tool against a search query.
+     *
+     * The scoring logic ensures proper ranking by:
+     * - Giving exact name matches the highest possible score (120 points)
+     * - Ensuring name prefix matches have higher scores than any combination of
+     *   partial matches in other fields
+     * - Combining scores from multiple fields while maintaining proper priorities
+     *
+     * @param tool - The Tool object to score against the query
+     * @param query - The search query string to match against tool fields
+     * @returns A numerical score representing the relevance of the tool to the query
+     *          Higher scores indicate better matches
+     */
+    scoreTool(tool, query) {
+        const lowerQuery = query.toLowerCase();
+        // Calculate scores for each field
+        const nameScore = this.scoreField(tool.name, lowerQuery, 12);
+        const descScore = this.scoreField(tool.description || '', lowerQuery, 3);
+        // Ensure exact name match has the highest score
+        if (nameScore === 120) {
+            // 10 * 12 = 120 indicates exact name match
+            return nameScore;
+        }
+        // If no exact name match, ensure name prefix match score is higher than other combined scores
+        if (nameScore === 60) {
+            // 5 * 12 = 60 indicates name prefix match
+            // Limit description score to ensure it doesn't exceed name prefix match score
+            const additionalScore = Math.min(descScore, 55);
+            return nameScore + additionalScore;
+        }
+        // For other cases, return the sum of scores from all fields
+        return nameScore + descScore;
+    }
+    /**
+     * Calculates the score for a single text field against a search query.
+     *
+     * The scoring uses three levels of matching with decreasing priority:
+     * 1. Exact match: Returns 10 * weight (highest score)
+     * 2. Prefix match: Returns 5 * weight (medium score)
+     * 3. Contains match: Returns 3 * weight (lowest score)
+     * 4. No match: Returns 0
+     *
+     * This method performs case-insensitive matching by converting both
+     * the input text and query to lowercase before comparison.
+     *
+     * @param text - The text field to evaluate (e.g., tool name or description)
+     * @param query - The lowercase search query to match against
+     * @param weight - The importance weight for this field (higher = more important)
+     * @returns A numerical score based on the match type multiplied by the field weight
+     */
+    scoreField(text, query, weight) {
+        const lowerText = text.toLowerCase();
+        if (lowerText === query) {
+            return 10 * weight;
+        }
+        if (lowerText.startsWith(query)) {
+            return 5 * weight;
+        }
+        if (lowerText.includes(query)) {
+            return 3 * weight;
+        }
+        return 0;
+    }
+}

package/dist/server/src/services/search/types.d.ts

@@ -0,0 +1,20 @@
+import type { Tool } from '../../../shared/models/tool.model.js';
+export interface SearchResult {
+    tool: Tool;
+    score: number;
+}
+export interface SearchOptions {
+    mode: 'fuzzy';
+    filters?: {
+        serverId?: string;
+        tags?: Record<string, string>;
+    };
+    limit?: number;
+    offset?: number;
+}
+export interface SearchQuery {
+    original: string;
+    tokens: string[];
+    filters?: Record<string, never>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/src/services/search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/services/search/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC/B,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CACjC"}

package/dist/server/src/services/search/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/src/services/session/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Session service module index.
+ */
+export { McpSessionManager, mcpSessionManager } from './session-manager.js';
+export type { TransportWithWebStandard, Session } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/src/services/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/session/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC5E,YAAY,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/server/src/services/session/index.js

@@ -0,0 +1,4 @@
+/**
+ * Session service module index.
+ */
+export { McpSessionManager, mcpSessionManager } from './session-manager.js';