mcp-compression-proxy 1.0.0

package/dist/services/compression-persistence.js

@@ -0,0 +1,111 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Service for persisting compressed tool descriptions to disk
+ */
+export class CompressionPersistence {
+    logger;
+    cacheDir;
+    cacheFile;
+    VERSION = 1;
+    constructor(logger, cacheDir) {
+        this.logger = logger;
+        this.cacheDir = cacheDir || path.join(os.homedir(), '.mcp-compression-proxy');
+        this.cacheFile = path.join(this.cacheDir, 'cache.json');
+    }
+    /**
+     * Load cached compressions from disk
+     */
+    async load() {
+        const cache = new Map();
+        try {
+            // Check if cache file exists
+            await fs.access(this.cacheFile);
+            // Read and parse cache file
+            const data = await fs.readFile(this.cacheFile, 'utf-8');
+            const persisted = JSON.parse(data);
+            // Validate version
+            if (persisted.version !== this.VERSION) {
+                this.logger.warn({ fileVersion: persisted.version, currentVersion: this.VERSION }, 'Cache version mismatch, ignoring cached data');
+                return cache;
+            }
+            // Load compressions into map
+            for (const comp of persisted.compressions) {
+                const key = `${comp.serverName}:${comp.toolName}`;
+                cache.set(key, {
+                    original: comp.originalDescription,
+                    compressed: comp.compressedDescription,
+                    compressedAt: comp.compressedAt,
+                });
+            }
+            this.logger.info({ count: cache.size, file: this.cacheFile }, 'Loaded compression cache from disk');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.logger.debug('No cache file found, starting with empty cache');
+            }
+            else {
+                this.logger.error({ error, file: this.cacheFile }, 'Failed to load cache from disk');
+            }
+        }
+        return cache;
+    }
+    /**
+     * Save compressions to disk
+     */
+    async save(cache) {
+        try {
+            // Ensure cache directory exists
+            await fs.mkdir(this.cacheDir, { recursive: true });
+            // Convert cache map to persisted format
+            const compressions = Array.from(cache.entries()).map(([key, value]) => {
+                const [serverName, toolName] = key.split(':');
+                return {
+                    serverName,
+                    toolName,
+                    originalDescription: value.original,
+                    compressedDescription: value.compressed,
+                    compressedAt: value.compressedAt,
+                };
+            });
+            const persisted = {
+                version: this.VERSION,
+                lastUpdated: new Date().toISOString(),
+                compressions,
+            };
+            // Write to file with pretty formatting for debuggability
+            await fs.writeFile(this.cacheFile, JSON.stringify(persisted, null, 2), 'utf-8');
+            this.logger.info({ count: compressions.length, file: this.cacheFile }, 'Saved compression cache to disk');
+        }
+        catch (error) {
+            this.logger.error({ error, file: this.cacheFile }, 'Failed to save cache to disk');
+            throw error;
+        }
+    }
+    /**
+     * Clear the cache file from disk
+     */
+    async clear() {
+        try {
+            await fs.unlink(this.cacheFile);
+            this.logger.info({ file: this.cacheFile }, 'Cleared cache file from disk');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                this.logger.debug('Cache file does not exist, nothing to clear');
+            }
+            else {
+                this.logger.error({ error, file: this.cacheFile }, 'Failed to clear cache file');
+                throw error;
+            }
+        }
+    }
+    /**
+     * Get the cache file path (useful for debugging)
+     */
+    getCacheFilePath() {
+        return this.cacheFile;
+    }
+}
+//# sourceMappingURL=compression-persistence.js.map

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

