mcp-compression-proxy 1.0.0

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

@@ -0,0 +1,65 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { MCPServerConfig, ServerStatus } from '../types/index.js';
+import type { Logger } from 'pino';
+/**
+ * Manages connections to multiple MCP servers
+ */
+export declare class MCPClientManager {
+    private connections;
+    private logger;
+    private readonly DEFAULT_TIMEOUT_MS;
+    constructor(logger: Logger);
+    /**
+     * Wraps a promise with a timeout.
+     *
+     * The timer is always cleared - leaving it pending keeps the Node event loop
+     * alive for the full duration even after a fast connection succeeds.
+     */
+    private withTimeout;
+    /**
+     * Build the environment handed to a spawned server.
+     *
+     * 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.
+     */
+    private buildEnv;
+    /**
+     * 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)
+     */
+    initializeServers(servers: MCPServerConfig[], defaultTimeout?: number, defaultInheritEnv?: boolean | string[]): Promise<void>;
+    /**
+     * Connect to a single MCP server with timeout
+     */
+    private connectToServer;
+    /**
+     * Get a connected client by server name
+     */
+    getClient(serverName: string): Client | undefined;
+    /**
+     * Get all connected clients
+     */
+    getConnectedClients(): Array<{
+        name: string;
+        client: Client;
+    }>;
+    /**
+     * Get status of all servers
+     */
+    getServerStatuses(): ServerStatus[];
+    /**
+     * Check if at least one server is connected
+     */
+    hasConnectedServers(): boolean;
+    /**
+     * Disconnect from all servers
+     */
+    disconnectAll(): Promise<void>;
+}
+//# sourceMappingURL=client-manager.d.ts.map

package/dist/mcp/client-manager.js

