@memberjunction/core-entities 3.3.0 → 3.4.0

package/dist/engines/MCPEngine.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview MCP Engine for caching MCP server, connection, and tool data
+ *
+ * Provides centralized caching for MCP (Model Context Protocol) entities.
+ * Execution logs are NOT cached here - they should be loaded on-demand via RunView.
+ *
+ * @module @memberjunction/core-entities/MCPEngine
+ */
+import { BaseEngine, IMetadataProvider, UserInfo } from "@memberjunction/core";
+import { MCPServerEntity, MCPServerConnectionEntity, MCPServerToolEntity } from "../generated/entity_subclasses";
+/**
+ * MCPEngine provides centralized caching for MCP-related entities.
+ *
+ * Cached entities:
+ * - MCP Servers: Server definitions with transport, auth, and rate limit config
+ * - MCP Server Connections: Connection instances for each server
+ * - MCP Server Tools: Tools discovered from MCP servers
+ *
+ * NOT cached (load on-demand):
+ * - MCP Tool Execution Logs: Historical data that should be queried as needed
+ *
+ * @example
+ * ```typescript
+ * // Initialize the engine
+ * await MCPEngine.Instance.Config(false, contextUser);
+ *
+ * // Access cached data
+ * const servers = MCPEngine.Instance.Servers;
+ * const connections = MCPEngine.Instance.Connections;
+ * const tools = MCPEngine.Instance.Tools;
+ *
+ * // Get tools for a specific server
+ * const serverTools = MCPEngine.Instance.GetToolsByServer(serverId);
+ *
+ * // Force refresh
+ * await MCPEngine.Instance.Config(true, contextUser);
+ * ```
+ */
+export declare class MCPEngine extends BaseEngine<MCPEngine> {
+    /**
+     * Configures and loads the MCP engine data.
+     *
+     * @param forceRefresh - If true, forces a refresh of cached data
+     * @param contextUser - User context for data loading (required for server-side)
+     * @param provider - Optional metadata provider
+     */
+    Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    /**
+     * Gets the singleton instance of MCPEngine
+     */
+    static get Instance(): MCPEngine;
+    private _Servers;
+    private _Connections;
+    private _Tools;
+    /**
+     * Gets all cached MCP servers
+     */
+    get Servers(): MCPServerEntity[];
+    /**
+     * Gets all cached MCP server connections
+     */
+    get Connections(): MCPServerConnectionEntity[];
+    /**
+     * Gets all cached MCP server tools
+     */
+    get Tools(): MCPServerToolEntity[];
+    /**
+     * Gets a server by ID
+     *
+     * @param serverId - The server ID
+     * @returns The server entity or undefined if not found
+     */
+    GetServerById(serverId: string): MCPServerEntity | undefined;
+    /**
+     * Gets a connection by ID
+     *
+     * @param connectionId - The connection ID
+     * @returns The connection entity or undefined if not found
+     */
+    GetConnectionById(connectionId: string): MCPServerConnectionEntity | undefined;
+    /**
+     * Gets a tool by ID
+     *
+     * @param toolId - The tool ID
+     * @returns The tool entity or undefined if not found
+     */
+    GetToolById(toolId: string): MCPServerToolEntity | undefined;
+    /**
+     * Gets all connections for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of connections for the server
+     */
+    GetConnectionsByServer(serverId: string): MCPServerConnectionEntity[];
+    /**
+     * Gets all tools for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of tools for the server
+     */
+    GetToolsByServer(serverId: string): MCPServerToolEntity[];
+    /**
+     * Gets active servers only
+     *
+     * @returns Array of servers with Status = 'Active'
+     */
+    get ActiveServers(): MCPServerEntity[];
+    /**
+     * Gets active connections only
+     *
+     * @returns Array of connections with Status = 'Active'
+     */
+    get ActiveConnections(): MCPServerConnectionEntity[];
+    /**
+     * Gets active tools only
+     *
+     * @returns Array of tools with Status = 'Active'
+     */
+    get ActiveTools(): MCPServerToolEntity[];
+    /**
+     * Gets active connections for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of active connections for the server
+     */
+    GetActiveConnectionsByServer(serverId: string): MCPServerConnectionEntity[];
+    /**
+     * Gets active tools for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of active tools for the server
+     */
+    GetActiveToolsByServer(serverId: string): MCPServerToolEntity[];
+    /**
+     * Gets the server name for a given server ID
+     *
+     * @param serverId - The server ID
+     * @returns The server name or 'Unknown' if not found
+     */
+    GetServerName(serverId: string): string;
+    /**
+     * Gets the connection name for a given connection ID
+     *
+     * @param connectionId - The connection ID
+     * @returns The connection name or 'Unknown' if not found
+     */
+    GetConnectionName(connectionId: string): string;
+}
+//# sourceMappingURL=MCPEngine.d.ts.map