@@ -0,0 +1,89 @@
+import type { Logger } from 'pino';
+import type { ObservedTool } from './stats-service.js';
+/** A compressed description ready to be cached. */
+export type SampledDescription = {
+    serverName: string;
+    toolName: string;
+    description: string;
+};
+/** Minimal shape of the SDK's createMessage result that we depend on. */
+export type SamplingResult = {
+    content?: {
+        type?: string;
+        text?: string;
+    } | Array<{
+        type?: string;
+        text?: string;
+    }>;
+};
+/** The subset of the MCP server surface this needs, so it can be tested. */
+export type SamplingHost = {
+    /** Client capabilities from the initialize handshake, if connected. */
+    getClientCapabilities(): {
+        sampling?: unknown;
+    } | undefined;
+    /** Ask the host LLM to complete a prompt. */
+    createMessage(params: {
+        messages: Array<{
+            role: 'user';
+            content: {
+                type: 'text';
+                text: string;
+            };
+        }>;
+        maxTokens: number;
+        systemPrompt?: string;
+    }): Promise<SamplingResult>;
+};
+/**
+ * Compresses tool descriptions using the *host's* LLM via `sampling/createMessage`.
+ *
+ * This makes compression free and zero-config on clients that support
+ * sampling: no separate API key, no second model to configure. Clients that
+ * do not advertise the capability keep the existing agent-driven flow, where
+ * the caller compresses descriptions itself and posts them back.
+ */
+export declare class CompressionSampler {
+    private logger;
+    private host;
+    private batchSize;
+    constructor(logger: Logger, host: SamplingHost, batchSize?: number);
+    /**
+     * Whether the connected client advertised the `sampling` capability.
+     *
+     * Cursor supports it; Claude Desktop and Cline did not at the time of
+     * writing, so this must never be assumed.
+     */
+    isSupported(): boolean;
+    /** Split tools into request-sized batches. */
+    private batch;
+    /**
+     * Pull the text out of a sampling result, which the SDK may return as a
+     * single content block or an array of them.
+     */
+    private extractText;
+    /**
+     * Parse the model's reply into descriptions.
+     *
+     * Models wrap JSON in prose or a code fence often enough that requiring a
+     * clean array would fail routinely, so the outermost array is extracted
+     * before parsing. Entries that are malformed or name a tool that was not
+     * requested are dropped rather than poisoning the cache.
+     */
+    private parse;
+    /** Build the user prompt for one batch. */
+    private buildPrompt;
+    /**
+     * Compress the given tools via the host LLM.
+     *
+     * Batches are sent sequentially: each one is a round-trip through the host,
+     * which may prompt a human to approve it, so firing them in parallel would
+     * bury the user in approval dialogs.
+     */
+    compress(tools: ObservedTool[]): Promise<{
+        descriptions: SampledDescription[];
+        batchesAttempted: number;
+        batchesFailed: number;
+    }>;
+}
+//# sourceMappingURL=compression-sampler.d.ts.map

package/dist/services/compression-sampler.js

