@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/services/log-storage.service.js

@@ -0,0 +1,243 @@
+import { logger, LOG_MODULES } from '../utils/logger.js';
+import { eventBus, EventTypes } from './event-bus.service.js';
+/**
+ * Service for managing and storing log entries for MCP servers.
+ *
+ * This service provides centralized log storage with memory-efficient management,
+ * real-time event notifications, and query capabilities for debugging and monitoring
+ * MCP server activities. It maintains separate log streams for each server identified
+ * by their unique server ID and supports configurable log retention limits.
+ *
+ * Key features:
+ * - Memory-efficient log storage with automatic cleanup
+ * - Real-time log event publishing via EventBus
+ * - Listener registration for immediate log notifications
+ * - Queryable log retrieval with filtering and pagination
+ * - Configurable maximum log entries per server to prevent memory leaks
+ *
+ * Usage scenarios:
+ * - Debugging MCP server communication issues
+ * - Monitoring server activity and status changes
+ * - Providing log data for UI log viewers
+ * - Supporting audit trails for server operations
+ */
+export class LogStorageService {
+    serverLogs = new Map();
+    maxLogsPerServer = 1000; // Configurable maximum number of log entries
+    logListeners = new Map();
+    /**
+     * Appends a new log entry for the specified server.
+     *
+     * Creates a timestamped log entry with the provided level and message,
+     * stores it in memory, and notifies all registered listeners and the
+     * global event bus about the new log entry.
+     *
+     * @param serverId - The unique identifier of the MCP server to log for
+     * @param level - The log level (e.g., 'debug', 'info', 'warn', 'error')
+     * @param message - The log message content (will be trimmed of whitespace)
+     * @returns The created LogEntry object containing timestamp, level, and message
+     *
+     * @example
+     * ```typescript
+     * const logEntry = logStorage.append('server-123', 'info', 'Server connected successfully');
+     * console.log(logEntry.timestamp); // Current timestamp in milliseconds
+     * ```
+     */
+    append(serverId, level, message) {
+        const logEntry = {
+            timestamp: Date.now(),
+            level,
+            message: message.trim()
+        };
+        if (!this.serverLogs.has(serverId)) {
+            this.serverLogs.set(serverId, []);
+        }
+        const logs = this.serverLogs.get(serverId);
+        logs.push(logEntry);
+        // Limit log entries to prevent memory leaks
+        if (logs.length > this.maxLogsPerServer) {
+            logs.splice(0, logs.length - this.maxLogsPerServer);
+        }
+        // Notify listeners
+        this.notifyListeners(serverId, logEntry);
+        // Publish log event
+        eventBus.publish(EventTypes.LOG_ENTRY, {
+            serverId,
+            logs: [logEntry]
+        });
+        return logEntry;
+    }
+    /**
+     * Retrieves log entries for the specified server with optional filtering and pagination.
+     *
+     * Returns a filtered and paginated subset of log entries based on the provided query options.
+     * The method supports filtering by log level, timestamp range, and pagination parameters.
+     *
+     * @param serverId - The unique identifier of the MCP server to retrieve logs for
+     * @param options - Optional query parameters for filtering and pagination
+     * @param options.level - Filter logs by specific log level (e.g., 'error', 'warn')
+     * @param options.since - Filter logs with timestamps greater than or equal to this value (milliseconds since epoch)
+     * @param options.offset - Number of log entries to skip (for pagination, default: 0)
+     * @param options.limit - Maximum number of log entries to return (default: all matching entries)
+     * @returns Array of LogEntry objects matching the query criteria, empty array if no logs exist
+     *
+     * @example
+     * ```typescript
+     * // Get last 10 error logs
+     * const errorLogs = logStorage.getLogs('server-123', { level: 'error', limit: 10 });
+     *
+     * // Get logs from the last hour
+     * const recentLogs = logStorage.getLogs('server-123', { since: Date.now() - 3600000 });
+     *
+     * // Get logs with pagination
+     * const paginatedLogs = logStorage.getLogs('server-123', { offset: 20, limit: 10 });
+     * ```
+     */
+    getLogs(serverId, options) {
+        let logs = this.serverLogs.get(serverId) || [];
+        // Filter by level
+        if (options?.level) {
+            logs = logs.filter((log) => log.level === options.level);
+        }
+        // Filter by time
+        if (options?.since != null) {
+            const since = options.since;
+            logs = logs.filter((log) => log.timestamp >= since);
+        }
+        // Pagination
+        const offset = options?.offset || 0;
+        const limit = options?.limit || logs.length;
+        return logs.slice(offset, offset + limit);
+    }
+    /**
+     * Clears all log entries for the specified server.
+     *
+     * Removes all stored log entries for the given server ID, effectively resetting
+     * the log history for that server. This operation is immediate and cannot be undone.
+     *
+     * @param serverId - The unique identifier of the MCP server to clear logs for
+     *
+     * @example
+     * ```typescript
+     * // Clear all logs for a specific server
+     * logStorage.clearLogs('server-123');
+     * ```
+     */
+    clearLogs(serverId) {
+        this.serverLogs.set(serverId, []);
+    }
+    /**
+     * Gets the total number of log entries stored for the specified server.
+     *
+     * @param serverId - The unique identifier of the MCP server to get log count for
+     * @returns The number of log entries stored for the server, or 0 if no logs exist
+     *
+     * @example
+     * ```typescript
+     * const logCount = logStorage.getLogCount('server-123');
+     * console.log(`Server has ${logCount} log entries`);
+     * ```
+     */
+    getLogCount(serverId) {
+        return this.serverLogs.get(serverId)?.length || 0;
+    }
+    /**
+     * Sets the maximum number of log entries to store per server.
+     *
+     * Configures the memory limit for log storage and immediately trims existing logs
+     * for all servers that exceed the new limit. This helps prevent memory leaks in
+     * long-running applications with high log volume.
+     *
+     * @param max - The maximum number of log entries to store per server (must be positive)
+     *
+     * @example
+     * ```typescript
+     * // Limit logs to 500 entries per server
+     * logStorage.setMaxLogsPerServer(500);
+     * ```
+     */
+    setMaxLogsPerServer(max) {
+        this.maxLogsPerServer = max;
+        // Trim logs for all servers
+        for (const [serverId, logs] of this.serverLogs.entries()) {
+            if (logs.length > max) {
+                this.serverLogs.set(serverId, logs.slice(-max));
+            }
+        }
+    }
+    /**
+     * Adds a listener function that will be called whenever a new log entry is appended for the specified server.
+     *
+     * Listeners are called synchronously when new logs are added and should handle errors gracefully
+     * as exceptions are caught and logged but will not prevent other listeners from being called.
+     *
+     * @param serverId - The unique identifier of the MCP server to listen for logs
+     * @param listener - Function to be called with each new LogEntry for the server
+     *
+     * @example
+     * ```typescript
+     * const listener = (log: LogEntry) => {
+     *   console.log(`New log for server: ${log.message}`);
+     * };
+     * logStorage.addLogListener('server-123', listener);
+     * ```
+     */
+    addLogListener(serverId, listener) {
+        if (!this.logListeners.has(serverId)) {
+            this.logListeners.set(serverId, []);
+        }
+        this.logListeners.get(serverId).push(listener);
+    }
+    /**
+     * Removes a previously registered log listener for the specified server.
+     *
+     * @param serverId - The unique identifier of the MCP server to remove the listener from
+     * @param listener - The listener function to remove (must be the exact same function reference)
+     *
+     * @example
+     * ```typescript
+     * // Remove the listener
+     * logStorage.removeLogListener('server-123', listener);
+     * ```
+     */
+    removeLogListener(serverId, listener) {
+        const listeners = this.logListeners.get(serverId);
+        if (listeners) {
+            const index = listeners.indexOf(listener);
+            if (index !== -1) {
+                listeners.splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Notify listeners
+     */
+    notifyListeners(serverId, log) {
+        const listeners = this.logListeners.get(serverId);
+        if (listeners) {
+            listeners.forEach((listener) => {
+                try {
+                    listener(log);
+                }
+                catch (error) {
+                    logger.error(`Error in log listener for server ${serverId}:`, error, LOG_MODULES.dynamic(serverId));
+                }
+            });
+        }
+    }
+    /**
+     * Gets an array of all server IDs that currently have stored log entries.
+     *
+     * @returns Array of server ID strings that have logs, empty array if no servers have logs
+     *
+     * @example
+     * ```typescript
+     * const serverIds = logStorage.getServersWithLogs();
+     * console.log(`Servers with logs: ${serverIds.join(', ')}`);
+     * ```
+     */
+    getServersWithLogs() {
+        return Array.from(this.serverLogs.keys());
+    }
+}
+export const logStorage = new LogStorageService();

package/dist/server/src/services/mcp-connection-manager.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @deprecated This file is now a thin wrapper. Please import from './connection/index.js' instead.
+ * MCP Connection Manager - Connection management for MCP servers.
+ */
+export { McpConnectionManager, mcpConnectionManager } from './connection/index.js';
+export type { ServerStatus } from './connection/index.js';
+//# sourceMappingURL=mcp-connection-manager.d.ts.map

package/dist/server/src/services/mcp-connection-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-connection-manager.d.ts","sourceRoot":"","sources":["../../../../src/services/mcp-connection-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACnF,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/server/src/services/mcp-connection-manager.js

@@ -0,0 +1,6 @@
+/**
+ * @deprecated This file is now a thin wrapper. Please import from './connection/index.js' instead.
+ * MCP Connection Manager - Connection management for MCP servers.
+ */
+// Re-export everything from the new modular implementation
+export { McpConnectionManager, mcpConnectionManager } from './connection/index.js';

package/dist/server/src/services/mcp-session-manager.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @deprecated This file is now a thin wrapper. Please import from './session/index.js' instead.
+ */
+export { McpSessionManager, mcpSessionManager } from './session/index.js';
+export type { TransportWithWebStandard, Session } from './session/types.js';
+//# sourceMappingURL=mcp-session-manager.d.ts.map

package/dist/server/src/services/mcp-session-manager.d.ts.map

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

package/dist/server/src/services/mcp-session-manager.js

@@ -0,0 +1,4 @@
+/**
+ * @deprecated This file is now a thin wrapper. Please import from './session/index.js' instead.
+ */
+export { McpSessionManager, mcpSessionManager } from './session/index.js';

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

@@ -0,0 +1,5 @@
+export * from './search-core.service.js';
+export * from './search-scorer.js';
+export * from './search-cache.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/services/search/index.ts"],"names":[],"mappings":"AACA,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,5 @@
+// Search module index
+export * from './search-core.service.js';
+export * from './search-scorer.js';
+export * from './search-cache.js';
+export * from './types.js';

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

@@ -0,0 +1,132 @@
+import type { Tool } from '../../../shared/models/tool.model.js';
+/**
+ * Search cache service that provides time-based caching for search results.
+ *
+ * This service implements a simple TTL (Time-To-Live) cache mechanism for storing
+ * and retrieving search results. It automatically invalidates cached data after
+ * a specified time period (30 seconds by default) to ensure freshness while
+ * providing performance benefits for repeated searches within the TTL window.
+ *
+ * The cache stores an array of Tool objects and maintains a timestamp of the last
+ * update to determine cache validity. This is particularly useful in scenarios
+ * where search operations might be expensive or frequently repeated, such as
+ * in autocomplete or real-time search interfaces.
+ *
+ * @example
+ * ```typescript
+ * const cache = new SearchCacheService();
+ *
+ * // Set cache with search results
+ * cache.set(searchResults);
+ *
+ * // Retrieve cached results (returns null if expired)
+ * const results = cache.get();
+ *
+ * // Manually invalidate cache
+ * cache.invalidate();
+ * ```
+ */
+export declare class SearchCacheService {
+    private cache;
+    private lastUpdate;
+    private readonly CACHE_TTL;
+    /**
+     * Checks if the current cache is valid based on the TTL (Time-To-Live).
+     *
+     * A cache is considered valid if it exists and has not exceeded the
+     * configured TTL since the last update. The default TTL is 30 seconds.
+     *
+     * @returns {boolean} True if the cache exists and is within the TTL window,
+     *                    false otherwise (either no cache or expired).
+     *
+     * @example
+     * ```typescript
+     * if (cache.isValid()) {
+     *   // Use cached results
+     *   const results = cache.get();
+     * }
+     * ```
+     */
+    isValid(): boolean;
+    /**
+     * Retrieves the cached search results if they are still valid.
+     *
+     * This method first checks if the cache is valid using the TTL mechanism.
+     * If the cache is invalid or expired, it automatically clears the cache
+     * and returns null. Otherwise, it returns the cached Tool array.
+     *
+     * @returns {Tool[] | null} The cached array of Tool objects if valid,
+     *                          null if the cache is invalid, expired, or empty.
+     *
+     * @example
+     * ```typescript
+     * const cachedResults = cache.get();
+     * if (cachedResults) {
+     *   // Use cached results
+     *   return cachedResults;
+     * } else {
+     *   // Perform fresh search
+     *   const freshResults = performSearch();
+     *   cache.set(freshResults);
+     *   return freshResults;
+     * }
+     * ```
+     */
+    get(): Tool[] | null;
+    /**
+     * Stores search results in the cache with the current timestamp.
+     *
+     * This method sets the provided Tool array as the cached value and
+     * records the current timestamp as the last update time. The cache
+     * will remain valid until it exceeds the TTL (30 seconds by default).
+     *
+     * @param {Tool[]} tools - The array of Tool objects to cache.
+     *                         Must be a valid array of Tool instances.
+     *
+     * @example
+     * ```typescript
+     * const searchResults = await searchTools('pattern');
+     * cache.set(searchResults);
+     * ```
+     */
+    set(tools: Tool[]): void;
+    /**
+     * Immediately invalidates and clears the current cache.
+     *
+     * This method forces the cache to be cleared by setting the cache to null
+     * and resetting the last update timestamp to zero. After calling this method,
+     * subsequent calls to `get()` will return null until new data is set.
+     *
+     * This is useful when external events indicate that cached data may be stale,
+     * such as when servers are added, removed, or updated.
+     *
+     * @example
+     * ```typescript
+     * // Invalidate cache when server configuration changes
+     * hubManager.on('serverUpdated', () => {
+     *   searchCache.invalidate();
+     * });
+     * ```
+     */
+    invalidate(): void;
+    /**
+     * Updates a specific tool in the cache (deprecated method).
+     *
+     * This method is currently deprecated because the serverId field has been
+     * removed from the Tool interface. It logs a warning message and performs
+     * no actual operations. The method is kept for backward compatibility but
+     * should not be used in new code.
+     *
+     * @deprecated This method is deprecated and does nothing. ServerId field
+     *             has been removed from the Tool interface, making this method
+     *             obsolete.
+     *
+     * @example
+     * ```typescript
+     * // This will log a warning but do nothing
+     * cache.updateTool();
+     * ```
+     */
+    updateTool(): void;
+}
+//# sourceMappingURL=search-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search-cache.d.ts","sourceRoot":"","sources":["../../../../../src/services/search/search-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IAEvC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,IAAI,OAAO;IAMlB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,IAAI,IAAI,EAAE,GAAG,IAAI;IASpB;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI;IAKxB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,IAAI,IAAI;CAQnB"}

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

@@ -0,0 +1,151 @@
+import { logger, LOG_MODULES } from '../../utils/logger.js';
+/**
+ * Search cache service that provides time-based caching for search results.
+ *
+ * This service implements a simple TTL (Time-To-Live) cache mechanism for storing
+ * and retrieving search results. It automatically invalidates cached data after
+ * a specified time period (30 seconds by default) to ensure freshness while
+ * providing performance benefits for repeated searches within the TTL window.
+ *
+ * The cache stores an array of Tool objects and maintains a timestamp of the last
+ * update to determine cache validity. This is particularly useful in scenarios
+ * where search operations might be expensive or frequently repeated, such as
+ * in autocomplete or real-time search interfaces.
+ *
+ * @example
+ * ```typescript
+ * const cache = new SearchCacheService();
+ *
+ * // Set cache with search results
+ * cache.set(searchResults);
+ *
+ * // Retrieve cached results (returns null if expired)
+ * const results = cache.get();
+ *
+ * // Manually invalidate cache
+ * cache.invalidate();
+ * ```
+ */
+export class SearchCacheService {
+    cache = null;
+    lastUpdate = 0;
+    CACHE_TTL = 30 * 1000;
+    /**
+     * Checks if the current cache is valid based on the TTL (Time-To-Live).
+     *
+     * A cache is considered valid if it exists and has not exceeded the
+     * configured TTL since the last update. The default TTL is 30 seconds.
+     *
+     * @returns {boolean} True if the cache exists and is within the TTL window,
+     *                    false otherwise (either no cache or expired).
+     *
+     * @example
+     * ```typescript
+     * if (cache.isValid()) {
+     *   // Use cached results
+     *   const results = cache.get();
+     * }
+     * ```
+     */
+    isValid() {
+        if (!this.cache)
+            return false;
+        return Date.now() - this.lastUpdate < this.CACHE_TTL;
+    }
+    /**
+     * Retrieves the cached search results if they are still valid.
+     *
+     * This method first checks if the cache is valid using the TTL mechanism.
+     * If the cache is invalid or expired, it automatically clears the cache
+     * and returns null. Otherwise, it returns the cached Tool array.
+     *
+     * @returns {Tool[] | null} The cached array of Tool objects if valid,
+     *                          null if the cache is invalid, expired, or empty.
+     *
+     * @example
+     * ```typescript
+     * const cachedResults = cache.get();
+     * if (cachedResults) {
+     *   // Use cached results
+     *   return cachedResults;
+     * } else {
+     *   // Perform fresh search
+     *   const freshResults = performSearch();
+     *   cache.set(freshResults);
+     *   return freshResults;
+     * }
+     * ```
+     */
+    get() {
+        if (!this.isValid()) {
+            this.cache = null;
+            return null;
+        }
+        return this.cache;
+    }
+    /**
+     * Stores search results in the cache with the current timestamp.
+     *
+     * This method sets the provided Tool array as the cached value and
+     * records the current timestamp as the last update time. The cache
+     * will remain valid until it exceeds the TTL (30 seconds by default).
+     *
+     * @param {Tool[]} tools - The array of Tool objects to cache.
+     *                         Must be a valid array of Tool instances.
+     *
+     * @example
+     * ```typescript
+     * const searchResults = await searchTools('pattern');
+     * cache.set(searchResults);
+     * ```
+     */
+    set(tools) {
+        this.cache = tools;
+        this.lastUpdate = Date.now();
+    }
+    /**
+     * Immediately invalidates and clears the current cache.
+     *
+     * This method forces the cache to be cleared by setting the cache to null
+     * and resetting the last update timestamp to zero. After calling this method,
+     * subsequent calls to `get()` will return null until new data is set.
+     *
+     * This is useful when external events indicate that cached data may be stale,
+     * such as when servers are added, removed, or updated.
+     *
+     * @example
+     * ```typescript
+     * // Invalidate cache when server configuration changes
+     * hubManager.on('serverUpdated', () => {
+     *   searchCache.invalidate();
+     * });
+     * ```
+     */
+    invalidate() {
+        this.cache = null;
+        this.lastUpdate = 0;
+    }
+    /**
+     * Updates a specific tool in the cache (deprecated method).
+     *
+     * This method is currently deprecated because the serverId field has been
+     * removed from the Tool interface. It logs a warning message and performs
+     * no actual operations. The method is kept for backward compatibility but
+     * should not be used in new code.
+     *
+     * @deprecated This method is deprecated and does nothing. ServerId field
+     *             has been removed from the Tool interface, making this method
+     *             obsolete.
+     *
+     * @example
+     * ```typescript
+     * // This will log a warning but do nothing
+     * cache.updateTool();
+     * ```
+     */
+    updateTool() {
+        // Since serverId field has been removed from Tool interface, this method needs refactoring
+        // Currently kept but not performing any operations, or modify according to actual requirements
+        logger.warn('updateTool method is deprecated because serverId field is removed from Tool', LOG_MODULES.SEARCH);
+    }
+}