package/dist/engines/MCPEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MCPEngine.d.ts","sourceRoot":"","sources":["../../src/engines/MCPEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAA4B,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACzG,OAAO,EACH,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACtB,MAAM,gCAAgC,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,SAAU,SAAQ,UAAU,CAAC,SAAS,CAAC;IAChD;;;;;;OAMG;IACU,MAAM,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBhH;;OAEG;IACH,WAAkB,QAAQ,IAAI,SAAS,CAEtC;IAMD,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,MAAM,CAA6B;IAM3C;;OAEG;IACH,IAAW,OAAO,IAAI,eAAe,EAAE,CAEtC;IAED;;OAEG;IACH,IAAW,WAAW,IAAI,yBAAyB,EAAE,CAEpD;IAED;;OAEG;IACH,IAAW,KAAK,IAAI,mBAAmB,EAAE,CAExC;IAMD;;;;;OAKG;IACI,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAInE;;;;;OAKG;IACI,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,yBAAyB,GAAG,SAAS;IAIrF;;;;;OAKG;IACI,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAInE;;;;;OAKG;IACI,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,EAAE;IAI5E;;;;;OAKG;IACI,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAIhE;;;;OAIG;IACH,IAAW,aAAa,IAAI,eAAe,EAAE,CAE5C;IAED;;;;OAIG;IACH,IAAW,iBAAiB,IAAI,yBAAyB,EAAE,CAE1D;IAED;;;;OAIG;IACH,IAAW,WAAW,IAAI,mBAAmB,EAAE,CAE9C;IAED;;;;;OAKG;IACI,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,EAAE;IAIlF;;;;;OAKG;IACI,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,EAAE;IAItE;;;;;OAKG;IACI,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAK9C;;;;;OAKG;IACI,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;CAIzD"}

