mcp-compression-proxy 1.0.2 → 1.1.0

package/dist/config/loader.js

@@ -67,6 +67,8 @@ function expandEnvVarsInObject(obj, unresolved) {
     }
     return obj;
 }
+/** Fields that only configure a process we spawn ourselves. */
+const STDIO_ONLY_FIELDS = ['args', 'env', 'inheritEnv'];
 /**
  * Validates JSON config against schema
  */
@@ -82,7 +84,48 @@ function validateConfig(config) {
         console.error(`[Config] Validation failed:\n${errors}`);
         throw new Error(`Invalid server configuration:\n${errors}`);
     }
-    return config;
+    const validated = config;
+    // Derived from the schema rather than hand-listed, so a field added there
+    // cannot start warning about itself.
+    const knownServerKeys = new Set(Object.keys(serverConfigSchema.properties.mcpServers.items.properties));
+    for (const server of validated.mcpServers) {
+        const unknown = Object.keys(server).filter((key) => !knownServerKeys.has(key));
+        if (unknown.length > 0) {
+            // A warning, not a throw. These are usually keys carried over from
+            // another MCP client's config format, and failing here would take every
+            // server down over a field this proxy simply does not read.
+            console.error(`[Config] WARNING: server "${server.name}" has unrecognized field(s): ${unknown.join(', ')}. ` +
+                `They are ignored. Check the spelling if you expected them to take effect.`);
+        }
+    }
+    // The schema's `oneOf` only rules out `command` next to `url`; it has nothing
+    // to say about the stdio-only fields, so a remote entry carrying `args` would
+    // validate and then silently drop them. That combination is always a typo, so
+    // it throws like every other config mistake here rather than warning - a soft
+    // path would be the only one in this file.
+    for (const server of validated.mcpServers) {
+        if (server.url) {
+            const offending = STDIO_ONLY_FIELDS.filter((field) => server[field] !== undefined);
+            if (offending.length > 0) {
+                const message = `Invalid server configuration: "${server.name}" sets ${offending.join(', ')} ` +
+                    `alongside "url". Those fields configure a locally spawned process and have no ` +
+                    `effect on a remote server; use "headers" to send credentials instead.`;
+                console.error(`[Config] Validation failed:\n  - ${message}`);
+                throw new Error(message);
+            }
+            continue;
+        }
+        // The mirror of the check above. Headers are an HTTP concept, so on a
+        // spawned server they would be dropped in silence - the same failure mode
+        // that rejecting unknown keys was meant to end.
+        if (server.headers !== undefined) {
+            const message = `Invalid server configuration: "${server.name}" sets headers alongside "command". ` +
+                `Headers are only sent to a remote server; use "env" to pass values to a spawned one.`;
+            console.error(`[Config] Validation failed:\n  - ${message}`);
+            throw new Error(message);
+        }
+    }
+    return validated;
 }
 /**
  * Load and parse JSON config from a file
@@ -162,6 +205,10 @@ export function loadJSONServers() {
     let aggregatedExcludePatterns = [];
     let aggregatedNoCompressPatterns = [];
     let defaultTimeout;
+    let softMaxConnectionAgeSeconds;
+    let hardMaxConnectionAgeSeconds;
+    let authErrorPatterns;
+    let authRetryTools;
     let cliConfig;
     let inheritEnv;
     let compressionFallbackBehavior = 'original';
@@ -182,6 +229,20 @@ export function loadJSONServers() {
         if (userConfig.defaultTimeout) {
             defaultTimeout = userConfig.defaultTimeout;
         }
+        const userSoftMaxAge = userConfig.softMaxConnectionAgeSeconds ??
+            userConfig.maxConnectionAgeSeconds;
+        if (userSoftMaxAge !== undefined) {
+            softMaxConnectionAgeSeconds = userSoftMaxAge;
+        }
+        if (userConfig.hardMaxConnectionAgeSeconds !== undefined) {
+            hardMaxConnectionAgeSeconds = userConfig.hardMaxConnectionAgeSeconds;
+        }
+        if (userConfig.authErrorPatterns !== undefined) {
+            authErrorPatterns = [...userConfig.authErrorPatterns];
+        }
+        if (userConfig.authRetryTools !== undefined) {
+            authRetryTools = [...userConfig.authRetryTools];
+        }
         if (userConfig.cli) {
             cliConfig = { ...userConfig.cli };
         }
@@ -215,6 +276,20 @@ export function loadJSONServers() {
         if (projectConfig.defaultTimeout) {
             defaultTimeout = projectConfig.defaultTimeout;
         }
+        const projectSoftMaxAge = projectConfig.softMaxConnectionAgeSeconds ??
+            projectConfig.maxConnectionAgeSeconds;
+        if (projectSoftMaxAge !== undefined) {
+            softMaxConnectionAgeSeconds = projectSoftMaxAge;
+        }
+        if (projectConfig.hardMaxConnectionAgeSeconds !== undefined) {
+            hardMaxConnectionAgeSeconds = projectConfig.hardMaxConnectionAgeSeconds;
+        }
+        if (projectConfig.authErrorPatterns !== undefined) {
+            authErrorPatterns = [...projectConfig.authErrorPatterns];
+        }
+        if (projectConfig.authRetryTools !== undefined) {
+            authRetryTools = [...projectConfig.authRetryTools];
+        }
         // Project-level CLI config overrides user-level
         if (projectConfig.cli) {
             cliConfig = { ...cliConfig, ...projectConfig.cli };
@@ -249,6 +324,18 @@ export function loadJSONServers() {
     if (defaultTimeout) {
         console.error(`[Config] Default timeout: ${defaultTimeout} seconds`);
     }
+    if (softMaxConnectionAgeSeconds !== undefined) {
+        console.error(`[Config] Soft max connection age: ${softMaxConnectionAgeSeconds} seconds`);
+    }
+    if (hardMaxConnectionAgeSeconds !== undefined) {
+        console.error(`[Config] Hard max connection age: ${hardMaxConnectionAgeSeconds} seconds`);
+    }
+    if (authErrorPatterns && authErrorPatterns.length > 0) {
+        console.error(`[Config] Authentication error patterns configured: ${authErrorPatterns.length}`);
+    }
+    if (authRetryTools && authRetryTools.length > 0) {
+        console.error(`[Config] Authentication retry-safe tools configured: ${authRetryTools.length}`);
+    }
     // Log environment inheritance policy when it deviates from the default
     if (inheritEnv !== undefined && inheritEnv !== true) {
         console.error(`[Config] Environment inheritance: ${inheritEnv === false ? 'safe defaults only' : `allowlist (${inheritEnv.join(', ')})`}`);
@@ -263,6 +350,10 @@ export function loadJSONServers() {
         excludePatterns: aggregatedExcludePatterns,
         noCompressPatterns: aggregatedNoCompressPatterns,
         defaultTimeout,
+        softMaxConnectionAgeSeconds,
+        hardMaxConnectionAgeSeconds,
+        authErrorPatterns,
+        authRetryTools,
         cli: cliConfig,
         inheritEnv,
         compressionFallbackBehavior,

package/dist/config/schema.d.ts

@@ -20,6 +20,18 @@ export declare const serverConfigSchema: {
                         description: string;
                         minLength: number;
                     };
+                    url: {
+                        type: string;
+                        description: string;
+                        minLength: number;
+                    };
+                    headers: {
+                        type: string;
+                        description: string;
+                        additionalProperties: {
+                            type: string;
+                        };
+                    };
                     args: {
                         type: string;
                         description: string;
@@ -54,6 +66,37 @@ export declare const serverConfigSchema: {
                         type: string;
                         description: string;
                     };
+                    softMaxConnectionAgeSeconds: {
+                        type: string;
+                        description: string;
+                        minimum: number;
+                    };
+                    hardMaxConnectionAgeSeconds: {
+                        type: string;
+                        description: string;
+                        minimum: number;
+                    };
+                    maxConnectionAgeSeconds: {
+                        type: string;
+                        description: string;
+                        minimum: number;
+                    };
+                    authErrorPatterns: {
+                        type: string;
+                        description: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
+                    authRetryTools: {
+                        type: string;
+                        description: string;
+                        items: {
+                            type: string;
+                            minLength: number;
+                        };
+                    };
                     type: {
                         type: string;
                         description: string;
@@ -67,6 +110,9 @@ export declare const serverConfigSchema: {
                     };
                 };
                 required: string[];
+                oneOf: {
+                    required: string[];
+                }[];
                 additionalProperties: boolean;
             };
         };
@@ -89,6 +135,37 @@ export declare const serverConfigSchema: {
             description: string;
             minimum: number;
         };
+        softMaxConnectionAgeSeconds: {
+            type: string;
+            description: string;
+            minimum: number;
+        };
+        hardMaxConnectionAgeSeconds: {
+            type: string;
+            description: string;
+            minimum: number;
+        };
+        maxConnectionAgeSeconds: {
+            type: string;
+            description: string;
+            minimum: number;
+        };
+        authErrorPatterns: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                minLength: number;
+            };
+        };
+        authRetryTools: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                minLength: number;
+            };
+        };
         cli: {
             type: string;
             description: string;
@@ -141,18 +218,30 @@ export type CompressionFallbackBehavior = 'original' | 'blank';
 export type ServerConfigJSON = {
     mcpServers: Array<{
         name: string;
-        command: string;
+        command?: string;
         args?: string[];
         env?: Record<string, string>;
         inheritEnv?: InheritEnv;
+        url?: string;
+        headers?: Record<string, string>;
         enabled?: boolean;
         timeout?: number;
+        softMaxConnectionAgeSeconds?: number;
+        hardMaxConnectionAgeSeconds?: number;
+        maxConnectionAgeSeconds?: number;
+        authErrorPatterns?: string[];
+        authRetryTools?: string[];
         type?: string;
         autoApprove?: string[];
     }>;
     excludeTools?: string[];
     noCompressTools?: string[];
     defaultTimeout?: number;
+    softMaxConnectionAgeSeconds?: number;
+    hardMaxConnectionAgeSeconds?: number;
+    maxConnectionAgeSeconds?: number;
+    authErrorPatterns?: string[];
+    authRetryTools?: string[];
     cli?: {
         payloadThreshold?: number;
         autoStartDaemon?: boolean;

package/dist/config/schema.js

@@ -17,9 +17,21 @@ export const serverConfigSchema = {
                     },
                     command: {
                         type: 'string',
-                        description: 'Command to execute',
+                        description: 'Command to execute for a locally spawned (stdio) server',
                         minLength: 1,
                     },
+                    url: {
+                        type: 'string',
+                        description: 'Endpoint of a hosted MCP server, spoken over Streamable HTTP. Mutually exclusive with "command"; the stdio-only fields (args, env, inheritEnv) do not apply.',
+                        minLength: 1,
+                    },
+                    headers: {
+                        type: 'object',
+                        description: 'Static HTTP headers sent with every request to "url", e.g. { "Authorization": "Bearer ${MY_TOKEN}" }. Values go through the same ${VAR} expansion as "env".',
+                        additionalProperties: {
+                            type: 'string',
+                        },
+                    },
                     args: {
                         type: 'array',
                         description: 'Command arguments',
@@ -36,10 +48,7 @@ export const serverConfigSchema = {
                     },
                     inheritEnv: {
                         description: "Which of the proxy's own environment variables this server inherits. true = inherit all (default), false = inherit only the transport's safe defaults (PATH, HOME, ...), or an array of variable names to inherit. Values in `env` always take precedence. Overrides the top-level `inheritEnv`.",
-                        oneOf: [
-                            { type: 'boolean' },
-                            { type: 'array', items: { type: 'string' } },
-                        ],
+                        oneOf: [{ type: 'boolean' }, { type: 'array', items: { type: 'string' } }],
                     },
                     enabled: {
                         type: 'boolean',
@@ -49,9 +58,43 @@ export const serverConfigSchema = {
                         type: 'number',
                         description: 'Server timeout in seconds',
                     },
+                    // Accepted but never read. Presence of `url` is the transport
+                    // discriminator; keeping `type` declared only stops configs that
+                    // already carry it from failing the stricter check below.
+                    softMaxConnectionAgeSeconds: {
+                        type: 'number',
+                        description: 'Lazy recycle threshold in seconds. On the first use at or after this age, the old connection drains and a fresh backend is opened. 0 disables.',
+                        minimum: 0,
+                    },
+                    hardMaxConnectionAgeSeconds: {
+                        type: 'number',
+                        description: 'Absolute connection lifetime in seconds. At this age the connection drains, closes after active calls finish, and remains closed until reused. 0 disables.',
+                        minimum: 0,
+                    },
+                    maxConnectionAgeSeconds: {
+                        type: 'number',
+                        description: 'Deprecated alias for softMaxConnectionAgeSeconds.',
+                        minimum: 0,
+                    },
+                    authErrorPatterns: {
+                        type: 'array',
+                        description: 'Case-insensitive substrings that identify authentication failures in tool results or thrown errors.',
+                        items: {
+                            type: 'string',
+                            minLength: 1,
+                        },
+                    },
+                    authRetryTools: {
+                        type: 'array',
+                        description: 'Tool-name wildcard patterns that are safe to retry once after an authentication failure reopens the backend.',
+                        items: {
+                            type: 'string',
+                            minLength: 1,
+                        },
+                    },
                     type: {
                         type: 'string',
-                        description: 'Server transport type (usually "stdio")',
+                        description: 'Ignored. Kept for compatibility with existing configs.',
                     },
                     autoApprove: {
                         type: 'array',
@@ -61,7 +104,18 @@ export const serverConfigSchema = {
                         },
                     },
                 },
-                required: ['name', 'command'],
+                required: ['name'],
+                // Exactly one transport. `oneOf` also rejects an entry that sets both,
+                // so no extra `not` is needed to catch command+url.
+                oneOf: [{ required: ['command'] }, { required: ['url'] }],
+                // Deliberately permissive. A misspelled *required* key like "comand"
+                // is already rejected by the oneOf above - neither command nor url
+                // survives the typo - so strictness here would only add misspelled
+                // optional keys, and it would pay for that by failing the entire
+                // config, and so every server, on something like Claude Desktop's
+                // `disabled` copied in from another client. The loader warns about
+                // unrecognized keys instead, which keeps the diagnostic without
+                // turning a cosmetic field into total loss of tools.
                 additionalProperties: true,
             },
         },
@@ -84,15 +138,46 @@ export const serverConfigSchema = {
             description: 'Default timeout in seconds for all servers (can be overridden per-server). Default is 30 seconds if not specified.',
             minimum: 1,
         },
+        softMaxConnectionAgeSeconds: {
+            type: 'number',
+            description: 'Global lazy recycle threshold in seconds. Default is 3600 (1 hour). 0 disables.',
+            minimum: 0,
+        },
+        hardMaxConnectionAgeSeconds: {
+            type: 'number',
+            description: 'Global absolute connection lifetime in seconds. Default is 28800 (8 hours). 0 disables.',
+            minimum: 0,
+        },
+        maxConnectionAgeSeconds: {
+            type: 'number',
+            description: 'Deprecated alias for softMaxConnectionAgeSeconds.',
+            minimum: 0,
+        },
+        authErrorPatterns: {
+            type: 'array',
+            description: 'Global case-insensitive substrings that identify authentication failures.',
+            items: {
+                type: 'string',
+                minLength: 1,
+            },
+        },
+        authRetryTools: {
+            type: 'array',
+            description: 'Global tool-name wildcard patterns that are safe to retry once after authentication recovery.',
+            items: {
+                type: 'string',
+                minLength: 1,
+            },
+        },
         cli: {
             type: 'object',
             description: 'CLI (mcp-cli) configuration for lazy-loading mode',
             properties: {
                 payloadThreshold: {
                     type: 'number',
-                    description: 'Character threshold for redirecting large tool outputs to temp files. Default: 500.',
+                    description: 'Character threshold for caching large tool outputs in private files. Default: 10000.',
                     minimum: 0,
-                    default: 500,
+                    default: 10000,
                 },
                 autoStartDaemon: {
                     type: 'boolean',
@@ -110,10 +195,7 @@ export const serverConfigSchema = {
         },
         inheritEnv: {
             description: "Default environment inheritance for all servers (can be overridden per-server). true = pass the proxy's full environment to every backend server (default), false = pass only the transport's safe defaults (PATH, HOME, ...), or an array of variable names to pass through.",
-            oneOf: [
-                { type: 'boolean' },
-                { type: 'array', items: { type: 'string' } },
-            ],
+            oneOf: [{ type: 'boolean' }, { type: 'array', items: { type: 'string' } }],
         },
         compressionFallbackBehavior: {
             type: 'string',