ocr-provenance-mcp 1.0.0

package/dist/server/state.js

@@ -0,0 +1,424 @@
+/**
+ * MCP Server State Management
+ *
+ * Manages global server state including current database connection and configuration.
+ * FAIL FAST: All state access throws immediately if preconditions not met.
+ *
+ * @module server/state
+ */
+import { DatabaseService } from '../services/storage/database/index.js';
+import { VectorService } from '../services/storage/vector.js';
+import { DEFAULT_STORAGE_PATH } from '../services/storage/database/helpers.js';
+import { databaseNotSelectedError, databaseNotFoundError, databaseAlreadyExistsError, } from './errors.js';
+import { loadPersistedConfig } from '../utils/config-persistence.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEFAULT CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Default server configuration
+ */
+const defaultConfig = {
+    defaultStoragePath: DEFAULT_STORAGE_PATH,
+    defaultOCRMode: 'balanced',
+    maxConcurrent: 3,
+    embeddingBatchSize: 32,
+    embeddingDevice: 'auto',
+    chunkSize: 2000,
+    chunkOverlapPercent: 10,
+    maxChunkSize: 8000,
+    autoClusterEnabled: false,
+    autoClusterThreshold: 10,
+    autoClusterAlgorithm: 'hdbscan',
+    imageOptimization: {
+        enabled: true,
+        ocrMaxWidth: 4800,
+        vlmMaxDimension: 2048,
+        vlmSkipBelowSize: 50,
+        vlmMinRelevance: 0.3,
+        vlmSkipLogosIcons: true,
+    },
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// GLOBAL STATE
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Global server state
+ * Mutable state for current database and configuration
+ */
+export const state = {
+    currentDatabase: null,
+    currentDatabaseName: null,
+    config: { ...defaultConfig },
+};
+/**
+ * Cached VectorService instance - cleared on database change
+ */
+let _cachedVectorService = null;
+/**
+ * Generation counter - incremented on every database switch/clear.
+ */
+let _dbGeneration = 0;
+/**
+ * Active operation counter - tracks in-flight async database operations.
+ * selectDatabase() and clearDatabase() refuse to proceed when > 0.
+ */
+let _activeOperations = 0;
+/**
+ * Require database to be selected - FAIL FAST if not
+ *
+ * @returns Database service, vector service, and generation counter
+ * @throws MCPError with DATABASE_NOT_SELECTED if no database is selected
+ */
+export function requireDatabase() {
+    if (!state.currentDatabase) {
+        throw databaseNotSelectedError();
+    }
+    if (!_cachedVectorService) {
+        _cachedVectorService = new VectorService(state.currentDatabase.getConnection());
+    }
+    return { db: state.currentDatabase, vector: _cachedVectorService, generation: _dbGeneration };
+}
+/**
+ * Validate that the database generation matches the expected value.
+ *
+ * The generation counter increments on every database switch/clear. A mismatch
+ * means the database was switched between the time a caller obtained the
+ * generation and the time it validates -- indicating a race condition where
+ * the caller's database reference is stale.
+ *
+ * Callers can optionally use this at critical points (e.g., before writing
+ * results back to the database) to detect and fail fast on stale references.
+ *
+ * @param expectedGeneration - The generation value obtained from requireDatabase()
+ * @throws Error if the current generation does not match
+ */
+export function validateGeneration(expectedGeneration) {
+    if (_dbGeneration !== expectedGeneration) {
+        throw new Error(`Database generation mismatch: expected ${expectedGeneration}, current ${_dbGeneration}. ` +
+            `The database was switched during this operation. Retry with the current database.`);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// OPERATION TRACKING (H-1, H-2, M-9)
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Begin tracking an in-flight database operation.
+ *
+ * Increments the active operation counter and returns the current generation.
+ * While any operations are active, selectDatabase() and clearDatabase() will
+ * throw to prevent database switches during async work.
+ *
+ * @returns Current database generation for later validation
+ * @throws MCPError if no database is selected
+ */
+export function beginDatabaseOperation() {
+    if (!state.currentDatabase) {
+        throw databaseNotSelectedError();
+    }
+    _activeOperations++;
+    return _dbGeneration;
+}
+/**
+ * End tracking an in-flight database operation.
+ *
+ * Decrements the active operation counter. Counter never goes below 0.
+ */
+export function endDatabaseOperation() {
+    if (_activeOperations > 0) {
+        _activeOperations--;
+    }
+}
+/**
+ * Get the number of active database operations (for diagnostics/testing).
+ */
+export function getActiveOperationCount() {
+    return _activeOperations;
+}
+/**
+ * Execute an async function within a tracked database operation scope.
+ *
+ * Calls beginDatabaseOperation() before the function and endDatabaseOperation()
+ * in a finally block, guaranteeing the counter is decremented even on error.
+ * Also validates the generation after the function completes to detect any
+ * mid-operation database switch.
+ *
+ * Use this for async tool handlers that do database writes across multiple
+ * await points. Read-only synchronous handlers do not need this wrapper
+ * because the event loop does not yield.
+ *
+ * @param fn - Async function receiving DatabaseServices
+ * @returns The result of fn
+ * @throws MCPError if no database is selected
+ * @throws Error if the database was switched during the operation
+ */
+export async function withDatabaseOperation(fn) {
+    const generation = beginDatabaseOperation();
+    try {
+        const services = requireDatabase();
+        const result = await fn(services);
+        validateGeneration(generation);
+        return result;
+    }
+    finally {
+        endDatabaseOperation();
+    }
+}
+/**
+ * Check if a database is currently selected
+ */
+export function hasDatabase() {
+    return state.currentDatabase !== null;
+}
+/**
+ * Get current database name or null
+ */
+export function getCurrentDatabaseName() {
+    return state.currentDatabaseName;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// DATABASE MANAGEMENT
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Apply persisted config from a database's config_json column.
+ *
+ * Called after database selection to restore config values that were
+ * saved by handleConfigSet in a previous session.
+ *
+ * @param db - The newly opened DatabaseService
+ */
+function applyPersistedConfig(db) {
+    try {
+        const persisted = loadPersistedConfig(db.getConnection());
+        if (Object.keys(persisted).length > 0) {
+            // Apply each persisted config key using updateConfig
+            const CONFIG_KEY_TO_STATE = {
+                datalab_default_mode: 'defaultOCRMode',
+                datalab_max_concurrent: 'maxConcurrent',
+                embedding_batch_size: 'embeddingBatchSize',
+                embedding_device: 'embeddingDevice',
+                chunk_size: 'chunkSize',
+                chunk_overlap_percent: 'chunkOverlapPercent',
+                max_chunk_size: 'maxChunkSize',
+                auto_cluster_enabled: 'autoClusterEnabled',
+                auto_cluster_threshold: 'autoClusterThreshold',
+                auto_cluster_algorithm: 'autoClusterAlgorithm',
+            };
+            const updates = {};
+            for (const [key, value] of Object.entries(persisted)) {
+                const stateKey = CONFIG_KEY_TO_STATE[key];
+                if (stateKey) {
+                    updates[stateKey] = value;
+                }
+            }
+            if (Object.keys(updates).length > 0) {
+                updateConfig(updates);
+                console.error(`[state] Loaded ${Object.keys(updates).length} persisted config value(s) from database`);
+            }
+        }
+    }
+    catch (error) {
+        console.error(`[state] Failed to apply persisted config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Select a database by name - opens connection and sets as current
+ *
+ * FAIL FAST: Throws immediately if database doesn't exist or if operations
+ * are in-flight (H-2 guard). Uses atomic swap (M-9 fix): opens new DB first,
+ * then swaps state, then closes old DB -- no null window.
+ *
+ * @param name - Database name to select
+ * @param storagePath - Optional storage path override
+ * @throws MCPError with DATABASE_NOT_FOUND if database doesn't exist
+ * @throws Error if database operations are in-flight
+ */
+export function selectDatabase(name, storagePath) {
+    const path = storagePath ?? state.config.defaultStoragePath;
+    // H-2: Refuse to switch while async operations are in-flight
+    if (_activeOperations > 0) {
+        throw new Error(`Cannot switch databases while ${_activeOperations} operation(s) are in-flight. ` +
+            `Wait for active operations to complete before switching databases.`);
+    }
+    // Verify database exists BEFORE any state changes - FAIL FAST
+    // If the new DB doesn't exist, the old connection stays open and usable.
+    if (!DatabaseService.exists(name, path)) {
+        throw databaseNotFoundError(name, path);
+    }
+    // M-9: Atomic swap - open new FIRST, then swap state, then close old.
+    // This eliminates the null window where state.currentDatabase is null
+    // between closing old and opening new.
+    const newDb = DatabaseService.open(name, path);
+    const oldDb = state.currentDatabase;
+    // Swap state atomically (single tick - no await between these assignments)
+    state.currentDatabase = newDb;
+    state.currentDatabaseName = name;
+    _cachedVectorService = null;
+    _dbGeneration++;
+    // Close old connection AFTER state points to new DB
+    if (oldDb) {
+        oldDb.close();
+    }
+    // Load persisted config from the database (if any)
+    applyPersistedConfig(newDb);
+}
+/**
+ * Create a new database and optionally select it
+ *
+ * FAIL FAST: Throws immediately if database already exists
+ *
+ * @param name - Database name to create
+ * @param description - Optional description
+ * @param storagePath - Optional storage path override
+ * @param autoSelect - Whether to select the database after creation (default: true)
+ * @returns The created database service
+ * @throws MCPError with DATABASE_ALREADY_EXISTS if database exists
+ */
+export function createDatabase(name, description, storagePath, autoSelect = true) {
+    const path = storagePath ?? state.config.defaultStoragePath;
+    // Check if database already exists - FAIL FAST
+    if (DatabaseService.exists(name, path)) {
+        throw databaseAlreadyExistsError(name);
+    }
+    // Create the database
+    const db = DatabaseService.create(name, description, path);
+    if (autoSelect) {
+        // H-3: Refuse to switch while async operations are in-flight
+        if (_activeOperations > 0) {
+            // Close the newly created DB since we can't switch to it
+            db.close();
+            throw new Error(`Cannot auto-select newly created database "${name}" while ${_activeOperations} operation(s) are in-flight. ` +
+                `Wait for active operations to complete, then select the database manually.`);
+        }
+        // Close any existing connection first
+        if (state.currentDatabase) {
+            state.currentDatabase.close();
+        }
+        _cachedVectorService = null;
+        _dbGeneration++;
+        state.currentDatabase = db;
+        state.currentDatabaseName = name;
+    }
+    // When autoSelect=false, return the open DB -- caller manages lifecycle.
+    // Previously the DB was closed here making the returned service dead.
+    return db;
+}
+/**
+ * Delete a database
+ *
+ * FAIL FAST: Throws if database doesn't exist
+ *
+ * @param name - Database name to delete
+ * @param storagePath - Optional storage path override
+ * @throws MCPError with DATABASE_NOT_FOUND if database doesn't exist
+ */
+export function deleteDatabase(name, storagePath) {
+    const path = storagePath ?? state.config.defaultStoragePath;
+    // Verify database exists - FAIL FAST
+    if (!DatabaseService.exists(name, path)) {
+        throw databaseNotFoundError(name, path);
+    }
+    // If this is the current database, clear state first
+    if (state.currentDatabaseName === name) {
+        clearDatabase();
+    }
+    // Delete the database
+    DatabaseService.delete(name, path);
+}
+/**
+ * Clear current database selection - closes connection.
+ *
+ * FAIL FAST: Throws if async operations are in-flight (H-2 guard).
+ * The forceClose parameter bypasses the guard for internal use only
+ * (resetState in tests, process exit cleanup).
+ *
+ * @param forceClose - Skip operation guard (internal use only)
+ * @throws Error if database operations are in-flight and forceClose is false
+ */
+export function clearDatabase(forceClose = false) {
+    // H-2: Refuse to clear while async operations are in-flight
+    if (!forceClose && _activeOperations > 0) {
+        throw new Error(`Cannot clear database while ${_activeOperations} operation(s) are in-flight. ` +
+            `Wait for active operations to complete before clearing the database.`);
+    }
+    if (state.currentDatabase) {
+        state.currentDatabase.close();
+        state.currentDatabase = null;
+        state.currentDatabaseName = null;
+        _cachedVectorService = null;
+        _dbGeneration++;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONFIGURATION
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Get current server configuration
+ */
+export function getConfig() {
+    return { ...state.config };
+}
+/**
+ * Update server configuration (deep merges nested objects like imageOptimization)
+ */
+export function updateConfig(updates) {
+    // Deep merge imageOptimization if both existing and update have it
+    if (updates.imageOptimization && state.config.imageOptimization) {
+        updates = {
+            ...updates,
+            imageOptimization: {
+                ...state.config.imageOptimization,
+                ...updates.imageOptimization,
+            },
+        };
+    }
+    state.config = { ...state.config, ...updates };
+}
+/**
+ * Reset configuration to defaults
+ */
+export function resetConfig() {
+    state.config = { ...defaultConfig };
+}
+/**
+ * Get default storage path
+ */
+export function getDefaultStoragePath() {
+    return state.config.defaultStoragePath;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// STATE RESET (FOR TESTING)
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Reset all server state - ONLY USE IN TESTS
+ *
+ * Uses forceClose=true to bypass the operation guard since tests
+ * need to reset state unconditionally between test cases.
+ */
+export function resetState() {
+    clearDatabase(/* forceClose */ true);
+    _cachedVectorService = null;
+    _dbGeneration = 0;
+    _activeOperations = 0;
+    state.config = { ...defaultConfig };
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// PROCESS EXIT CLEANUP
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * L-5: Clean up database connections on process exit.
+ * Ensures WAL/SHM files are properly checkpointed.
+ */
+process.on('exit', () => {
+    if (state.currentDatabase) {
+        try {
+            state.currentDatabase.close();
+        }
+        catch (error) {
+            console.error('[state] database close on exit failed:', error instanceof Error ? error.message : String(error));
+            // Continue exit cleanup despite error
+        }
+        state.currentDatabase = null;
+        state.currentDatabaseName = null;
+    }
+});
+//# sourceMappingURL=state.js.map

package/dist/server/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/server/state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAGrE,kFAAkF;AAClF,wBAAwB;AACxB,kFAAkF;AAElF;;GAEG;AACH,MAAM,aAAa,GAAiB;IAClC,kBAAkB,EAAE,oBAAoB;IACxC,cAAc,EAAE,UAAU;IAC1B,aAAa,EAAE,CAAC;IAChB,kBAAkB,EAAE,EAAE;IACtB,eAAe,EAAE,MAAM;IACvB,SAAS,EAAE,IAAI;IACf,mBAAmB,EAAE,EAAE;IACvB,YAAY,EAAE,IAAI;IAClB,kBAAkB,EAAE,KAAK;IACzB,oBAAoB,EAAE,EAAE;IACxB,oBAAoB,EAAE,SAAS;IAC/B,iBAAiB,EAAE;QACjB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,IAAI;QACjB,eAAe,EAAE,IAAI;QACrB,gBAAgB,EAAE,EAAE;QACpB,eAAe,EAAE,GAAG;QACpB,iBAAiB,EAAE,IAAI;KACxB;CACF,CAAC;AAEF,kFAAkF;AAClF,eAAe;AACf,kFAAkF;AAElF;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAgB;IAChC,eAAe,EAAE,IAAI;IACrB,mBAAmB,EAAE,IAAI;IACzB,MAAM,EAAE,EAAE,GAAG,aAAa,EAAE;CAC7B,CAAC;AAgBF;;GAEG;AACH,IAAI,oBAAoB,GAAyB,IAAI,CAAC;AAEtD;;GAEG;AACH,IAAI,aAAa,GAAG,CAAC,CAAC;AAEtB;;;GAGG;AACH,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;QAC3B,MAAM,wBAAwB,EAAE,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,oBAAoB,GAAG,IAAI,aAAa,CAAC,KAAK,CAAC,eAAe,CAAC,aAAa,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,eAAe,EAAE,MAAM,EAAE,oBAAoB,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC;AAChG,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,kBAA0B;IAC3D,IAAI,aAAa,KAAK,kBAAkB,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,0CAA0C,kBAAkB,aAAa,aAAa,IAAI;YACxF,mFAAmF,CACtF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,qCAAqC;AACrC,kFAAkF;AAElF;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB;IACpC,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;QAC3B,MAAM,wBAAwB,EAAE,CAAC;IACnC,CAAC;IACD,iBAAiB,EAAE,CAAC;IACpB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;QAC1B,iBAAiB,EAAE,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAA8C;IAE9C,MAAM,UAAU,GAAG,sBAAsB,EAAE,CAAC;IAC5C,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC;QAClC,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,oBAAoB,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,KAAK,CAAC,eAAe,KAAK,IAAI,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,CAAC,mBAAmB,CAAC;AACnC,CAAC;AAED,kFAAkF;AAClF,sBAAsB;AACtB,kFAAkF;AAElF;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAAC,EAAmB;IAC/C,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,mBAAmB,CAAC,EAAE,CAAC,aAAa,EAAE,CAAC,CAAC;QAC1D,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtC,qDAAqD;YACrD,MAAM,mBAAmB,GAA2B;gBAClD,oBAAoB,EAAE,gBAAgB;gBACtC,sBAAsB,EAAE,eAAe;gBACvC,oBAAoB,EAAE,oBAAoB;gBAC1C,gBAAgB,EAAE,iBAAiB;gBACnC,UAAU,EAAE,WAAW;gBACvB,qBAAqB,EAAE,qBAAqB;gBAC5C,cAAc,EAAE,cAAc;gBAC9B,oBAAoB,EAAE,oBAAoB;gBAC1C,sBAAsB,EAAE,sBAAsB;gBAC9C,sBAAsB,EAAE,sBAAsB;aAC/C,CAAC;YAEF,MAAM,OAAO,GAA4B,EAAE,CAAC;YAC5C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;gBACrD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;gBAC1C,IAAI,QAAQ,EAAE,CAAC;oBACb,OAAO,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC;gBAC5B,CAAC;YACH,CAAC;YAED,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,YAAY,CAAC,OAAgC,CAAC,CAAC;gBAC/C,OAAO,CAAC,KAAK,CACX,kBAAkB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,0CAA0C,CACxF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CACX,6CAA6C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACtG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,WAAoB;IAC/D,MAAM,IAAI,GAAG,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC,kBAAkB,CAAC;IAE5D,6DAA6D;IAC7D,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,iCAAiC,iBAAiB,+BAA+B;YAC/E,oEAAoE,CACvE,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,yEAAyE;IACzE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,sEAAsE;IACtE,sEAAsE;IACtE,uCAAuC;IACvC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,eAAe,CAAC;IAEpC,2EAA2E;IAC3E,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC;IAC9B,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC;IACjC,oBAAoB,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,CAAC;IAEhB,oDAAoD;IACpD,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAED,mDAAmD;IACnD,oBAAoB,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,WAAoB,EACpB,WAAoB,EACpB,aAAsB,IAAI;IAE1B,MAAM,IAAI,GAAG,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC,kBAAkB,CAAC;IAE5D,+CAA+C;IAC/C,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,sBAAsB;IACtB,MAAM,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IAE3D,IAAI,UAAU,EAAE,CAAC;QACf,6DAA6D;QAC7D,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;YAC1B,yDAAyD;YACzD,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,8CAA8C,IAAI,WAAW,iBAAiB,+BAA+B;gBAC3G,4EAA4E,CAC/E,CAAC;QACJ,CAAC;QAED,sCAAsC;QACtC,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;YAC1B,KAAK,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAChC,CAAC;QACD,oBAAoB,GAAG,IAAI,CAAC;QAC5B,aAAa,EAAE,CAAC;QAChB,KAAK,CAAC,eAAe,GAAG,EAAE,CAAC;QAC3B,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC;IACnC,CAAC;IACD,yEAAyE;IACzE,sEAAsE;IAEtE,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,WAAoB;IAC/D,MAAM,IAAI,GAAG,WAAW,IAAI,KAAK,CAAC,MAAM,CAAC,kBAAkB,CAAC;IAE5D,qCAAqC;IACrC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,qDAAqD;IACrD,IAAI,KAAK,CAAC,mBAAmB,KAAK,IAAI,EAAE,CAAC;QACvC,aAAa,EAAE,CAAC;IAClB,CAAC;IAED,sBAAsB;IACtB,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,aAAsB,KAAK;IACvD,4DAA4D;IAC5D,IAAI,CAAC,UAAU,IAAI,iBAAiB,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,+BAA+B,iBAAiB,+BAA+B;YAC7E,sEAAsE,CACzE,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;QAC1B,KAAK,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC9B,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC;QAC7B,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC;QACjC,oBAAoB,GAAG,IAAI,CAAC;QAC5B,aAAa,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,kFAAkF;AAClF,gBAAgB;AAChB,kFAAkF;AAElF;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAA8B;IACzD,mEAAmE;IACnE,IAAI,OAAO,CAAC,iBAAiB,IAAI,KAAK,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAChE,OAAO,GAAG;YACR,GAAG,OAAO;YACV,iBAAiB,EAAE;gBACjB,GAAG,KAAK,CAAC,MAAM,CAAC,iBAAiB;gBACjC,GAAG,OAAO,CAAC,iBAAiB;aAC7B;SACF,CAAC;IACJ,CAAC;IACD,KAAK,CAAC,MAAM,GAAG,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW;IACzB,KAAK,CAAC,MAAM,GAAG,EAAE,GAAG,aAAa,EAAE,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,KAAK,CAAC,MAAM,CAAC,kBAAkB,CAAC;AACzC,CAAC;AAED,kFAAkF;AAClF,4BAA4B;AAC5B,kFAAkF;AAElF;;;;;GAKG;AACH,MAAM,UAAU,UAAU;IACxB,aAAa,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACrC,oBAAoB,GAAG,IAAI,CAAC;IAC5B,aAAa,GAAG,CAAC,CAAC;IAClB,iBAAiB,GAAG,CAAC,CAAC;IACtB,KAAK,CAAC,MAAM,GAAG,EAAE,GAAG,aAAa,EAAE,CAAC;AACtC,CAAC;AAED,kFAAkF;AAClF,uBAAuB;AACvB,kFAAkF;AAElF;;;GAGG;AACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;IACtB,IAAI,KAAK,CAAC,eAAe,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,KAAK,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CACX,wCAAwC,EACxC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;YACF,sCAAsC;QACxC,CAAC;QACD,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC;QAC7B,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC;IACnC,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/server/transports/http-transport.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Streamable HTTP Transport for MCP
+ *
+ * Implements MCP Streamable HTTP transport (2025-03-26):
+ * - HTTP POST for client->server messages
+ * - SSE for server->client streaming
+ * - Mcp-Session-Id header for session management
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module server/transports/http-transport
+ */
+export interface HttpTransportConfig {
+    port: number;
+    sessionTtlMs: number;
+}
+export declare class HttpTransport {
+    private sessions;
+    private server;
+    private config;
+    private cleanupTimer;
+    private messageHandler;
+    constructor(config?: Partial<HttpTransportConfig>);
+    /** Set the handler for incoming messages */
+    onMessage(handler: (sessionId: string, message: unknown) => Promise<unknown>): void;
+    /** Start the HTTP server */
+    start(): Promise<void>;
+    /** Stop the HTTP server */
+    stop(): Promise<void>;
+    private handlePost;
+    private handleSSE;
+    /** Send SSE event to a session */
+    sendEvent(sessionId: string, event: string, data: unknown): void;
+    private cleanupExpiredSessions;
+    getSessionCount(): number;
+}
+//# sourceMappingURL=http-transport.d.ts.map

package/dist/server/transports/http-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-transport.d.ts","sourceRoot":"","sources":["../../../src/server/transports/http-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAaD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,cAAc,CAA4E;gBAEtF,MAAM,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC;IAOjD,4CAA4C;IAC5C,SAAS,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAInF,4BAA4B;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmD5B,2BAA2B;IACrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAeb,UAAU;YAiDV,SAAS;IAoCvB,kCAAkC;IAClC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAchE,OAAO,CAAC,sBAAsB;IAiB9B,eAAe,IAAI,MAAM;CAG1B"}

package/dist/server/transports/http-transport.js

@@ -0,0 +1,204 @@
+/**
+ * Streamable HTTP Transport for MCP
+ *
+ * Implements MCP Streamable HTTP transport (2025-03-26):
+ * - HTTP POST for client->server messages
+ * - SSE for server->client streaming
+ * - Mcp-Session-Id header for session management
+ *
+ * CRITICAL: NEVER use console.log() - stdout is reserved for JSON-RPC protocol.
+ *
+ * @module server/transports/http-transport
+ */
+import http from 'http';
+import { randomUUID } from 'crypto';
+// ═══════════════════════════════════════════════════════════════════════════════
+// HTTP TRANSPORT
+// ═══════════════════════════════════════════════════════════════════════════════
+export class HttpTransport {
+    sessions = new Map();
+    server = null;
+    config;
+    cleanupTimer = null;
+    messageHandler = null;
+    constructor(config) {
+        this.config = {
+            port: config?.port ?? (Number(process.env.MCP_HTTP_PORT) || 3100),
+            sessionTtlMs: config?.sessionTtlMs ?? (Number(process.env.MCP_SESSION_TTL) || 3600) * 1000,
+        };
+    }
+    /** Set the handler for incoming messages */
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    /** Start the HTTP server */
+    async start() {
+        this.server = http.createServer(async (req, res) => {
+            // CORS headers
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+            res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            try {
+                if (req.method === 'POST' && req.url === '/mcp') {
+                    await this.handlePost(req, res);
+                }
+                else if (req.method === 'GET' && req.url === '/mcp/sse') {
+                    await this.handleSSE(req, res);
+                }
+                else if (req.method === 'GET' && req.url === '/health') {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ status: 'ok', sessions: this.sessions.size }));
+                }
+                else {
+                    res.writeHead(404);
+                    res.end('Not found');
+                }
+            }
+            catch (error) {
+                console.error('[HttpTransport] Request error:', error instanceof Error ? error.message : String(error));
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Internal server error' }));
+                }
+            }
+        });
+        await new Promise((resolve, reject) => {
+            this.server.listen(this.config.port, () => {
+                console.error(`[HttpTransport] Listening on port ${this.config.port}`);
+                resolve();
+            });
+            this.server.on('error', reject);
+        });
+        // Session cleanup every 60s
+        this.cleanupTimer = setInterval(() => this.cleanupExpiredSessions(), 60000);
+        this.cleanupTimer.unref();
+    }
+    /** Stop the HTTP server */
+    async stop() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        if (this.server) {
+            await new Promise((resolve) => {
+                this.server.close(() => resolve());
+            });
+            this.server = null;
+        }
+        this.sessions.clear();
+        console.error('[HttpTransport] Stopped');
+    }
+    async handlePost(req, res) {
+        // Get or create session
+        let sessionId = req.headers['mcp-session-id'];
+        if (sessionId && !this.sessions.has(sessionId)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Invalid session ID' }));
+            return;
+        }
+        if (!sessionId) {
+            sessionId = randomUUID();
+            this.sessions.set(sessionId, {
+                id: sessionId,
+                createdAt: Date.now(),
+                lastActivity: Date.now(),
+                sseResponse: null,
+            });
+        }
+        const session = this.sessions.get(sessionId);
+        session.lastActivity = Date.now();
+        // Read body
+        const body = await new Promise((resolve, reject) => {
+            let data = '';
+            req.on('data', (chunk) => {
+                data += chunk;
+            });
+            req.on('end', () => resolve(data));
+            req.on('error', reject);
+        });
+        if (!this.messageHandler) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'No message handler registered' }));
+            return;
+        }
+        const message = JSON.parse(body);
+        const response = await this.messageHandler(sessionId, message);
+        res.writeHead(200, {
+            'Content-Type': 'application/json',
+            'Mcp-Session-Id': sessionId,
+        });
+        res.end(JSON.stringify(response));
+    }
+    async handleSSE(req, res) {
+        const sessionId = req.headers['mcp-session-id'];
+        if (!sessionId || !this.sessions.has(sessionId)) {
+            res.writeHead(400);
+            res.end('Invalid session');
+            return;
+        }
+        const session = this.sessions.get(sessionId);
+        session.lastActivity = Date.now();
+        session.sseResponse = res;
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'Mcp-Session-Id': sessionId,
+        });
+        // Keep-alive ping every 30s
+        const keepAlive = setInterval(() => {
+            try {
+                res.write(': ping\n\n');
+            }
+            catch {
+                clearInterval(keepAlive);
+            }
+        }, 30000);
+        req.on('close', () => {
+            clearInterval(keepAlive);
+            if (session.sseResponse === res) {
+                session.sseResponse = null;
+            }
+        });
+    }
+    /** Send SSE event to a session */
+    sendEvent(sessionId, event, data) {
+        const session = this.sessions.get(sessionId);
+        if (session?.sseResponse) {
+            try {
+                session.sseResponse.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+            }
+            catch (error) {
+                console.error(`[HttpTransport] SSE send failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+                session.sseResponse = null;
+            }
+        }
+    }
+    cleanupExpiredSessions() {
+        const now = Date.now();
+        for (const [id, session] of this.sessions) {
+            if (now - session.lastActivity > this.config.sessionTtlMs) {
+                console.error(`[HttpTransport] Expiring session ${id}`);
+                if (session.sseResponse) {
+                    try {
+                        session.sseResponse.end();
+                    }
+                    catch {
+                        /* ignore close errors */
+                    }
+                }
+                this.sessions.delete(id);
+            }
+        }
+    }
+    getSessionCount() {
+        return this.sessions.size;
+    }
+}
+//# sourceMappingURL=http-transport.js.map