@loop_ouroboros/mcp-hub-lite 1.1.0 → 1.1.1

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

@@ -101,16 +101,16 @@ export class SearchCoreService {
      *
      * 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 aggregatedTools configuration,
+     * 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 aggregatedTools configuration
-     * - If aggregatedTools is null or undefined, all tools from that server are included
-     * - If aggregatedTools is an empty array, no tools from that server are included
-     * - Tools are filtered using strict name matching against the aggregatedTools list
+     * - 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();
@@ -119,17 +119,17 @@ export class SearchCoreService {
         }
         // Use new server name-level cache to get all tools
         const tools = mcpConnectionManager.getAllToolsByServerName();
-        // Get configuration based on server name and apply aggregatedTools filtering
+        // 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 aggregated = serverConfig.template.aggregatedTools;
-            if (aggregated == null)
-                return false; // No aggregatedTools configured, don't show any tools
-            if (aggregated.length === 0)
+            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 aggregated.includes(tool.name); // Strict filtering
+            return allowed.includes(tool.name); // Strict filtering
         });
         this.cacheService.set(filteredTools);
         return filteredTools;

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

@@ -1,16 +1,28 @@
+import { SessionState } from '../../../shared/models/session.model.js';
 import type { Session } from './types.js';
 /**
- * Lightweight MCP Session Manager with in-memory session management only.
+ * Enhanced MCP Session Manager with comprehensive persistence and lifecycle management.
  *
- * This service manages MCP sessions with basic in-memory storage and automatic
- * cleanup of stale sessions. It provides session isolation through unique
+ * This service manages MCP sessions with full state persistence, automatic cleanup,
+ * and graceful shutdown handling. It provides session isolation through unique
  * server and transport instances per session while maintaining shared resources
  * for efficiency.
  *
- * Key features:
- * - In-memory session storage only (no persistence)
+ * Key features include:
+ * - Session state persistence to disk with individual session files and index
+ * - Dirty tracking with 5-second batch flushing to minimize I/O operations
  * - Automatic cleanup of stale sessions based on configurable timeout (default 30 minutes)
- * - Session ID generation for internal use
+ * - Graceful shutdown handling with SIGTERM/SIGINT signal capture
+ * - Client metadata integration from client tracker service
+ * - Environment variable controlled debugging (SESSION_DEBUG)
+ *
+ * Session storage structure:
+ * ```
+ * ~/.mcp-hub-lite/
+ * └── sessions/
+ *     ├── index.json          # Session index file
+ *     └── {sessionId}.json    # Individual session state files
+ * ```
  *
  * @example
  * ```typescript
@@ -19,19 +31,200 @@ import type { Session } from './types.js';
  * // Use session.server and session.transport for MCP communication
  * ```
  *
- * @since 2.0.0
+ * @since 1.0.0
  */
 export declare class McpSessionManager {
     private sessions;
+    private sessionStates;
+    private dirtySessions;
+    private sessionsPath;
+    private flushTimeout;
+    private isInitialized;
     private get SESSION_TIMEOUT();
     private get CLEANUP_INTERVAL();
     constructor();
+    /**
+     * Registers process shutdown handlers for graceful session cleanup.
+     *
+     * This method sets up event listeners for SIGTERM and SIGINT signals to ensure
+     * that all dirty sessions are flushed to disk before the process terminates.
+     * This prevents data loss during unexpected shutdowns or service restarts.
+     *
+     * The shutdown handler performs a final flush of all dirty sessions and
+     * clears any pending flush timeouts to ensure clean termination.
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // Called automatically in constructor
+     * sessionManager.registerShutdownHandler();
+     * ```
+     */
+    private registerShutdownHandler;
+    /**
+     * Marks a session as dirty, indicating it needs to be persisted to disk.
+     *
+     * This method adds the session ID to the dirty sessions set and initiates
+     * a delayed batch flush operation with a 5-second timeout. This optimization
+     * prevents excessive I/O operations by batching multiple session updates
+     * that occur in quick succession.
+     *
+     * When the SESSION_DEBUG environment variable is set, detailed logging
+     * is enabled for debugging session persistence behavior.
+     *
+     * @param {string} sessionId - Unique identifier of the session to mark as dirty
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * sessionManager.markAsDirty('my-session-id');
+     * // Session will be flushed to disk within 5 seconds
+     * ```
+     */
+    private markAsDirty;
+    /**
+     * Loads the complete session store from disk, including all individual session files.
+     *
+     * This method reads the sessions index file and loads each individual session state
+     * file, validating each session state against the SessionStateSchema. Invalid
+     * session states are skipped with warning logs, ensuring robust recovery from
+     * corrupted data.
+     *
+     * The method creates the sessions directory and index file if they don't exist,
+     * providing a clean initialization path for first-time usage.
+     *
+     * @returns {Promise<SessionStore>} Complete session store with all valid sessions
+     * @throws {Error} If critical I/O operations fail (non-recoverable errors)
+     *
+     * @example
+     * ```typescript
+     * const store = await sessionManager.loadSessionStore();
+     * console.log(`Loaded ${Object.keys(store.sessions).length} sessions`);
+     * ```
+     */
+    private loadSessionStore;
+    /**
+     * Saves the complete session store to disk, writing individual session files and index.
+     *
+     * This method persists all session states by writing individual JSON files for each
+     * session and updating the sessions index file. The operation is atomic at the
+     * file level, ensuring data integrity even if the process is interrupted.
+     *
+     * @param {SessionStore} store - Complete session store to persist
+     * @returns {Promise<void>} Resolves when all files are successfully written
+     * @throws {Error} If any file write operations fail
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.saveSessionStore(mySessionStore);
+     * console.log('Session store saved successfully');
+     * ```
+     */
+    private saveSessionStore;
+    /**
+     * Restores all sessions from disk during service startup.
+     *
+     * This method is called automatically during initialization to recover session states
+     * from persistent storage. It loads the session store, validates each session state,
+     * and populates the in-memory session state cache. Invalid sessions are skipped
+     * with warning logs to ensure robust startup even with corrupted data.
+     *
+     * The method ensures idempotent execution by checking the initialization flag,
+     * preventing multiple restoration attempts.
+     *
+     * @returns {Promise<void>} Resolves when all valid sessions are restored
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.restoreSessions();
+     * console.log('Sessions restored from disk');
+     * ```
+     */
+    restoreSessions(): Promise<void>;
+    /**
+     * Flushes all dirty sessions to disk in a single batch operation.
+     *
+     * This method collects all sessions marked as dirty, loads the current session store,
+     * updates it with the dirty sessions, and saves the complete store back to disk.
+     * This batch approach minimizes I/O operations and ensures data consistency.
+     *
+     * The method includes comprehensive error handling to prevent partial writes and
+     * maintains detailed logging for debugging and monitoring purposes.
+     *
+     * @returns {Promise<void>} Resolves when all dirty sessions are successfully flushed
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.flushDirtySessions();
+     * console.log('All dirty sessions flushed to disk');
+     * ```
+     */
+    private flushDirtySessions;
+    /**
+     * Updates session metadata by retrieving client information from the client tracker service.
+     *
+     * This method fetches current client information including name, version, working directory,
+     * and project context from the client tracker service and returns a partial session state
+     * update object containing only the relevant metadata fields.
+     *
+     * @param {string} sessionId - Unique identifier of the session to update
+     * @returns {Partial<SessionState>} Partial session state with updated client metadata
+     *
+     * @example
+     * ```typescript
+     * const metadata = sessionManager.updateSessionMetadataFromClient('my-session-id');
+     * console.log('Updated client metadata:', metadata);
+     * ```
+     */
+    private updateSessionMetadataFromClient;
+    /**
+     * Creates or updates a session state with current metadata and timestamps.
+     *
+     * This method merges existing session state (if any) with current client metadata
+     * from the client tracker service, updates access timestamps, and ensures proper
+     * session state structure. The updated state is stored in memory and marked as dirty
+     * for persistence.
+     *
+     * @param {string} sessionId - Unique identifier of the session to create or update
+     * @returns {SessionState} Complete updated session state object
+     *
+     * @example
+     * ```typescript
+     * const state = sessionManager.upsertSessionState('my-session-id');
+     * console.log('Session state updated:', state);
+     * ```
+     */
+    private upsertSessionState;
+    /**
+     * Updates session metadata explicitly with provided key-value pairs.
+     *
+     * This method merges the provided metadata object with existing session metadata,
+     * updates the last accessed timestamp, and marks the session as dirty for persistence.
+     * It's useful for storing custom session-specific information that needs to be persisted.
+     *
+     * @param {string} sessionId - Unique identifier of the session to update
+     * @param {Record<string, unknown>} metadata - Key-value pairs to merge into session metadata
+     * @returns {Promise<void>} Resolves when metadata is updated and marked for persistence
+     *
+     * @example
+     * ```typescript
+     * await sessionManager.updateSessionMetadata('my-session-id', {
+     *   userPreferences: { theme: 'dark' },
+     *   lastProject: 'my-project'
+     * });
+     * ```
+     */
+    updateSessionMetadata(sessionId: string, metadata: Record<string, unknown>): Promise<void>;
     /**
      * Retrieves an existing session or creates a new one if it doesn't exist.
      *
      * This method provides access to active sessions, creating new ones on demand with
      * proper initialization based on the requireInitialize parameter. It updates session
-     * access timestamps.
+     * access timestamps and persists session state changes to ensure data consistency.
+     *
+     * The method includes optimization to prevent excessive timestamp updates for rapid
+     * successive requests by only updating when at least 100ms have passed since the last access.
      *
      * @param {string} sessionId - Unique identifier of the session to retrieve or create
      * @param {boolean} [requireInitialize=true] - Whether to require MCP protocol initialization
@@ -41,9 +234,47 @@ export declare class McpSessionManager {
      * ```typescript
      * // Get or create session with default initialization
      * const session = await sessionManager.getSession('my-session-id');
+     *
+     * // Get or create session without requiring initialization (for restored sessions)
+     * const restoredSession = await sessionManager.getSession('restored-session-id', false);
      * ```
      */
     getSession(sessionId: string, requireInitialize?: boolean): Promise<Session>;
+    /**
+     * Retrieves all persisted session states for API exposure.
+     *
+     * This method returns an array of all current session states, providing a complete
+     * snapshot of all active sessions and their metadata. It's primarily used by the
+     * web API to expose session information to clients.
+     *
+     * @returns {SessionState[]} Array of all current session states
+     *
+     * @example
+     * ```typescript
+     * const allStates = sessionManager.getAllSessionStates();
+     * console.log(`Total active sessions: ${allStates.length}`);
+     * ```
+     */
+    getAllSessionStates(): SessionState[];
+    /**
+     * Retrieves a specific session state by session ID for API exposure.
+     *
+     * This method returns the current state of a specific session or undefined if
+     * the session doesn't exist. It's primarily used by the web API to provide
+     * detailed information about individual sessions.
+     *
+     * @param {string} sessionId - Unique identifier of the session to retrieve
+     * @returns {SessionState | undefined} Session state object or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const state = sessionManager.getSessionState('my-session-id');
+     * if (state) {
+     *   console.log('Session client:', state.clientName);
+     * }
+     * ```
+     */
+    getSessionState(sessionId: string): SessionState | undefined;
     /**
      * Checks if a session object exists in the active sessions map.
      *
@@ -52,9 +283,11 @@ export declare class McpSessionManager {
      */
     hasSession(sessionId: string): boolean;
     /**
-     * Deletes a session from memory.
+     * Deletes a session and removes it from persistent storage.
      *
-     * This method gracefully closes the session's MCP server and removes it from memory.
+     * This method gracefully closes the session's MCP server, removes it from memory,
+     * and ensures it's removed from persistent storage by marking it as dirty and
+     * performing an immediate flush. It returns true if the session existed and was deleted.
      *
      * @param {string} sessionId - Unique identifier of the session to delete
      * @returns {Promise<boolean>} True if session existed and was deleted, false otherwise
@@ -72,7 +305,15 @@ export declare class McpSessionManager {
      * Creates a new MCP session with proper initialization and transport setup.
      *
      * This method sets up a complete MCP session including server, transport, and
-     * communication logging.
+     * communication logging. It handles both fresh sessions and restored sessions,
+     * with special logic for skipping initialization when appropriate.
+     *
+     * Key features:
+     * - Creates StreamableHTTPServerTransport with custom session ID generation
+     * - Sets up comprehensive message logging for debugging
+     * - Handles restored sessions by manually initializing transport state
+     * - Integrates with client tracker service for metadata
+     * - Creates/updates session state and marks as dirty for persistence
      *
      * @param {string} sessionId - Unique identifier for the new session
      * @param {boolean} [requireInitialize=true] - Whether to require MCP protocol initialization
@@ -89,11 +330,14 @@ export declare class McpSessionManager {
     /**
      * Cleans up stale sessions based on the configured session timeout.
      *
-     * This method is called periodically to identify and close
+     * This method is called periodically (every 60 seconds) to identify and close
      * sessions that haven't been accessed within the configured timeout period
      * (default 30 minutes). It gracefully closes MCP servers and removes sessions
      * from memory to prevent resource leaks.
      *
+     * The method logs detailed information about cleaned sessions and maintains
+     * active session count for monitoring purposes.
+     *
      * @returns {void}
      *
      * @example

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

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/session/session-manager.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAA4B,OAAO,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAmC;IAEnD,OAAO,KAAK,eAAe,GAE1B;IAED,OAAO,KAAK,gBAAgB,GAE3B;;IAOD;;;;;;;;;;;;;;;;OAgBG;IACU,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,GAAE,OAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAkE/F;;;;;OAKG;IACI,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;;;;;;;;;;;;OAeG;IACU,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAc/D;;;;;;;;;;;;;;;;OAgBG;YACW,aAAa;IA0G3B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,OAAO;CA4BhB;AAED,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../../../src/services/session/session-manager.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,YAAY,EAIb,MAAM,iCAAiC,CAAC;AAMzC,OAAO,KAAK,EAA4B,OAAO,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,aAAa,CAAS;IAE9B,OAAO,KAAK,eAAe,GAE1B;IAED,OAAO,KAAK,gBAAgB,GAE3B;;IA4BD;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,WAAW;IAgBnB;;;;;;;;;;;;;;;;;;;OAmBG;YACW,gBAAgB;IA8D9B;;;;;;;;;;;;;;;;OAgBG;YACW,gBAAgB;IA8B9B;;;;;;;;;;;;;;;;;;OAkBG;IACU,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IA6D7C;;;;;;;;;;;;;;;;;OAiBG;YACW,kBAAkB;IA+ChC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,+BAA+B;IAcvC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,kBAAkB;IA0B1B;;;;;;;;;;;;;;;;;;OAkBG;IACU,qBAAqB,CAChC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC;IAqBhB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,GAAE,OAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IA0F/F;;;;;;;;;;;;;;OAcG;IACI,mBAAmB,IAAI,YAAY,EAAE;IAI5C;;;;;;;;;;;;;;;;;OAiBG;IACI,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAInE;;;;;OAKG;IACI,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI7C;;;;;;;;;;;;;;;;;OAiBG;IACU,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB/D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;YACW,aAAa;IA8I3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,OAAO;CAqDhB;AAED,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}