mcp-compression-proxy 1.0.2 → 1.1.0

package/dist/mcp/tool-call-executor.d.ts

@@ -0,0 +1,11 @@
+import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Logger } from 'pino';
+import type { MCPClientManager } from './client-manager.js';
+export declare function matchesAuthenticationFailure(value: unknown, patterns: string[]): boolean;
+/**
+ * Execute a backend tool call and recover once from configured authentication
+ * failures. Every auth failure invalidates the exact connection generation.
+ * Automatic replay is restricted to explicitly configured read-only tools.
+ */
+export declare function callToolWithAuthRecovery(manager: MCPClientManager, logger: Logger, serverName: string, toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
+//# sourceMappingURL=tool-call-executor.d.ts.map

package/dist/mcp/tool-call-executor.js

@@ -0,0 +1,94 @@
+import { CallToolResultSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { matchesIgnorePattern } from '../config/loader.js';
+function searchableText(value) {
+    if (value instanceof Error) {
+        return `${value.name}: ${value.message}`;
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function isCallToolResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        Array.isArray(value.content));
+}
+export function matchesAuthenticationFailure(value, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const text = searchableText(value).toLowerCase();
+    return patterns.some((pattern) => {
+        const normalized = pattern.trim().toLowerCase();
+        return normalized.length > 0 && text.includes(normalized);
+    });
+}
+function isRetrySafe(serverName, toolName, patterns) {
+    return (matchesIgnorePattern(toolName, patterns) ||
+        matchesIgnorePattern(`${serverName}__${toolName}`, patterns));
+}
+async function attemptToolCall(manager, serverName, toolName, args, authErrorPatterns) {
+    let authFailure = false;
+    try {
+        const result = await manager.withClient(serverName, async ({ client, invalidate, markFailure }) => {
+            try {
+                const rawResult = await client.callTool({
+                    name: toolName,
+                    arguments: args,
+                }, CallToolResultSchema);
+                if (!isCallToolResult(rawResult)) {
+                    throw new Error('Task-based MCP tool results are not supported by the proxy');
+                }
+                const callResult = rawResult;
+                if (matchesAuthenticationFailure(callResult, authErrorPatterns)) {
+                    authFailure = true;
+                    invalidate('auth-error');
+                }
+                else if (callResult.isError === true) {
+                    markFailure(`Tool '${toolName}' reported an error`);
+                }
+                return callResult;
+            }
+            catch (error) {
+                if (matchesAuthenticationFailure(error, authErrorPatterns)) {
+                    authFailure = true;
+                    invalidate('auth-error');
+                }
+                throw error;
+            }
+        });
+        return { result, authFailure };
+    }
+    catch (error) {
+        return { error, authFailure };
+    }
+}
+/**
+ * Execute a backend tool call and recover once from configured authentication
+ * failures. Every auth failure invalidates the exact connection generation.
+ * Automatic replay is restricted to explicitly configured read-only tools.
+ */
+export async function callToolWithAuthRecovery(manager, logger, serverName, toolName, args) {
+    const policy = manager.getAuthRecoveryPolicy(serverName);
+    const retrySafe = isRetrySafe(serverName, toolName, policy.authRetryTools);
+    const first = await attemptToolCall(manager, serverName, toolName, args, policy.authErrorPatterns);
+    if (!first.authFailure || !retrySafe) {
+        if (first.authFailure) {
+            logger.warn({ server: serverName, tool: toolName }, 'Authentication failure invalidated the MCP connection; tool was not replayed');
+        }
+        if ('error' in first)
+            throw first.error;
+        return first.result;
+    }
+    logger.warn({ server: serverName, tool: toolName }, 'Retrying read-only MCP tool after authentication recovery');
+    const second = await attemptToolCall(manager, serverName, toolName, args, policy.authErrorPatterns);
+    if ('error' in second)
+        throw second.error;
+    return second.result;
+}
+//# sourceMappingURL=tool-call-executor.js.map

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

@@ -65,6 +65,24 @@ export declare class CompressionCache {
      * Check if a tool has compressed description
      */
     hasCompressed(serverName: string, toolName: string): boolean;
+    /**
+     * Whether a cached compression was made from a description the backend no
+     * longer serves.
+     *
+     * Both sides must be present to say anything: entries cached before originals
+     * were recorded have no baseline (see `missingOriginals` in the metrics), and
+     * a backend that reports no description gives nothing to compare. Treating
+     * either as stale would put those tools into a recompression loop they could
+     * never exit.
+     */
+    isStale(serverName: string, toolName: string, liveOriginal?: string): boolean;
+    /**
+     * Drop one tool's cached compression. Returns whether there was one.
+     *
+     * Persisting is left to the caller so a batch of invalidations costs a single
+     * disk write.
+     */
+    invalidate(serverName: string, toolName: string): boolean;
     /**
      * Get original description if cached
      */

package/dist/services/compression-cache.js

@@ -111,6 +111,38 @@ export class CompressionCache {
         const key = this.getKey(serverName, toolName);
         return !!this.cache[key]?.compressed;
     }
+    /**
+     * Whether a cached compression was made from a description the backend no
+     * longer serves.
+     *
+     * Both sides must be present to say anything: entries cached before originals
+     * were recorded have no baseline (see `missingOriginals` in the metrics), and
+     * a backend that reports no description gives nothing to compare. Treating
+     * either as stale would put those tools into a recompression loop they could
+     * never exit.
+     */
+    isStale(serverName, toolName, liveOriginal) {
+        const entry = this.cache[this.getKey(serverName, toolName)];
+        if (!entry?.compressed)
+            return false;
+        if (!entry.original || !liveOriginal)
+            return false;
+        return entry.original !== liveOriginal;
+    }
+    /**
+     * Drop one tool's cached compression. Returns whether there was one.
+     *
+     * Persisting is left to the caller so a batch of invalidations costs a single
+     * disk write.
+     */
+    invalidate(serverName, toolName) {
+        const key = this.getKey(serverName, toolName);
+        if (!this.cache[key])
+            return false;
+        delete this.cache[key];
+        this.logger.debug({ serverName, toolName }, 'Invalidated compressed description');
+        return true;
+    }
     /**
      * Get original description if cached
      */

package/dist/services/session-manager.js

@@ -102,6 +102,11 @@ export class SessionManager {
         const session = this.sessions.get(sessionId);
         if (!session)
             return false;
+        // Reading counts as use. This runs for every tool on every tools/list, so
+        // without it a session that is only ever read - the normal case, since
+        // expand/collapse are one-off calls - ages out mid-conversation and its
+        // expanded tools silently collapse back to compressed descriptions.
+        session.lastAccessedAt = new Date().toISOString();
         const toolKey = `${serverName}:${toolName}`;
         return session.expandedTools.includes(toolKey);
     }

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

@@ -1,5 +1,6 @@
 import type { Logger } from 'pino';
 import type { MCPClientManager } from '../mcp/client-manager.js';
+import type { ConnectionLifecycleState } from '../types/index.js';
 import type { CompressionCache } from './compression-cache.js';
 import type { SessionManager } from './session-manager.js';
 import type { ConfigResult } from '../config/loader.js';
@@ -7,6 +8,7 @@ type DetailLevel = 'summary' | 'full';
 type ServerToolStats = {
     name: string;
     connected: boolean;
+    state?: ConnectionLifecycleState;
     error?: string;
     toolsTotal: number;
     toolsCompressed: number;
@@ -65,6 +67,8 @@ export type LiveCoverage = {
     totalTools: number;
     compressedTools: number;
     uncompressedTools: number;
+    /** Compressed from a description the backend has since changed. */
+    staleTools: number;
     coveragePercent: number;
     originalChars: number;
     compressedChars: number;

package/dist/services/stats-service.js

@@ -31,8 +31,6 @@ export class StatsService {
         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;
@@ -41,41 +39,8 @@ export class StatsService {
         }
         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 result = await this.clientManager.withClient(status.name, async ({ client }) => client.listTools());
                 const filtered = result.tools.filter((tool) => !matchesIgnorePattern(`${status.name}__${tool.name}`, excludePatterns));
                 const excludedCount = result.tools.length - filtered.length;
                 let toolsCompressed = 0;
@@ -100,6 +65,7 @@ export class StatsService {
                 serverStats.push({
                     name: status.name,
                     connected: true,
+                    state: 'ready',
                     toolsTotal,
                     toolsCompressed,
                     toolsUncompressed,
@@ -115,7 +81,9 @@ export class StatsService {
                 this.logger.warn({ server: status.name, error: message }, 'Failed to list tools for stats');
                 serverStats.push({
                     name: status.name,
-                    connected: true,
+                    connected: false,
+                    state: this.clientManager.getServerStatuses()
+                        .find((current) => current.name === status.name)?.state,
                     error: message,
                     toolsTotal: 0,
                     toolsCompressed: 0,
@@ -137,8 +105,8 @@ export class StatsService {
         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,
+                serversConnected: serverStats.filter((s) => s.connected).length,
+                serversWithErrors: serverStats.filter((s) => !s.connected || s.error).length,
                 toolsTotal: aggregateTotalTools,
                 toolsCompressed: aggregateCompressed,
                 toolsUncompressed: Math.max(aggregateTotalTools - aggregateCompressed, 0),
@@ -183,6 +151,7 @@ export class StatsService {
      */
     computeCoverage(tools) {
         let compressedTools = 0;
+        let staleTools = 0;
         let originalChars = 0;
         let compressedChars = 0;
         let latestCompressedAt;
@@ -194,6 +163,11 @@ export class StatsService {
             if (compressed !== undefined) {
                 compressedTools += 1;
                 compressedChars += compressed.length;
+                // The live description is already in hand here, so staleness costs no
+                // extra listTools call - preserve that when touching this loop.
+                if (this.compressionCache.isStale(tool.serverName, tool.toolName, tool.description)) {
+                    staleTools += 1;
+                }
             }
             else {
                 // Uncompressed tools still occupy their original description.
@@ -209,6 +183,7 @@ export class StatsService {
             totalTools: tools.length,
             compressedTools,
             uncompressedTools: Math.max(tools.length - compressedTools, 0),
+            staleTools,
             coveragePercent: this.coverage(compressedTools, tools.length),
             originalChars,
             compressedChars,
@@ -228,6 +203,10 @@ export class StatsService {
             `${coverage.compressedTools}/${coverage.totalTools} compressed (${coverage.coveragePercent}%)`,
             `${coverage.uncompressedTools} remaining`,
         ];
+        // Only when non-zero: this string ships on every tools/list.
+        if (coverage.staleTools > 0) {
+            parts.push(`${coverage.staleTools} stale`);
+        }
         if (coverage.estimatedTokensSaved > 0) {
             parts.push(`~${compact(coverage.estimatedTokensSaved)} tokens saved`);
         }

package/dist/types/index.d.ts

@@ -1,22 +1,63 @@
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+/**
+ * A backend server, either spawned locally (`command`) or reached over HTTP
+ * (`url`). The two are mutually exclusive, enforced by the config schema.
+ *
+ * Flat optionals rather than a discriminated union: `initializeServers`
+ * applies defaults by spreading (`{...server, timeout: ...}`), and TypeScript
+ * cannot keep a union narrowed across that.
+ */
 export interface MCPServerConfig {
     name: string;
-    command: 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[];
+    /** Endpoint of a hosted MCP server. Mutually exclusive with `command`. */
+    url?: string;
+    /** Static headers sent with every request to `url`, e.g. Authorization. */
+    headers?: Record<string, string>;
     enabled?: boolean;
     timeout?: number;
+    /** Lazy recycle threshold. Reopen on the next use after this age. 0 disables. */
+    softMaxConnectionAgeSeconds?: number;
+    /** Absolute lifetime. Drain at this age and close after active calls finish. 0 disables. */
+    hardMaxConnectionAgeSeconds?: number;
+    /** Deprecated alias for softMaxConnectionAgeSeconds. */
+    maxConnectionAgeSeconds?: number;
+    /** Case-insensitive substrings that identify an authentication failure. */
+    authErrorPatterns?: string[];
+    /** Tool-name wildcard patterns that are safe to retry once after auth recovery. */
+    authRetryTools?: string[];
 }
 export interface MCPClientConnection {
     name: string;
     client: Client;
-    transport: Transport;
+    /**
+     * Absent when the transport could not be built at all - a malformed `url`,
+     * say. Recording the failure still matters, so this cannot be required.
+     */
+    transport?: Transport;
     connected: boolean;
     lastError?: string;
+    /**
+     * The resolved config this connection was built from - defaults already
+     * merged in. A reconnect replays it verbatim instead of re-deriving the
+     * timeout and env policy, which would silently drift from the original.
+     */
+    config: MCPServerConfig;
+}
+export interface ConnectionLifecycleDefaults {
+    softMaxConnectionAgeSeconds?: number;
+    hardMaxConnectionAgeSeconds?: number;
+    /** Deprecated alias for softMaxConnectionAgeSeconds. */
+    maxConnectionAgeSeconds?: number;
+    authErrorPatterns?: string[];
+    authRetryTools?: string[];
 }
+export type ConnectionLifecycleState = 'closed' | 'starting' | 'ready' | 'draining' | 'failed';
 export interface AggregatedToolsResponse {
     tools: Array<{
         name: string;
@@ -44,6 +85,20 @@ export interface ServerStatus {
     name: string;
     connected: boolean;
     lastError?: string;
+    state?: ConnectionLifecycleState;
+    activeCalls?: number;
+    drainingConnections?: number;
+    generation?: number;
+    connectedAt?: number;
+    lastUsedAt?: number;
+    lastAttemptAt?: number;
+    lastSuccessAt?: number;
+    connectionAgeSeconds?: number;
+    softMaxConnectionAgeSeconds?: number;
+    hardMaxConnectionAgeSeconds?: number;
+    recycleCount?: number;
+    authInvalidations?: number;
+    consecutiveFailures?: number;
 }
 export interface HealthResponse {
     status: 'healthy' | 'degraded' | 'unhealthy';
@@ -61,7 +116,7 @@ export interface ToolsQueryParams {
     pattern?: string;
     sessionId?: string;
 }
-export type IPCMethod = 'tools' | 'search' | 'info' | 'call' | 'stats' | 'daemon-status';
+export type IPCMethod = 'tools' | 'search' | 'info' | 'call' | 'payload-read' | 'payload-find' | 'script' | 'stats' | 'daemon-status';
 export interface IPCRequest {
     id: string;
     method: IPCMethod;
@@ -83,6 +138,7 @@ export interface CLIConfig {
 export interface DaemonStatusResult {
     running: boolean;
     pid: number;
+    releaseId?: string;
     uptime: number;
     servers: ServerStatus[];
     /**

package/dist/version.d.ts

@@ -7,5 +7,5 @@
  * constant never needs to be edited by hand.
  */
 export declare const SERVER_NAME = "mcp-compression-proxy";
-export declare const VERSION = "1.0.2";
+export declare const VERSION = "1.1.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -7,5 +7,5 @@
  * constant never needs to be edited by hand.
  */
 export const SERVER_NAME = 'mcp-compression-proxy';
-export const VERSION = '1.0.2';
+export const VERSION = '1.1.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-compression-proxy",
-  "version": "1.0.2",
+  "version": "1.1.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",
@@ -29,6 +29,7 @@
     "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",
+    "check:release-notes": "node scripts/check-release-notes.mjs",
     "prepare": "husky || true",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -71,7 +72,7 @@
     "url": "https://github.com/kdpa-llc/mcp-compression-proxy/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "ajv": "^8.17.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.0.0"
@@ -81,10 +82,10 @@
     "@commitlint/config-conventional": "^21.2.2",
     "@eslint/js": "^10.0.1",
     "@jest/globals": "^30.4.1",
-    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/exec": "^7.1.0",
-    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/git": "^11.0.1",
     "@semantic-release/github": "^12.0.2",
     "@semantic-release/npm": "^13.1.2",
     "@semantic-release/release-notes-generator": "^14.1.0",