mcp-compression-proxy 1.0.2 → 1.1.0

package/dist/mcp/client-manager.d.ts

@@ -1,13 +1,35 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import type { MCPServerConfig, ServerStatus } from '../types/index.js';
+import type { ConnectionLifecycleDefaults, MCPServerConfig, ServerStatus } from '../types/index.js';
 import type { Logger } from 'pino';
+import type { ConfigResult } from '../config/loader.js';
+export declare const DEFAULT_SOFT_MAX_CONNECTION_AGE_SECONDS = 3600;
+export declare const DEFAULT_HARD_MAX_CONNECTION_AGE_SECONDS = 28800;
+export interface ManagedClientContext {
+    client: Client;
+    generation: number;
+    /** Record a failed operation without recycling an otherwise healthy backend. */
+    markFailure(reason: string): void;
+    /**
+     * Stop routing new work to this exact generation. Active calls finish before
+     * the backend closes, and the next acquisition starts a replacement.
+     */
+    invalidate(reason: string): void;
+}
 /**
- * Manages connections to multiple MCP servers
+ * Manages backend MCP processes as leased connection generations.
+ *
+ * READY connections may be leased by concurrent callers. Soft-expired
+ * connections are replaced on the next acquisition. Hard-expired connections
+ * enter DRAINING immediately and close after their final lease is released.
  */
 export declare class MCPClientManager {
-    private connections;
-    private logger;
+    private readonly slots;
+    private readonly logger;
     private readonly DEFAULT_TIMEOUT_MS;
+    private readonly RECONNECT_BASE_MS;
+    private readonly RECONNECT_MAX_MS;
+    private configWatchTimer?;
+    private shuttingDown;
     constructor(logger: Logger);
     /**
      * Wraps a promise with a timeout.
@@ -21,45 +43,106 @@ export declare class MCPClientManager {
      *
      * The stdio transport only inherits a small allowlist of "safe" variables
      * (PATH, HOME, ...), so anything else the user exported - API tokens, base
-     * URLs - never reaches the child unless it is passed explicitly. By default
-     * we forward the proxy's full environment, matching what users expect from a
-     * process they launched themselves. `inheritEnv` narrows that when a server
-     * should not see unrelated secrets.
+     * URLs - never reaches the child unless it is passed explicitly.
      */
     private buildEnv;
+    private resolveConfig;
     /**
-     * Initialize and connect to all configured MCP servers
-     * @param servers - Server configurations to initialize
-     * @param defaultTimeout - Optional default timeout in seconds (overrides class default)
-     * @param defaultInheritEnv - Optional default env inheritance policy (overridden per-server)
+     * Pick the transport for a server.
+     *
+     * `url` is the whole discriminator - the config schema makes `command` and
+     * `url` mutually exclusive, so there is nothing else to inspect. `buildEnv`
+     * falls away on the remote branch because there is no child process to hand
+     * an environment to; credentials travel as headers instead.
      */
-    initializeServers(servers: MCPServerConfig[], defaultTimeout?: number, defaultInheritEnv?: boolean | string[]): Promise<void>;
+    private buildTransport;
     /**
-     * Connect to a single MCP server with timeout
+     * Initialize all configured slots and eagerly start their first generation.
+     * A failed initial connection remains configured and is retried lazily later.
      */
-    private connectToServer;
+    initializeServers(servers: MCPServerConfig[], defaultTimeout?: number, defaultInheritEnv?: boolean | string[], lifecycleDefaults?: ConnectionLifecycleDefaults): Promise<void>;
+    private createConnection;
     /**
-     * Get a connected client by server name
+     * React to a backend connection going away.
+     *
+     * `connection` identifies which generation closed: an old transport finishing
+     * its teardown after a reconnect already installed a replacement must not
+     * mark the live connection down.
      */
-    getClient(serverName: string): Client | undefined;
+    private handleDrop;
     /**
-     * Get all connected clients
+     * Queue a reconnect with capped, jittered exponential backoff.
+     *
+     * Attempts are uncapped on purpose - a backend can be down for hours (a
+     * laptop asleep, a container being rebuilt) and should still come back
+     * without the operator restarting their whole MCP client. The jitter keeps
+     * several backends behind the same dead machine from retrying in lockstep.
      */
-    getConnectedClients(): Array<{
-        name: string;
-        client: Client;
-    }>;
+    private scheduleReconnect;
+    private reconnect;
     /**
-     * Get status of all servers
+     * Bring the live connections in line with a freshly loaded server list.
+     *
+     * Servers that vanished or changed are torn down, servers that appeared are
+     * connected, and everything untouched keeps its existing connection - an
+     * edit to one entry must not interrupt the other backends.
      */
-    getServerStatuses(): ServerStatus[];
+    reconcile(servers: MCPServerConfig[], defaultTimeout?: number, defaultInheritEnv?: boolean | string[], lifecycleDefaults?: ConnectionLifecycleDefaults): Promise<void>;
     /**
-     * Check if at least one server is connected
+     * Close a connection the operator has removed or replaced.
+     *
+     * Order matters: the queued retry dies first and the close is claimed as
+     * ours *before* close() runs, so handleDrop() cannot resurrect a server that
+     * was deliberately taken out of servers.json.
      */
-    hasConnectedServers(): boolean;
+    private teardownSlot;
+    private lifecycleDefaultsFromConfig;
+    private cancelReconnect;
     /**
-     * Disconnect from all servers
+     * Poll the config for server list changes and apply them live.
+     *
+     * Polling rather than fs.watch: watchers fire duplicate events and stop
+     * working entirely once a file is replaced by write-temp-then-rename, which
+     * is how most editors and jq-style tools save. Two stats every few seconds
+     * are cheaper than the bug reports that would follow.
+     *
+     * `loadConfig` is injected rather than imported so this stays testable
+     * without fixture files, matching the loader injection in StatsService.
+     */
+    startConfigWatch(loadConfig: () => ConfigResult, intervalMs?: number, onConfigLoaded?: (config: NonNullable<ConfigResult>) => void): void;
+    /**
+     * Single-flight connection creation. Concurrent callers share this promise.
+     */
+    private ensureConnection;
+    private scheduleHardExpiry;
+    private isSoftExpired;
+    private beginDrain;
+    private closeConnection;
+    private acquireConnection;
+    private releaseConnection;
+    private recordSuccess;
+    private recordFailure;
+    /**
+     * Execute work under a lease. Invalidating the context drains this exact
+     * generation, so concurrent recovery cannot accidentally close a newer one.
+     */
+    withClient<T>(serverName: string, operation: (context: ManagedClientContext) => Promise<T>): Promise<T>;
+    getConfiguredServerNames(): string[];
+    getAuthRecoveryPolicy(serverName: string): {
+        authErrorPatterns: string[];
+        authRetryTools: string[];
+    };
+    /**
+     * Compatibility accessors. Production operations should use withClient so
+     * lifecycle age, active leases, and health are tracked.
      */
+    getClient(serverName: string): Client | undefined;
+    getConnectedClients(): Array<{
+        name: string;
+        client: Client;
+    }>;
+    getServerStatuses(): ServerStatus[];
+    hasConnectedServers(): boolean;
     disconnectAll(): Promise<void>;
 }
 //# sourceMappingURL=client-manager.d.ts.map