@@ -0,0 +1,171 @@
+const SYSTEM_PROMPT = [
+    'You compress MCP tool descriptions to reduce context consumption.',
+    'For each tool you are given, write a much shorter description that still states',
+    'what the tool does and when to use it, so a model can choose it correctly.',
+    'Keep any detail that distinguishes the tool from a similar one. Drop examples,',
+    'parameter lists, and restatements of the schema.',
+    'Reply with ONLY a JSON array, no prose and no code fence, shaped like:',
+    '[{"serverName":"...","toolName":"...","description":"..."}]',
+].join(' ');
+/** Default tools per sampling request - large enough to be efficient, small
+ *  enough that the reply fits comfortably in maxTokens. */
+const DEFAULT_BATCH_SIZE = 10;
+const TOKENS_PER_TOOL = 120;
+/**
+ * Compresses tool descriptions using the *host's* LLM via `sampling/createMessage`.
+ *
+ * This makes compression free and zero-config on clients that support
+ * sampling: no separate API key, no second model to configure. Clients that
+ * do not advertise the capability keep the existing agent-driven flow, where
+ * the caller compresses descriptions itself and posts them back.
+ */
+export class CompressionSampler {
+    logger;
+    host;
+    batchSize;
+    constructor(logger, host, batchSize = DEFAULT_BATCH_SIZE) {
+        this.logger = logger;
+        this.host = host;
+        this.batchSize = Math.max(1, batchSize);
+    }
+    /**
+     * Whether the connected client advertised the `sampling` capability.
+     *
+     * Cursor supports it; Claude Desktop and Cline did not at the time of
+     * writing, so this must never be assumed.
+     */
+    isSupported() {
+        try {
+            return this.host.getClientCapabilities()?.sampling !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Split tools into request-sized batches. */
+    batch(tools) {
+        const batches = [];
+        for (let i = 0; i < tools.length; i += this.batchSize) {
+            batches.push(tools.slice(i, i + this.batchSize));
+        }
+        return batches;
+    }
+    /**
+     * Pull the text out of a sampling result, which the SDK may return as a
+     * single content block or an array of them.
+     */
+    extractText(result) {
+        const content = result?.content;
+        if (!content)
+            return '';
+        if (Array.isArray(content)) {
+            return content
+                .filter((part) => part?.type === 'text' && typeof part.text === 'string')
+                .map((part) => part.text)
+                .join('');
+        }
+        return typeof content.text === 'string' ? content.text : '';
+    }
+    /**
+     * Parse the model's reply into descriptions.
+     *
+     * Models wrap JSON in prose or a code fence often enough that requiring a
+     * clean array would fail routinely, so the outermost array is extracted
+     * before parsing. Entries that are malformed or name a tool that was not
+     * requested are dropped rather than poisoning the cache.
+     */
+    parse(text, requested) {
+        const start = text.indexOf('[');
+        const end = text.lastIndexOf(']');
+        if (start === -1 || end === -1 || end < start) {
+            this.logger.warn({ reply: text.slice(0, 200) }, 'Sampling reply contained no JSON array');
+            return [];
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text.slice(start, end + 1));
+        }
+        catch (error) {
+            this.logger.warn({ error: error instanceof Error ? error.message : 'Unknown error' }, 'Sampling reply was not valid JSON');
+            return [];
+        }
+        if (!Array.isArray(parsed))
+            return [];
+        const allowed = new Set(requested.map((t) => `${t.serverName}:${t.toolName}`));
+        const results = [];
+        for (const entry of parsed) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const { serverName, toolName, description } = entry;
+            if (typeof serverName !== 'string' ||
+                typeof toolName !== 'string' ||
+                typeof description !== 'string' ||
+                description.trim() === '') {
+                continue;
+            }
+            // Only accept tools we actually asked about - a hallucinated name would
+            // otherwise be cached and shown to the model later.
+            if (!allowed.has(`${serverName}:${toolName}`)) {
+                this.logger.warn({ serverName, toolName }, 'Sampling returned an unrequested tool');
+                continue;
+            }
+            results.push({ serverName, toolName, description: description.trim() });
+        }
+        return results;
+    }
+    /** Build the user prompt for one batch. */
+    buildPrompt(tools) {
+        const payload = tools.map((tool) => ({
+            serverName: tool.serverName,
+            toolName: tool.toolName,
+            description: tool.description ?? '',
+        }));
+        return `Compress these ${tools.length} MCP tool descriptions:\n\n${JSON.stringify(payload, null, 2)}`;
+    }
+    /**
+     * Compress the given tools via the host LLM.
+     *
+     * Batches are sent sequentially: each one is a round-trip through the host,
+     * which may prompt a human to approve it, so firing them in parallel would
+     * bury the user in approval dialogs.
+     */
+    async compress(tools) {
+        if (tools.length === 0) {
+            return { descriptions: [], batchesAttempted: 0, batchesFailed: 0 };
+        }
+        const batches = this.batch(tools);
+        const descriptions = [];
+        let batchesFailed = 0;
+        for (const [index, batchTools] of batches.entries()) {
+            try {
+                this.logger.debug({ batch: index + 1, of: batches.length, tools: batchTools.length }, 'Requesting compression from host LLM');
+                const result = await this.host.createMessage({
+                    messages: [
+                        {
+                            role: 'user',
+                            content: { type: 'text', text: this.buildPrompt(batchTools) },
+                        },
+                    ],
+                    maxTokens: batchTools.length * TOKENS_PER_TOOL,
+                    systemPrompt: SYSTEM_PROMPT,
+                });
+                const batchDescriptions = this.parse(this.extractText(result), batchTools);
+                if (batchDescriptions.length === 0) {
+                    batchesFailed += 1;
+                }
+                descriptions.push(...batchDescriptions);
+            }
+            catch (error) {
+                // A host may reject the request outright - the user can decline a
+                // sampling prompt. Keep whatever earlier batches produced.
+                batchesFailed += 1;
+                this.logger.warn({
+                    batch: index + 1,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                }, 'Sampling request failed');
+            }
+        }
+        return { descriptions, batchesAttempted: batches.length, batchesFailed };
+    }
+}
+//# sourceMappingURL=compression-sampler.js.map

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