@@ -0,0 +1,197 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SERVER_NAME, VERSION } from '../version.js';
+/**
+ * Manages connections to multiple MCP servers
+ */
+export class MCPClientManager {
+    connections = new Map();
+    logger;
+    DEFAULT_TIMEOUT_MS = 30000; // 30 seconds default timeout
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Wraps a promise with a timeout.
+     *
+     * The timer is always cleared - leaving it pending keeps the Node event loop
+     * alive for the full duration even after a fast connection succeeds.
+     */
+    async withTimeout(promise, timeoutMs) {
+        let timer;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        reject(new Error(`Connection timeout after ${timeoutMs}ms`));
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+    /**
+     * Build the environment handed to a spawned server.
+     *
+     * 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.
+     */
+    buildEnv(config) {
+        const inherit = config.inheritEnv ?? true;
+        // `false` defers entirely to the transport's safe defaults.
+        if (inherit === false) {
+            return config.env;
+        }
+        const names = Array.isArray(inherit) ? inherit : Object.keys(process.env);
+        const inherited = {};
+        for (const name of names) {
+            const value = process.env[name];
+            if (value === undefined)
+                continue;
+            // Skip exported shell functions, which are a known injection vector.
+            if (value.startsWith('()'))
+                continue;
+            inherited[name] = value;
+        }
+        // Explicit `env` entries always win over inherited ones.
+        return { ...inherited, ...config.env };
+    }
+    /**
+     * 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)
+     */
+    async initializeServers(servers, defaultTimeout, defaultInheritEnv) {
+        this.logger.info({ count: servers.length }, 'Initializing MCP servers');
+        // Apply defaults to servers that don't specify their own
+        const serversWithTimeout = servers.map(server => ({
+            ...server,
+            timeout: server.timeout ?? defaultTimeout,
+            inheritEnv: server.inheritEnv ?? defaultInheritEnv,
+        }));
+        const connectionPromises = serversWithTimeout.map(async (config) => {
+            try {
+                await this.connectToServer(config);
+            }
+            catch (error) {
+                this.logger.error({ server: config.name, error }, 'Failed to connect to MCP server');
+            }
+        });
+        await Promise.allSettled(connectionPromises);
+        const connectedCount = Array.from(this.connections.values()).filter((c) => c.connected).length;
+        this.logger.info({ connected: connectedCount, total: servers.length }, 'MCP servers initialization complete');
+    }
+    /**
+     * Connect to a single MCP server with timeout
+     */
+    async connectToServer(config) {
+        // Use server-specific timeout or default (convert seconds to milliseconds)
+        const timeoutMs = config.timeout
+            ? config.timeout * 1000
+            : this.DEFAULT_TIMEOUT_MS;
+        this.logger.info({ server: config.name, timeoutMs }, 'Connecting to MCP server');
+        const transport = new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            env: this.buildEnv(config),
+        });
+        const client = new Client({
+            name: SERVER_NAME,
+            version: VERSION,
+        }, {
+            capabilities: {},
+        });
+        try {
+            const connectPromise = client.connect(transport);
+            // If the timeout wins the race below, this promise may still reject on its
+            // own later; swallow it so it doesn't surface as an unhandled rejection.
+            connectPromise.catch(() => { });
+            await this.withTimeout(connectPromise, timeoutMs);
+            this.connections.set(config.name, {
+                name: config.name,
+                client,
+                transport,
+                connected: true,
+            });
+            this.logger.info({ server: config.name }, 'Successfully connected to MCP server');
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            // A timed-out connect leaves the spawned process running. Tear the
+            // transport down so we don't orphan a child for the proxy's lifetime.
+            try {
+                await transport.close();
+            }
+            catch (closeError) {
+                this.logger.debug({ server: config.name, error: closeError }, 'Failed to close transport for unsuccessful connection');
+            }
+            this.connections.set(config.name, {
+                name: config.name,
+                client,
+                transport,
+                connected: false,
+                lastError: errorMessage,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Get a connected client by server name
+     */
+    getClient(serverName) {
+        const connection = this.connections.get(serverName);
+        return connection?.connected ? connection.client : undefined;
+    }
+    /**
+     * Get all connected clients
+     */
+    getConnectedClients() {
+        return Array.from(this.connections.values())
+            .filter((conn) => conn.connected)
+            .map((conn) => ({ name: conn.name, client: conn.client }));
+    }
+    /**
+     * Get status of all servers
+     */
+    getServerStatuses() {
+        return Array.from(this.connections.values()).map((conn) => ({
+            name: conn.name,
+            connected: conn.connected,
+            lastError: conn.lastError,
+        }));
+    }
+    /**
+     * Check if at least one server is connected
+     */
+    hasConnectedServers() {
+        return Array.from(this.connections.values()).some((conn) => conn.connected);
+    }
+    /**
+     * Disconnect from all servers
+     */
+    async disconnectAll() {
+        this.logger.info('Disconnecting from all MCP servers');
+        const disconnectPromises = Array.from(this.connections.values()).map(async (conn) => {
+            try {
+                await conn.client.close();
+            }
+            catch (error) {
+                this.logger.error({ server: conn.name, error }, 'Error disconnecting from server');
+            }
+        });
+        await Promise.allSettled(disconnectPromises);
+        this.connections.clear();
+        this.logger.info('All MCP servers disconnected');
+    }
+}
+//# sourceMappingURL=client-manager.js.map

package/dist/services/compression-cache.d.ts

@@ -0,0 +1,112 @@
+import type { CompressionStats } from '../types/compression.js';
+import type { CacheMetrics } from '../types/compression.js';
+import type { Logger } from 'pino';
+import { CompressionPersistence } from './compression-persistence.js';
+import type { CompressionFallbackBehavior } from '../config/schema.js';
+/**
+ * In-memory cache for compressed tool descriptions
+ * Key format: "serverName:toolName"
+ */
+export declare class CompressionCache {
+    private cache;
+    private logger;
+    private persistence;
+    private noCompressPatterns;
+    private fallbackBehavior;
+    constructor(logger: Logger, persistence?: CompressionPersistence);
+    /**
+     * Set what to show for tools that have no compressed description yet.
+     * 'original' (default) keeps the server's description; 'blank' hides it so
+     * uncompressed tools cost no context until they have been compressed.
+     */
+    setFallbackBehavior(behavior: CompressionFallbackBehavior): void;
+    /**
+     * Current fallback behavior for uncompressed tools.
+     */
+    getFallbackBehavior(): CompressionFallbackBehavior;
+    /**
+     * Set patterns for tools that should display original descriptions
+     * (tools are still compressed and cached, but show original when listing)
+     */
+    setNoCompressPatterns(patterns: string[]): void;
+    /**
+     * Get all cached entries (for reporting/stats)
+     */
+    getCacheEntries(): Array<{
+        serverName: string;
+        toolName: string;
+        original?: string;
+        compressed: string;
+        compressedAt: string;
+    }>;
+    /**
+     * Check if a tool should bypass compression display
+     * (for showing original descriptions while still caching compressed versions)
+     */
+    private shouldBypassCompression;
+    /**
+     * Generate cache key from server and tool name
+     */
+    private getKey;
+    /**
+     * Save compressed description for a tool
+     * Always saves compression to cache regardless of noCompress patterns
+     */
+    saveCompressed(serverName: string, toolName: string, compressedDescription: string, originalDescription?: string): void;
+    /**
+     * Get description for a tool (session-aware)
+     * - If tool matches noCompress pattern: always use original (display-only bypass)
+     * - If tool is expanded in session: use original
+     * - If compressed exists: use compressed
+     * - Otherwise: apply the configured fallback behavior
+     */
+    getDescription(serverName: string, toolName: string, originalDescription?: string, isExpandedInSession?: boolean): string | undefined;
+    /**
+     * Check if a tool has compressed description
+     */
+    hasCompressed(serverName: string, toolName: string): boolean;
+    /**
+     * Get original description if cached
+     */
+    getOriginalDescription(serverName: string, toolName: string): string | undefined;
+    /**
+     * Get compressed description if cached
+     */
+    getCompressedDescription(serverName: string, toolName: string): string | undefined;
+    /**
+     * Get compression statistics
+     */
+    getStats(): CompressionStats;
+    /**
+     * Detailed cache metrics for reporting
+     */
+    getCacheMetrics(): CacheMetrics;
+    /**
+     * Clear all compressed descriptions
+     */
+    clear(): void;
+    /**
+     * Get all cached tools
+     */
+    getAllCached(): Array<{
+        serverName: string;
+        toolName: string;
+    }>;
+    /**
+     * Load cache from disk
+     */
+    loadFromDisk(): Promise<void>;
+    /**
+     * Save cache to disk
+     */
+    saveToDisk(): Promise<void>;
+    /**
+     * Clear cache from both memory and disk
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Get on-disk cache file path if available
+     */
+    getCacheFilePath(): string;
+}
+//# sourceMappingURL=compression-cache.d.ts.map

package/dist/services/compression-cache.js

@@ -0,0 +1,238 @@
+import { CompressionPersistence } from './compression-persistence.js';
+import { matchesIgnorePattern } from '../config/loader.js';
+/**
+ * In-memory cache for compressed tool descriptions
+ * Key format: "serverName:toolName"
+ */
+export class CompressionCache {
+    cache = {};
+    logger;
+    persistence;
+    noCompressPatterns = [];
+    fallbackBehavior = 'original';
+    constructor(logger, persistence) {
+        this.logger = logger;
+        this.persistence = persistence || new CompressionPersistence(logger);
+    }
+    /**
+     * Set what to show for tools that have no compressed description yet.
+     * 'original' (default) keeps the server's description; 'blank' hides it so
+     * uncompressed tools cost no context until they have been compressed.
+     */
+    setFallbackBehavior(behavior) {
+        this.fallbackBehavior = behavior;
+        this.logger.debug({ behavior }, 'Set compression fallback behavior');
+    }
+    /**
+     * Current fallback behavior for uncompressed tools.
+     */
+    getFallbackBehavior() {
+        return this.fallbackBehavior;
+    }
+    /**
+     * Set patterns for tools that should display original descriptions
+     * (tools are still compressed and cached, but show original when listing)
+     */
+    setNoCompressPatterns(patterns) {
+        this.noCompressPatterns = patterns;
+        this.logger.debug({ patterns }, 'Set noCompress patterns (display-only bypass)');
+    }
+    /**
+     * Get all cached entries (for reporting/stats)
+     */
+    getCacheEntries() {
+        return Object.entries(this.cache).map(([key, value]) => {
+            const [serverName, toolName] = key.split(':');
+            return {
+                serverName,
+                toolName,
+                original: value.original,
+                compressed: value.compressed,
+                compressedAt: value.compressedAt,
+            };
+        });
+    }
+    /**
+     * Check if a tool should bypass compression display
+     * (for showing original descriptions while still caching compressed versions)
+     */
+    shouldBypassCompression(toolName) {
+        return matchesIgnorePattern(toolName, this.noCompressPatterns);
+    }
+    /**
+     * Generate cache key from server and tool name
+     */
+    getKey(serverName, toolName) {
+        return `${serverName}:${toolName}`;
+    }
+    /**
+     * Save compressed description for a tool
+     * Always saves compression to cache regardless of noCompress patterns
+     */
+    saveCompressed(serverName, toolName, compressedDescription, originalDescription) {
+        const key = this.getKey(serverName, toolName);
+        this.cache[key] = {
+            original: originalDescription,
+            compressed: compressedDescription,
+            compressedAt: new Date().toISOString(),
+        };
+        this.logger.debug({ serverName, toolName }, 'Saved compressed description');
+    }
+    /**
+     * Get description for a tool (session-aware)
+     * - If tool matches noCompress pattern: always use original (display-only bypass)
+     * - If tool is expanded in session: use original
+     * - If compressed exists: use compressed
+     * - Otherwise: apply the configured fallback behavior
+     */
+    getDescription(serverName, toolName, originalDescription, isExpandedInSession) {
+        const fullToolName = `${serverName}__${toolName}`;
+        const key = this.getKey(serverName, toolName);
+        // Always bypass compression for noCompress patterns
+        if (this.shouldBypassCompression(fullToolName)) {
+            return originalDescription;
+        }
+        // If tool is expanded in session, use original description
+        if (isExpandedInSession) {
+            return this.cache[key]?.original || originalDescription;
+        }
+        const compressed = this.cache[key]?.compressed;
+        if (compressed) {
+            return compressed;
+        }
+        // Nothing compressed yet - 'blank' keeps the tool callable while costing
+        // no context; 'original' (default) shows the server's own description.
+        return this.fallbackBehavior === 'blank' ? '' : originalDescription;
+    }
+    /**
+     * Check if a tool has compressed description
+     */
+    hasCompressed(serverName, toolName) {
+        const key = this.getKey(serverName, toolName);
+        return !!this.cache[key]?.compressed;
+    }
+    /**
+     * Get original description if cached
+     */
+    getOriginalDescription(serverName, toolName) {
+        const key = this.getKey(serverName, toolName);
+        return this.cache[key]?.original;
+    }
+    /**
+     * Get compressed description if cached
+     */
+    getCompressedDescription(serverName, toolName) {
+        const key = this.getKey(serverName, toolName);
+        return this.cache[key]?.compressed;
+    }
+    /**
+     * Get compression statistics
+     */
+    getStats() {
+        return {
+            totalTools: Object.keys(this.cache).length,
+            compressedTools: Object.keys(this.cache).length,
+            expandedTools: [],
+            cacheSize: JSON.stringify(this.cache).length,
+        };
+    }
+    /**
+     * Detailed cache metrics for reporting
+     */
+    getCacheMetrics() {
+        const entries = this.getCacheEntries();
+        const perServer = {};
+        let totalOriginalChars = 0;
+        let totalCompressedChars = 0;
+        let missingOriginals = 0;
+        let latestCompressedAt;
+        for (const entry of entries) {
+            const originalLength = entry.original?.length ?? 0;
+            const compressedLength = entry.compressed.length;
+            if (!perServer[entry.serverName]) {
+                perServer[entry.serverName] = {
+                    cached: 0,
+                    totalOriginalChars: 0,
+                    totalCompressedChars: 0,
+                    missingOriginals: 0,
+                    latestCompressedAt: undefined,
+                };
+            }
+            perServer[entry.serverName].cached += 1;
+            perServer[entry.serverName].totalOriginalChars += originalLength;
+            perServer[entry.serverName].totalCompressedChars += compressedLength;
+            if (!entry.original) {
+                perServer[entry.serverName].missingOriginals += 1;
+            }
+            const serverLatest = perServer[entry.serverName].latestCompressedAt;
+            if (entry.compressedAt && (!serverLatest || serverLatest < entry.compressedAt)) {
+                perServer[entry.serverName].latestCompressedAt = entry.compressedAt;
+            }
+            totalOriginalChars += originalLength;
+            totalCompressedChars += compressedLength;
+            if (!entry.original)
+                missingOriginals += 1;
+            if (!latestCompressedAt || latestCompressedAt < entry.compressedAt) {
+                latestCompressedAt = entry.compressedAt;
+            }
+        }
+        return {
+            totalCached: entries.length,
+            totalOriginalChars,
+            totalCompressedChars,
+            missingOriginals,
+            latestCompressedAt,
+            cacheSizeBytes: Buffer.byteLength(JSON.stringify(this.cache)),
+            perServer,
+        };
+    }
+    /**
+     * Clear all compressed descriptions
+     */
+    clear() {
+        this.cache = {};
+        this.logger.info('Cleared compression cache');
+    }
+    /**
+     * Get all cached tools
+     */
+    getAllCached() {
+        return Object.keys(this.cache).map((key) => {
+            const [serverName, toolName] = key.split(':');
+            return { serverName, toolName };
+        });
+    }
+    /**
+     * Load cache from disk
+     */
+    async loadFromDisk() {
+        const loadedCache = await this.persistence.load();
+        // Convert Map to cache object
+        for (const [key, value] of loadedCache.entries()) {
+            this.cache[key] = value;
+        }
+        this.logger.info({ count: Object.keys(this.cache).length }, 'Loaded compression cache into memory');
+    }
+    /**
+     * Save cache to disk
+     */
+    async saveToDisk() {
+        // Convert cache object to Map
+        const cacheMap = new Map(Object.entries(this.cache));
+        await this.persistence.save(cacheMap);
+    }
+    /**
+     * Clear cache from both memory and disk
+     */
+    async clearAll() {
+        this.clear();
+        await this.persistence.clear();
+    }
+    /**
+     * Get on-disk cache file path if available
+     */
+    getCacheFilePath() {
+        return this.persistence.getCacheFilePath();
+    }
+}
+//# sourceMappingURL=compression-cache.js.map

package/dist/services/compression-persistence.d.ts

@@ -0,0 +1,36 @@
+import type { Logger } from 'pino';
+/**
+ * Service for persisting compressed tool descriptions to disk
+ */
+export declare class CompressionPersistence {
+    private logger;
+    private cacheDir;
+    private cacheFile;
+    private readonly VERSION;
+    constructor(logger: Logger, cacheDir?: string);
+    /**
+     * Load cached compressions from disk
+     */
+    load(): Promise<Map<string, {
+        original?: string;
+        compressed: string;
+        compressedAt: string;
+    }>>;
+    /**
+     * Save compressions to disk
+     */
+    save(cache: Map<string, {
+        original?: string;
+        compressed: string;
+        compressedAt: string;
+    }>): Promise<void>;
+    /**
+     * Clear the cache file from disk
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the cache file path (useful for debugging)
+     */
+    getCacheFilePath(): string;
+}
+//# sourceMappingURL=compression-persistence.d.ts.map