package/dist/engines/MCPEngine.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * @fileoverview MCP Engine for caching MCP server, connection, and tool data
+ *
+ * Provides centralized caching for MCP (Model Context Protocol) entities.
+ * Execution logs are NOT cached here - they should be loaded on-demand via RunView.
+ *
+ * @module @memberjunction/core-entities/MCPEngine
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPEngine = void 0;
+const core_1 = require("@memberjunction/core");
+/**
+ * MCPEngine provides centralized caching for MCP-related entities.
+ *
+ * Cached entities:
+ * - MCP Servers: Server definitions with transport, auth, and rate limit config
+ * - MCP Server Connections: Connection instances for each server
+ * - MCP Server Tools: Tools discovered from MCP servers
+ *
+ * NOT cached (load on-demand):
+ * - MCP Tool Execution Logs: Historical data that should be queried as needed
+ *
+ * @example
+ * ```typescript
+ * // Initialize the engine
+ * await MCPEngine.Instance.Config(false, contextUser);
+ *
+ * // Access cached data
+ * const servers = MCPEngine.Instance.Servers;
+ * const connections = MCPEngine.Instance.Connections;
+ * const tools = MCPEngine.Instance.Tools;
+ *
+ * // Get tools for a specific server
+ * const serverTools = MCPEngine.Instance.GetToolsByServer(serverId);
+ *
+ * // Force refresh
+ * await MCPEngine.Instance.Config(true, contextUser);
+ * ```
+ */
+class MCPEngine extends core_1.BaseEngine {
+    constructor() {
+        super(...arguments);
+        // ========================================
+        // Private Storage
+        // ========================================
+        this._Servers = [];
+        this._Connections = [];
+        this._Tools = [];
+    }
+    /**
+     * Configures and loads the MCP engine data.
+     *
+     * @param forceRefresh - If true, forces a refresh of cached data
+     * @param contextUser - User context for data loading (required for server-side)
+     * @param provider - Optional metadata provider
+     */
+    async Config(forceRefresh, contextUser, provider) {
+        const configs = [
+            {
+                Type: 'entity',
+                EntityName: 'MJ: MCP Servers',
+                PropertyName: '_Servers',
+                CacheLocal: true
+            },
+            {
+                Type: 'entity',
+                EntityName: 'MJ: MCP Server Connections',
+                PropertyName: '_Connections',
+                CacheLocal: true
+            },
+            {
+                Type: 'entity',
+                EntityName: 'MJ: MCP Server Tools',
+                PropertyName: '_Tools',
+                CacheLocal: true
+            }
+        ];
+        await this.Load(configs, provider, forceRefresh, contextUser);
+    }
+    /**
+     * Gets the singleton instance of MCPEngine
+     */
+    static get Instance() {
+        return super.getInstance();
+    }
+    // ========================================
+    // Public Getters
+    // ========================================
+    /**
+     * Gets all cached MCP servers
+     */
+    get Servers() {
+        return this._Servers;
+    }
+    /**
+     * Gets all cached MCP server connections
+     */
+    get Connections() {
+        return this._Connections;
+    }
+    /**
+     * Gets all cached MCP server tools
+     */
+    get Tools() {
+        return this._Tools;
+    }
+    // ========================================
+    // Helper Methods
+    // ========================================
+    /**
+     * Gets a server by ID
+     *
+     * @param serverId - The server ID
+     * @returns The server entity or undefined if not found
+     */
+    GetServerById(serverId) {
+        return this._Servers.find(s => s.ID === serverId);
+    }
+    /**
+     * Gets a connection by ID
+     *
+     * @param connectionId - The connection ID
+     * @returns The connection entity or undefined if not found
+     */
+    GetConnectionById(connectionId) {
+        return this._Connections.find(c => c.ID === connectionId);
+    }
+    /**
+     * Gets a tool by ID
+     *
+     * @param toolId - The tool ID
+     * @returns The tool entity or undefined if not found
+     */
+    GetToolById(toolId) {
+        return this._Tools.find(t => t.ID === toolId);
+    }
+    /**
+     * Gets all connections for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of connections for the server
+     */
+    GetConnectionsByServer(serverId) {
+        return this._Connections.filter(c => c.MCPServerID === serverId);
+    }
+    /**
+     * Gets all tools for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of tools for the server
+     */
+    GetToolsByServer(serverId) {
+        return this._Tools.filter(t => t.MCPServerID === serverId);
+    }
+    /**
+     * Gets active servers only
+     *
+     * @returns Array of servers with Status = 'Active'
+     */
+    get ActiveServers() {
+        return this._Servers.filter(s => s.Status === 'Active');
+    }
+    /**
+     * Gets active connections only
+     *
+     * @returns Array of connections with Status = 'Active'
+     */
+    get ActiveConnections() {
+        return this._Connections.filter(c => c.Status === 'Active');
+    }
+    /**
+     * Gets active tools only
+     *
+     * @returns Array of tools with Status = 'Active'
+     */
+    get ActiveTools() {
+        return this._Tools.filter(t => t.Status === 'Active');
+    }
+    /**
+     * Gets active connections for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of active connections for the server
+     */
+    GetActiveConnectionsByServer(serverId) {
+        return this._Connections.filter(c => c.MCPServerID === serverId && c.Status === 'Active');
+    }
+    /**
+     * Gets active tools for a specific server
+     *
+     * @param serverId - The server ID
+     * @returns Array of active tools for the server
+     */
+    GetActiveToolsByServer(serverId) {
+        return this._Tools.filter(t => t.MCPServerID === serverId && t.Status === 'Active');
+    }
+    /**
+     * Gets the server name for a given server ID
+     *
+     * @param serverId - The server ID
+     * @returns The server name or 'Unknown' if not found
+     */
+    GetServerName(serverId) {
+        const server = this.GetServerById(serverId);
+        return server?.Name ?? 'Unknown';
+    }
+    /**
+     * Gets the connection name for a given connection ID
+     *
+     * @param connectionId - The connection ID
+     * @returns The connection name or 'Unknown' if not found
+     */
+    GetConnectionName(connectionId) {
+        const connection = this.GetConnectionById(connectionId);
+        return connection?.Name ?? 'Unknown';
+    }
+}
+exports.MCPEngine = MCPEngine;
+//# sourceMappingURL=MCPEngine.js.map

package/dist/engines/MCPEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MCPEngine.js","sourceRoot":"","sources":["../../src/engines/MCPEngine.ts"],"names":[],"mappings":"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"}

package/dist/engines/UserInfoEngine.d.ts