@@ -0,0 +1,64 @@
+import type { SessionInfo } from '../types/compression.js';
+import type { Logger } from 'pino';
+/**
+ * Manages sessions for per-client tool expansion state
+ */
+export declare class SessionManager {
+    private sessions;
+    private logger;
+    private readonly SESSION_TIMEOUT_MS;
+    private cleanupTimer;
+    constructor(logger: Logger);
+    /**
+     * Create a new session
+     */
+    createSession(): string;
+    /**
+     * Get session info
+     */
+    getSession(sessionId: string): SessionInfo | undefined;
+    /**
+     * Check if session exists
+     */
+    hasSession(sessionId: string): boolean;
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId: string): boolean;
+    /**
+     * Add expanded tool to session
+     */
+    expandTool(sessionId: string, serverName: string, toolName: string): boolean;
+    /**
+     * Remove expanded tool from session
+     */
+    collapseTool(sessionId: string, serverName: string, toolName: string): boolean;
+    /**
+     * Check if a tool is expanded in a session
+     */
+    isToolExpanded(sessionId: string | undefined, serverName: string, toolName: string): boolean;
+    /**
+     * Get all sessions
+     */
+    getAllSessions(): SessionInfo[];
+    /**
+     * Get session statistics
+     */
+    getSessionStats(sessionId: string): {
+        expandedToolsCount: number;
+        expandedTools: string[];
+    } | null;
+    /**
+     * Cleanup expired sessions
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Clear all sessions
+     */
+    clearAllSessions(): void;
+    /**
+     * Destroy the session manager and cleanup resources
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/services/session-manager.js

@@ -0,0 +1,160 @@
+import { randomUUID } from 'crypto';
+/**
+ * Manages sessions for per-client tool expansion state
+ */
+export class SessionManager {
+    sessions = new Map();
+    logger;
+    SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+    cleanupTimer;
+    constructor(logger) {
+        this.logger = logger;
+        // Cleanup expired sessions every 5 minutes. unref'd because housekeeping
+        // should never be the reason the process stays alive - without it every
+        // SessionManager holds the event loop open until destroy() is called.
+        this.cleanupTimer = setInterval(() => this.cleanupExpiredSessions(), 5 * 60 * 1000);
+        this.cleanupTimer.unref?.();
+    }
+    /**
+     * Create a new session
+     */
+    createSession() {
+        const sessionId = randomUUID();
+        const now = new Date().toISOString();
+        this.sessions.set(sessionId, {
+            sessionId,
+            createdAt: now,
+            lastAccessedAt: now,
+            expandedTools: [],
+        });
+        this.logger.info({ sessionId }, 'Created new session');
+        return sessionId;
+    }
+    /**
+     * Get session info
+     */
+    getSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            // Update last accessed time
+            session.lastAccessedAt = new Date().toISOString();
+        }
+        return session;
+    }
+    /**
+     * Check if session exists
+     */
+    hasSession(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId) {
+        const existed = this.sessions.delete(sessionId);
+        if (existed) {
+            this.logger.info({ sessionId }, 'Deleted session');
+        }
+        return existed;
+    }
+    /**
+     * Add expanded tool to session
+     */
+    expandTool(sessionId, serverName, toolName) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            this.logger.warn({ sessionId }, 'Session not found for expand');
+            return false;
+        }
+        const toolKey = `${serverName}:${toolName}`;
+        if (!session.expandedTools.includes(toolKey)) {
+            session.expandedTools.push(toolKey);
+            session.lastAccessedAt = new Date().toISOString();
+            this.logger.debug({ sessionId, serverName, toolName }, 'Expanded tool in session');
+        }
+        return true;
+    }
+    /**
+     * Remove expanded tool from session
+     */
+    collapseTool(sessionId, serverName, toolName) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            this.logger.warn({ sessionId }, 'Session not found for collapse');
+            return false;
+        }
+        const toolKey = `${serverName}:${toolName}`;
+        const index = session.expandedTools.indexOf(toolKey);
+        if (index !== -1) {
+            session.expandedTools.splice(index, 1);
+            session.lastAccessedAt = new Date().toISOString();
+            this.logger.debug({ sessionId, serverName, toolName }, 'Collapsed tool in session');
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Check if a tool is expanded in a session
+     */
+    isToolExpanded(sessionId, serverName, toolName) {
+        if (!sessionId)
+            return false;
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return false;
+        const toolKey = `${serverName}:${toolName}`;
+        return session.expandedTools.includes(toolKey);
+    }
+    /**
+     * Get all sessions
+     */
+    getAllSessions() {
+        return Array.from(this.sessions.values());
+    }
+    /**
+     * Get session statistics
+     */
+    getSessionStats(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        return {
+            expandedToolsCount: session.expandedTools.length,
+            expandedTools: session.expandedTools,
+        };
+    }
+    /**
+     * Cleanup expired sessions
+     */
+    cleanupExpiredSessions() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [sessionId, session] of this.sessions.entries()) {
+            const lastAccessed = new Date(session.lastAccessedAt).getTime();
+            const age = now - lastAccessed;
+            if (age > this.SESSION_TIMEOUT_MS) {
+                this.sessions.delete(sessionId);
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            this.logger.info({ cleaned }, 'Cleaned up expired sessions');
+        }
+    }
+    /**
+     * Clear all sessions
+     */
+    clearAllSessions() {
+        const count = this.sessions.size;
+        this.sessions.clear();
+        this.logger.info({ count }, 'Cleared all sessions');
+    }
+    /**
+     * Destroy the session manager and cleanup resources
+     */
+    destroy() {
+        clearInterval(this.cleanupTimer);
+        this.clearAllSessions();
+    }
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/services/stats-service.d.ts

