mcp-compression-proxy 1.0.0

package/dist/services/stats-service.js

@@ -0,0 +1,246 @@
+import { matchesIgnorePattern, loadJSONServersCached } from '../config/loader.js';
+/** Render a token/char count compactly (1234 -> "1.2k"). */
+function compact(value) {
+    if (value < 1000)
+        return `${value}`;
+    if (value < 1_000_000)
+        return `${(value / 1000).toFixed(1)}k`;
+    return `${(value / 1_000_000).toFixed(1)}M`;
+}
+export class StatsService {
+    logger;
+    clientManager;
+    compressionCache;
+    sessionManager;
+    configLoader;
+    constructor(logger, clientManager, compressionCache, sessionManager, configLoader = loadJSONServersCached) {
+        this.logger = logger;
+        this.clientManager = clientManager;
+        this.compressionCache = compressionCache;
+        this.sessionManager = sessionManager;
+        this.configLoader = configLoader;
+    }
+    async getStats(options) {
+        const detailLevel = options?.detailLevel === 'full' ? 'full' : 'summary';
+        const serverFilter = options?.serverName;
+        const config = this.configLoader() || {
+            servers: [],
+            excludePatterns: [],
+            noCompressPatterns: [],
+        };
+        const excludePatterns = config.excludePatterns || [];
+        const noCompressPatterns = config.noCompressPatterns || [];
+        const serverStatuses = this.clientManager.getServerStatuses();
+        const connectedClients = this.clientManager.getConnectedClients();
+        const connectedClientMap = new Map(connectedClients.map((c) => [c.name, c.client]));
+        const targetStatuses = serverFilter
+            ? serverStatuses.filter((s) => s.name === serverFilter)
+            : serverStatuses;
+        if (serverFilter && targetStatuses.length === 0) {
+            throw new Error(`Server '${serverFilter}' is not configured or not initialized`);
+        }
+        const serverStats = [];
+        for (const status of targetStatuses) {
+            if (!status.connected) {
+                serverStats.push({
+                    name: status.name,
+                    connected: false,
+                    error: status.lastError || 'Not connected',
+                    toolsTotal: 0,
+                    toolsCompressed: 0,
+                    toolsUncompressed: 0,
+                    toolsExcluded: 0,
+                    coveragePercent: 0,
+                    originalChars: 0,
+                    compressedChars: 0,
+                    estimatedTokensSaved: 0,
+                });
+                continue;
+            }
+            const client = connectedClientMap.get(status.name);
+            if (!client) {
+                serverStats.push({
+                    name: status.name,
+                    connected: false,
+                    error: 'Client not available',
+                    toolsTotal: 0,
+                    toolsCompressed: 0,
+                    toolsUncompressed: 0,
+                    toolsExcluded: 0,
+                    coveragePercent: 0,
+                    originalChars: 0,
+                    compressedChars: 0,
+                    estimatedTokensSaved: 0,
+                });
+                continue;
+            }
+            try {
+                const result = await client.listTools();
+                const filtered = result.tools.filter((tool) => !matchesIgnorePattern(`${status.name}__${tool.name}`, excludePatterns));
+                const excludedCount = result.tools.length - filtered.length;
+                let toolsCompressed = 0;
+                let originalChars = 0;
+                let compressedChars = 0;
+                for (const tool of filtered) {
+                    const original = this.compressionCache.getOriginalDescription(status.name, tool.name) ??
+                        tool.description ??
+                        '';
+                    const hasCompression = this.compressionCache.hasCompressed(status.name, tool.name);
+                    const compressed = this.compressionCache.getCompressedDescription(status.name, tool.name) ??
+                        (hasCompression ? '' : tool.description ?? '');
+                    if (hasCompression) {
+                        toolsCompressed += 1;
+                    }
+                    originalChars += original.length;
+                    compressedChars += compressed.length;
+                }
+                const toolsTotal = filtered.length;
+                const toolsUncompressed = Math.max(toolsTotal - toolsCompressed, 0);
+                const estimatedTokensSaved = this.calculateTokensSaved(originalChars, compressedChars);
+                serverStats.push({
+                    name: status.name,
+                    connected: true,
+                    toolsTotal,
+                    toolsCompressed,
+                    toolsUncompressed,
+                    toolsExcluded: excludedCount,
+                    coveragePercent: this.coverage(toolsCompressed, toolsTotal),
+                    originalChars,
+                    compressedChars,
+                    estimatedTokensSaved,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                this.logger.warn({ server: status.name, error: message }, 'Failed to list tools for stats');
+                serverStats.push({
+                    name: status.name,
+                    connected: true,
+                    error: message,
+                    toolsTotal: 0,
+                    toolsCompressed: 0,
+                    toolsUncompressed: 0,
+                    toolsExcluded: 0,
+                    coveragePercent: 0,
+                    originalChars: 0,
+                    compressedChars: 0,
+                    estimatedTokensSaved: 0,
+                });
+            }
+        }
+        const aggregateTotalTools = serverStats.reduce((sum, s) => sum + s.toolsTotal, 0);
+        const aggregateCompressed = serverStats.reduce((sum, s) => sum + s.toolsCompressed, 0);
+        const aggregateOriginalChars = serverStats.reduce((sum, s) => sum + s.originalChars, 0);
+        const aggregateCompressedChars = serverStats.reduce((sum, s) => sum + s.compressedChars, 0);
+        const cacheMetrics = this.compressionCache.getCacheMetrics();
+        const sessions = this.sessionManager.getAllSessions();
+        const payload = {
+            summary: {
+                serversConfigured: config.servers?.length || serverStatuses.length,
+                serversConnected: serverStatuses.filter((s) => s.connected).length,
+                serversWithErrors: serverStatuses.filter((s) => !s.connected || s.lastError).length,
+                toolsTotal: aggregateTotalTools,
+                toolsCompressed: aggregateCompressed,
+                toolsUncompressed: Math.max(aggregateTotalTools - aggregateCompressed, 0),
+                coveragePercent: this.coverage(aggregateCompressed, aggregateTotalTools),
+                originalChars: aggregateOriginalChars,
+                compressedChars: aggregateCompressedChars,
+                estimatedTokensSaved: this.calculateTokensSaved(aggregateOriginalChars, aggregateCompressedChars),
+            },
+            servers: serverStats,
+            compression: {
+                cacheEntries: cacheMetrics.totalCached,
+                cacheFilePath: this.compressionCache.getCacheFilePath(),
+                cacheSizeBytes: cacheMetrics.cacheSizeBytes,
+                missingOriginals: cacheMetrics.missingOriginals,
+                latestCompressedAt: cacheMetrics.latestCompressedAt,
+                totalOriginalChars: cacheMetrics.totalOriginalChars,
+                totalCompressedChars: cacheMetrics.totalCompressedChars,
+                estimatedTokensSaved: this.calculateTokensSaved(cacheMetrics.totalOriginalChars, cacheMetrics.totalCompressedChars),
+            },
+            sessions: {
+                activeSessions: sessions.length,
+                expandedToolsTotal: sessions.reduce((sum, session) => sum + session.expandedTools.length, 0),
+                sessions: detailLevel === 'full'
+                    ? sessions.map((session) => ({
+                        sessionId: session.sessionId,
+                        expandedToolsCount: session.expandedTools.length,
+                    }))
+                    : undefined,
+            },
+            config: {
+                excludePatterns,
+                noCompressPatterns,
+            },
+        };
+        return payload;
+    }
+    /**
+     * 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) {
+        let compressedTools = 0;
+        let originalChars = 0;
+        let compressedChars = 0;
+        let latestCompressedAt;
+        for (const tool of tools) {
+            const cachedOriginal = this.compressionCache.getOriginalDescription(tool.serverName, tool.toolName);
+            const original = cachedOriginal ?? tool.description ?? '';
+            const compressed = this.compressionCache.getCompressedDescription(tool.serverName, tool.toolName);
+            originalChars += original.length;
+            if (compressed !== undefined) {
+                compressedTools += 1;
+                compressedChars += compressed.length;
+            }
+            else {
+                // Uncompressed tools still occupy their original description.
+                compressedChars += original.length;
+            }
+        }
+        for (const entry of this.compressionCache.getCacheEntries()) {
+            if (!latestCompressedAt || latestCompressedAt < entry.compressedAt) {
+                latestCompressedAt = entry.compressedAt;
+            }
+        }
+        return {
+            totalTools: tools.length,
+            compressedTools,
+            uncompressedTools: Math.max(tools.length - compressedTools, 0),
+            coveragePercent: this.coverage(compressedTools, tools.length),
+            originalChars,
+            compressedChars,
+            estimatedTokensSaved: this.calculateTokensSaved(originalChars, compressedChars),
+            latestCompressedAt,
+        };
+    }
+    /**
+     * One-line coverage summary suitable for appending to a tool description.
+     * Kept terse - it ships on every `tools/list`.
+     */
+    formatCoverage(coverage) {
+        if (coverage.totalTools === 0) {
+            return '[live: no backend tools available]';
+        }
+        const parts = [
+            `${coverage.compressedTools}/${coverage.totalTools} compressed (${coverage.coveragePercent}%)`,
+            `${coverage.uncompressedTools} remaining`,
+        ];
+        if (coverage.estimatedTokensSaved > 0) {
+            parts.push(`~${compact(coverage.estimatedTokensSaved)} tokens saved`);
+        }
+        return `[live: ${parts.join(' · ')}]`;
+    }
+    coverage(done, total) {
+        if (!total)
+            return 0;
+        return Math.round((done / total) * 1000) / 10; // one decimal place
+    }
+    calculateTokensSaved(originalChars, compressedChars) {
+        const savedChars = Math.max(originalChars - compressedChars, 0);
+        return Math.round(savedChars / 4); // rough char->token estimate
+    }
+}
+//# sourceMappingURL=stats-service.js.map

package/dist/types/compression.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Types for compression and session management
+ */
+export interface CompressedToolCache {
+    [key: string]: {
+        original?: string;
+        compressed: string;
+        compressedAt: string;
+    };
+}
+export interface CompressionStats {
+    totalTools: number;
+    compressedTools: number;
+    expandedTools: string[];
+    cacheSize: number;
+}
+export interface SessionInfo {
+    sessionId: string;
+    createdAt: string;
+    lastAccessedAt: string;
+    expandedTools: string[];
+}
+export interface CacheMetrics {
+    totalCached: number;
+    totalOriginalChars: number;
+    totalCompressedChars: number;
+    missingOriginals: number;
+    latestCompressedAt?: string;
+    cacheSizeBytes: number;
+    perServer: Record<string, {
+        cached: number;
+        totalOriginalChars: number;
+        totalCompressedChars: number;
+        missingOriginals: number;
+        latestCompressedAt?: string;
+    }>;
+}
+//# sourceMappingURL=compression.d.ts.map

package/dist/types/compression.js

@@ -0,0 +1,5 @@
+/**
+ * Types for compression and session management
+ */
+export {};
+//# sourceMappingURL=compression.js.map

package/dist/types/index.d.ts

@@ -0,0 +1,108 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+export interface MCPServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Which of the proxy's env vars to pass through. Defaults to all. */
+    inheritEnv?: boolean | string[];
+    enabled?: boolean;
+    timeout?: number;
+}
+export interface MCPClientConnection {
+    name: string;
+    client: Client;
+    transport: Transport;
+    connected: boolean;
+    lastError?: string;
+}
+export interface AggregatedToolsResponse {
+    tools: Array<{
+        name: string;
+        description?: string;
+        inputSchema: object;
+        serverName: string;
+    }>;
+    totalServers: number;
+    connectedServers: number;
+}
+export interface ToolCallRequest {
+    serverName: string;
+    toolName: string;
+    arguments?: Record<string, unknown>;
+}
+export interface ToolCallResponse {
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    isError?: boolean;
+}
+export interface ServerStatus {
+    name: string;
+    connected: boolean;
+    lastError?: string;
+}
+export interface HealthResponse {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    servers: ServerStatus[];
+    timestamp: string;
+}
+export interface FilterOptions {
+    serverNames?: string[];
+    namePattern?: string;
+    excludeServers?: string[];
+}
+export interface ToolsQueryParams {
+    servers?: string;
+    exclude?: string;
+    pattern?: string;
+    sessionId?: string;
+}
+export type IPCMethod = 'tools' | 'search' | 'info' | 'call' | 'stats' | 'daemon-status';
+export interface IPCRequest {
+    id: string;
+    method: IPCMethod;
+    params?: Record<string, unknown>;
+}
+export interface IPCResponse {
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export interface CLIConfig {
+    payloadThreshold?: number;
+    autoStartDaemon?: boolean;
+    daemonLogLevel?: string;
+}
+export interface DaemonStatusResult {
+    running: boolean;
+    pid: number;
+    uptime: number;
+    servers: ServerStatus[];
+    /**
+     * Tools with a cached compressed description. Deliberately not the total
+     * tool count: daemon-status doubles as the liveness ping on every CLI
+     * invocation, and counting all tools would mean a listTools round-trip per
+     * connected server on every command.
+     */
+    cachedToolCount: number;
+    socketPath: string;
+}
+export interface ToolEntry {
+    server: string;
+    tool: string;
+    description: string;
+}
+export interface ToolInfoResult {
+    name: string;
+    server: string;
+    description: string;
+    inputSchema: object;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Identity this proxy reports to MCP peers during the initialize handshake.
+ *
+ * VERSION is kept in sync with package.json by `npm run sync-version`, which
+ * semantic-release runs during a release (see .releaserc.json). The
+ * `tests/unit/version.test.ts` guard fails CI if the two ever drift, so this
+ * constant never needs to be edited by hand.
+ */
+export declare const SERVER_NAME = "mcp-compression-proxy";
+export declare const VERSION = "1.0.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,11 @@
+/**
+ * Identity this proxy reports to MCP peers during the initialize handshake.
+ *
+ * VERSION is kept in sync with package.json by `npm run sync-version`, which
+ * semantic-release runs during a release (see .releaserc.json). The
+ * `tests/unit/version.test.ts` guard fails CI if the two ever drift, so this
+ * constant never needs to be edited by hand.
+ */
+export const SERVER_NAME = 'mcp-compression-proxy';
+export const VERSION = '1.0.0';
+//# sourceMappingURL=version.js.map

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "mcp-compression-proxy",
+  "version": "1.0.0",
+  "description": "MCP server that aggregates tools from multiple MCP servers with LLM-based description compression. Reduces context consumption by 50-80% while maintaining full tool functionality.",
+  "main": "dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "build:test-servers": "tsc -p tests/e2e-real/test-servers/tsconfig.json",
+    "watch": "tsc --watch",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"**/*.{ts,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,json,md}\"",
+    "pretest": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:unit": "jest --testPathPatterns=unit",
+    "pretest:integration": "npm run build",
+    "test:integration": "jest --testPathPatterns=integration",
+    "pretest:e2e": "npm run build",
+    "test:e2e": "jest --testPathPatterns=e2e",
+    "test:e2e:real-llm": "npm run build && npm run build:test-servers && jest tests/e2e-real --testTimeout=120000 --testPathIgnorePatterns='/node_modules/'",
+    "docker:e2e": "docker-compose -f docker-compose.e2e.yml up --abort-on-container-exit",
+    "cli:start": "node dist/cli/index.js daemon start",
+    "cli:stop": "node dist/cli/index.js daemon stop",
+    "sync-version": "node scripts/sync-version.mjs",
+    "prepare": "husky || true",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "bin": {
+    "mcp-compression-proxy": "./dist/index.js",
+    "mcp-cli": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.spec.js",
+    "!dist/**/*.spec.d.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "aggregator",
+    "compression",
+    "llm",
+    "claude",
+    "claude-desktop",
+    "cline",
+    "ai",
+    "context-optimization",
+    "tool-aggregation"
+  ],
+  "author": "KDPA",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kdpa-llc/mcp-compression-proxy.git"
+  },
+  "homepage": "https://github.com/kdpa-llc/mcp-compression-proxy#readme",
+  "bugs": {
+    "url": "https://github.com/kdpa-llc/mcp-compression-proxy/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "ajv": "^8.17.1",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^30.4.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.13.3",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "eslint": "^10.8.1",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.11.0",
+    "husky": "^9.1.7",
+    "jest": "^30.4.2",
+    "prettier": "^3.9.6",
+    "semantic-release": "^25.0.2",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.67.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}