@@ -44,6 +44,25 @@ export declare class UserInfoEngine extends BaseEngine<UserInfoEngine> {
     private _UserNotificationPreferences;
     private _loadedForUserId;
     private _createDefaultAppsPromise;
+    /**
+     * Debounce time in milliseconds for SetSettingDebounced calls.
+     * Default is 500ms. Change via the SettingsDebounceMs setter.
+     */
+    private _settingsDebounceMs;
+    /**
+     * Map of pending setting updates: key -> { value, contextUser, timestamp }
+     * These are queued and flushed after the debounce period of inactivity.
+     */
+    private _pendingSettings;
+    /**
+     * Timer handle for the debounce flush
+     */
+    private _settingsDebounceTimer;
+    /**
+     * Promise that resolves when the current flush operation completes.
+     * Used to prevent concurrent flush operations.
+     */
+    private _flushPromise;
     /**
      * Configures the engine by loading user-specific metadata from the database.
      * All entities are filtered by the current user's ID and cached locally for performance.
@@ -87,6 +106,50 @@ export declare class UserInfoEngine extends BaseEngine<UserInfoEngine> {
      * @returns true if successful (or setting didn't exist), false on error
      */
     DeleteSetting(settingKey: string): Promise<boolean>;
+    /**
+     * Get the current debounce time in milliseconds for SetSettingDebounced calls.
+     */
+    get SettingsDebounceMs(): number;
+    /**
+     * Set the debounce time in milliseconds for SetSettingDebounced calls.
+     * When changed, any pending settings are flushed first before the new debounce time takes effect.
+     * @param value - The debounce time in milliseconds (minimum 100ms, maximum 10000ms)
+     */
+    set SettingsDebounceMs(value: number);
+    /**
+     * Queue a setting update with debouncing. Multiple calls within the debounce period
+     * are batched together, with only the last value for each key being saved.
+     * The actual database save occurs after the debounce period of inactivity.
+     *
+     * This is the preferred method for UI components that may update settings frequently
+     * (e.g., on every resize, scroll, or input change).
+     *
+     * @param settingKey - The setting key (e.g., "AI_DASHBOARD_ROOT/ai-models")
+     * @param value - The setting value (string, typically JSON for complex data)
+     * @param contextUser - Optional user context for server-side use
+     */
+    SetSettingDebounced(settingKey: string, value: string, contextUser?: UserInfo): void;
+    /**
+     * Immediately flush all pending debounced settings to the database.
+     * Call this when you need to ensure settings are saved (e.g., before navigation).
+     * Safe to call multiple times - concurrent calls will wait for the current flush to complete.
+     *
+     * @returns Promise that resolves when all pending settings have been saved
+     */
+    FlushPendingSettings(): Promise<void>;
+    /**
+     * Internal method to perform the actual flush of settings.
+     * @param settingsToSave - Map of settings to save
+     */
+    private doFlushSettings;
+    /**
+     * Check if there are any pending debounced settings waiting to be saved.
+     */
+    get HasPendingSettings(): boolean;
+    /**
+     * Get the number of pending debounced settings.
+     */
+    get PendingSettingsCount(): number;
     /**
      * Get unread notifications for the current user
      */

package/dist/engines/UserInfoEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UserInfoEngine.d.ts","sourceRoot":"","sources":["../../src/engines/UserInfoEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"UserInfoEngine.d.ts","sourceRoot":"","sources":["../../src/engines/UserInfoEngine.ts"],"names":[],"mappings":"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"}

package/dist/engines/UserInfoEngine.js