@@ -0,0 +1,101 @@
+import type { Logger } from 'pino';
+import type { MCPClientManager } from '../mcp/client-manager.js';
+import type { CompressionCache } from './compression-cache.js';
+import type { SessionManager } from './session-manager.js';
+import type { ConfigResult } from '../config/loader.js';
+type DetailLevel = 'summary' | 'full';
+type ServerToolStats = {
+    name: string;
+    connected: boolean;
+    error?: string;
+    toolsTotal: number;
+    toolsCompressed: number;
+    toolsUncompressed: number;
+    toolsExcluded: number;
+    coveragePercent: number;
+    originalChars: number;
+    compressedChars: number;
+    estimatedTokensSaved: number;
+};
+export type StatsPayload = {
+    summary: {
+        serversConfigured: number;
+        serversConnected: number;
+        serversWithErrors: number;
+        toolsTotal: number;
+        toolsCompressed: number;
+        toolsUncompressed: number;
+        coveragePercent: number;
+        originalChars: number;
+        compressedChars: number;
+        estimatedTokensSaved: number;
+    };
+    servers: ServerToolStats[];
+    compression: {
+        cacheEntries: number;
+        cacheFilePath?: string;
+        cacheSizeBytes: number;
+        missingOriginals: number;
+        latestCompressedAt?: string;
+        totalOriginalChars: number;
+        totalCompressedChars: number;
+        estimatedTokensSaved: number;
+    };
+    sessions: {
+        activeSessions: number;
+        expandedToolsTotal: number;
+        sessions?: Array<{
+            sessionId: string;
+            expandedToolsCount: number;
+        }>;
+    };
+    config: {
+        excludePatterns: string[];
+        noCompressPatterns: string[];
+    };
+};
+/** A tool as seen during aggregation, before its description is rewritten. */
+export type ObservedTool = {
+    serverName: string;
+    toolName: string;
+    description?: string;
+};
+/** Compression coverage over a set of tools, computed without extra I/O. */
+export type LiveCoverage = {
+    totalTools: number;
+    compressedTools: number;
+    uncompressedTools: number;
+    coveragePercent: number;
+    originalChars: number;
+    compressedChars: number;
+    estimatedTokensSaved: number;
+    latestCompressedAt?: string;
+};
+export declare class StatsService {
+    private logger;
+    private clientManager;
+    private compressionCache;
+    private sessionManager;
+    private configLoader;
+    constructor(logger: Logger, clientManager: MCPClientManager, compressionCache: CompressionCache, sessionManager: SessionManager, configLoader?: () => ConfigResult);
+    getStats(options?: {
+        detailLevel?: DetailLevel;
+        serverName?: string;
+    }): Promise<StatsPayload>;
+    /**
+     * Compute coverage over tools already fetched during aggregation.
+     *
+     * Unlike {@link getStats} this issues no `listTools` calls, so it is cheap
+     * enough to run on every `tools/list`.
+     */
+    computeCoverage(tools: ObservedTool[]): LiveCoverage;
+    /**
+     * One-line coverage summary suitable for appending to a tool description.
+     * Kept terse - it ships on every `tools/list`.
+     */
+    formatCoverage(coverage: LiveCoverage): string;
+    private coverage;
+    private calculateTokensSaved;
+}
+export {};
+//# sourceMappingURL=stats-service.d.ts.map