@@ -47,6 +47,28 @@ let UserInfoEngine = class UserInfoEngine extends core_1.BaseEngine {
         this._loadedForUserId = null;
         // Track in-progress CreateDefaultApplications call to prevent duplicate execution
         this._createDefaultAppsPromise = null;
+        // ========================================================================
+        // DEBOUNCED SETTINGS SUPPORT
+        // ========================================================================
+        /**
+         * Debounce time in milliseconds for SetSettingDebounced calls.
+         * Default is 500ms. Change via the SettingsDebounceMs setter.
+         */
+        this._settingsDebounceMs = 500;
+        /**
+         * Map of pending setting updates: key -> { value, contextUser, timestamp }
+         * These are queued and flushed after the debounce period of inactivity.
+         */
+        this._pendingSettings = new Map();
+        /**
+         * Timer handle for the debounce flush
+         */
+        this._settingsDebounceTimer = null;
+        /**
+         * Promise that resolves when the current flush operation completes.
+         * Used to prevent concurrent flush operations.
+         */
+        this._flushPromise = null;
     }
     /**
      * Returns the global instance of the class. This is a singleton class, so there is only one instance of it in the application.
@@ -248,6 +270,120 @@ let UserInfoEngine = class UserInfoEngine extends core_1.BaseEngine {
             return false;
         }
     }
+    // ========================================================================
+    // DEBOUNCED SETTINGS METHODS
+    // ========================================================================
+    /**
+     * Get the current debounce time in milliseconds for SetSettingDebounced calls.
+     */
+    get SettingsDebounceMs() {
+        return this._settingsDebounceMs;
+    }
+    /**
+     * Set the debounce time in milliseconds for SetSettingDebounced calls.
+     * When changed, any pending settings are flushed first before the new debounce time takes effect.
+     * @param value - The debounce time in milliseconds (minimum 100ms, maximum 10000ms)
+     */
+    set SettingsDebounceMs(value) {
+        const clampedValue = Math.max(100, Math.min(10000, value));
+        if (clampedValue !== this._settingsDebounceMs) {
+            // Flush any pending settings before changing the debounce time
+            this.FlushPendingSettings();
+            this._settingsDebounceMs = clampedValue;
+        }
+    }
+    /**
+     * Queue a setting update with debouncing. Multiple calls within the debounce period
+     * are batched together, with only the last value for each key being saved.
+     * The actual database save occurs after the debounce period of inactivity.
+     *
+     * This is the preferred method for UI components that may update settings frequently
+     * (e.g., on every resize, scroll, or input change).
+     *
+     * @param settingKey - The setting key (e.g., "AI_DASHBOARD_ROOT/ai-models")
+     * @param value - The setting value (string, typically JSON for complex data)
+     * @param contextUser - Optional user context for server-side use
+     */
+    SetSettingDebounced(settingKey, value, contextUser) {
+        // Queue the setting update
+        this._pendingSettings.set(settingKey, {
+            value,
+            contextUser,
+            timestamp: Date.now(),
+        });
+        // Reset the debounce timer
+        if (this._settingsDebounceTimer) {
+            clearTimeout(this._settingsDebounceTimer);
+        }
+        this._settingsDebounceTimer = setTimeout(() => {
+            this.FlushPendingSettings();
+        }, this._settingsDebounceMs);
+    }
+    /**
+     * Immediately flush all pending debounced settings to the database.
+     * Call this when you need to ensure settings are saved (e.g., before navigation).
+     * Safe to call multiple times - concurrent calls will wait for the current flush to complete.
+     *
+     * @returns Promise that resolves when all pending settings have been saved
+     */
+    async FlushPendingSettings() {
+        // Clear the timer since we're flushing now
+        if (this._settingsDebounceTimer) {
+            clearTimeout(this._settingsDebounceTimer);
+            this._settingsDebounceTimer = null;
+        }
+        // If nothing pending, return immediately
+        if (this._pendingSettings.size === 0) {
+            return;
+        }
+        // If a flush is already in progress, wait for it and then check again
+        if (this._flushPromise) {
+            await this._flushPromise;
+            // After waiting, there might be new pending settings, so recurse
+            if (this._pendingSettings.size > 0) {
+                return this.FlushPendingSettings();
+            }
+            return;
+        }
+        // Take a snapshot of pending settings and clear the queue
+        const settingsToSave = new Map(this._pendingSettings);
+        this._pendingSettings.clear();
+        // Create the flush promise
+        this._flushPromise = this.doFlushSettings(settingsToSave);
+        try {
+            await this._flushPromise;
+        }
+        finally {
+            this._flushPromise = null;
+        }
+    }
+    /**
+     * Internal method to perform the actual flush of settings.
+     * @param settingsToSave - Map of settings to save
+     */
+    async doFlushSettings(settingsToSave) {
+        const savePromises = [];
+        for (const [key, { value, contextUser }] of settingsToSave) {
+            savePromises.push(this.SetSetting(key, value, contextUser));
+        }
+        const results = await Promise.all(savePromises);
+        const failedCount = results.filter((r) => !r).length;
+        if (failedCount > 0) {
+            console.warn(`UserInfoEngine.FlushPendingSettings: ${failedCount} of ${results.length} settings failed to save`);
+        }
+    }
+    /**
+     * Check if there are any pending debounced settings waiting to be saved.
+     */
+    get HasPendingSettings() {
+        return this._pendingSettings.size > 0;
+    }
+    /**
+     * Get the number of pending debounced settings.
+     */
+    get PendingSettingsCount() {
+        return this._pendingSettings.size;
+    }
     /**
      * Get unread notifications for the current user
      */