mcp-compression-proxy 1.0.0

package/dist/config/loader.js

@@ -0,0 +1,332 @@
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir as osHomedir } from 'os';
+import { serverConfigSchema, } from './schema.js';
+import Ajv from 'ajv';
+const ajv = new Ajv({ allErrors: true });
+const validate = ajv.compile(serverConfigSchema);
+/**
+ * Get home directory (testable)
+ */
+function homedir() {
+    return process.env.HOME || osHomedir();
+}
+/**
+ * Expands environment variables in a string.
+ *
+ * Supported syntax:
+ * - `${VAR}`           - substitutes the variable, or '' when it is not set
+ * - `${VAR:-fallback}` - substitutes the variable, or `fallback` when unset/empty
+ * - `$${VAR}`          - escape hatch, produces the literal text `${VAR}`
+ *
+ * Names of `${VAR}` references that could not be resolved are collected into
+ * `unresolved` so the caller can warn instead of silently injecting an empty
+ * string (a common cause of confusing downstream 401s).
+ */
+function expandEnvVars(value, unresolved) {
+    return value.replace(/(\$?)\$\{([^}]+)\}/g, (match, escape, expression) => {
+        // `$${VAR}` is an escape for a literal `${VAR}`
+        if (escape) {
+            return match.slice(1);
+        }
+        const separatorIndex = expression.indexOf(':-');
+        const varName = separatorIndex === -1 ? expression : expression.slice(0, separatorIndex);
+        const defaultValue = separatorIndex === -1 ? undefined : expression.slice(separatorIndex + 2);
+        const resolved = process.env[varName];
+        if (resolved) {
+            return resolved;
+        }
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        unresolved.add(varName);
+        return '';
+    });
+}
+/**
+ * Recursively expands environment variables in an object.
+ *
+ * Generic rather than `any`: expansion only ever rewrites string leaves, so
+ * the shape is preserved. Returning `any` here silently erased
+ * ServerConfigJSON at the one call site that needs it most - the value that
+ * has just been schema-validated.
+ */
+function expandEnvVarsInObject(obj, unresolved) {
+    if (typeof obj === 'string') {
+        return expandEnvVars(obj, unresolved);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => expandEnvVarsInObject(item, unresolved));
+    }
+    if (obj !== null && typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = expandEnvVarsInObject(value, unresolved);
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Validates JSON config against schema
+ */
+function validateConfig(config) {
+    if (!validate(config)) {
+        const errors = validate.errors
+            ?.map((err) => {
+            const path = err.instancePath || 'root';
+            const data = err.data ? JSON.stringify(err.data, null, 2) : 'undefined';
+            return `  - ${path}: ${err.message}\n    Data: ${data}`;
+        })
+            .join('\n');
+        console.error(`[Config] Validation failed:\n${errors}`);
+        throw new Error(`Invalid server configuration:\n${errors}`);
+    }
+    return config;
+}
+/**
+ * Load and parse JSON config from a file
+ */
+function loadJSONConfig(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        const validated = validateConfig(parsed);
+        // Expand environment variables
+        const unresolved = new Set();
+        const expanded = expandEnvVarsInObject(validated, unresolved);
+        if (unresolved.size > 0) {
+            console.error(`[Config] WARNING: ${filePath} references environment variable(s) that are not set: ` +
+                `${[...unresolved].join(', ')}. They were replaced with an empty string, which usually ` +
+                `surfaces later as an authentication failure in the downstream server. Export them before ` +
+                `starting your MCP client, or use \${VAR:-default} to supply a fallback.`);
+        }
+        return expanded;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            // Keep the parser's own error as `cause`: it carries the offset of the
+            // offending token, which is what actually locates the typo.
+            throw new Error(`Invalid JSON in ${filePath}: ${error.message}`, { cause: error });
+        }
+        throw error;
+    }
+}
+/**
+ * Get config file paths
+ * User-level: ~/.mcp-compression-proxy/servers.json
+ * Project-level: ./servers.json
+ */
+function getConfigPaths() {
+    return {
+        user: join(homedir(), '.mcp-compression-proxy', 'servers.json'),
+        project: join(process.cwd(), 'servers.json'),
+    };
+}
+/**
+ * Convert wildcard pattern to regex
+ * Supports * wildcard, case-insensitive
+ */
+function patternToRegex(pattern) {
+    // Escape regex special chars except *
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    // Convert * to .*
+    const regexPattern = escaped.replace(/\*/g, '.*');
+    // Case insensitive
+    return new RegExp(`^${regexPattern}$`, 'i');
+}
+/**
+ * Check if tool name matches any ignore pattern
+ */
+export function matchesIgnorePattern(toolName, patterns) {
+    if (!patterns || patterns.length === 0) {
+        return false;
+    }
+    return patterns.some(pattern => {
+        const regex = patternToRegex(pattern);
+        return regex.test(toolName);
+    });
+}
+/**
+ * Load and aggregate server configuration from JSON files
+ * 1. Load user-level config and collect patterns
+ * 2. Load project-level config and append servers
+ * 3. Aggregate exclude and noCompress patterns from both configs
+ */
+export function loadJSONServers() {
+    const paths = getConfigPaths();
+    let aggregatedServers = [];
+    let aggregatedExcludePatterns = [];
+    let aggregatedNoCompressPatterns = [];
+    let defaultTimeout;
+    let cliConfig;
+    let inheritEnv;
+    let compressionFallbackBehavior = 'original';
+    let hasAnyConfig = false;
+    // Step 1: Load user-level config
+    const userConfig = loadJSONConfig(paths.user);
+    if (userConfig) {
+        hasAnyConfig = true;
+        console.error(`[Config] Loaded user-level configuration from: ${paths.user}`);
+        console.error(`[Config] User config contains ${userConfig.mcpServers.length} servers`);
+        aggregatedServers = [...userConfig.mcpServers];
+        if (userConfig.excludeTools) {
+            aggregatedExcludePatterns = [...userConfig.excludeTools];
+        }
+        if (userConfig.noCompressTools) {
+            aggregatedNoCompressPatterns = [...userConfig.noCompressTools];
+        }
+        if (userConfig.defaultTimeout) {
+            defaultTimeout = userConfig.defaultTimeout;
+        }
+        if (userConfig.cli) {
+            cliConfig = { ...userConfig.cli };
+        }
+        if (userConfig.inheritEnv !== undefined) {
+            inheritEnv = userConfig.inheritEnv;
+        }
+        if (userConfig.compressionFallbackBehavior) {
+            compressionFallbackBehavior = userConfig.compressionFallbackBehavior;
+        }
+    }
+    else {
+        console.error(`[Config] No user-level config found at: ${paths.user}`);
+    }
+    // Step 2: Load project-level config and append
+    const projectConfig = loadJSONConfig(paths.project);
+    if (projectConfig) {
+        hasAnyConfig = true;
+        console.error(`[Config] Loaded project-level configuration from: ${paths.project}`);
+        console.error(`[Config] Project config contains ${projectConfig.mcpServers.length} servers`);
+        // Append project servers
+        aggregatedServers = [...aggregatedServers, ...projectConfig.mcpServers];
+        // Append project exclude patterns
+        if (projectConfig.excludeTools) {
+            aggregatedExcludePatterns = [...aggregatedExcludePatterns, ...projectConfig.excludeTools];
+        }
+        // Append project noCompress patterns
+        if (projectConfig.noCompressTools) {
+            aggregatedNoCompressPatterns = [...aggregatedNoCompressPatterns, ...projectConfig.noCompressTools];
+        }
+        // Project-level settings override user-level
+        if (projectConfig.defaultTimeout) {
+            defaultTimeout = projectConfig.defaultTimeout;
+        }
+        // Project-level CLI config overrides user-level
+        if (projectConfig.cli) {
+            cliConfig = { ...cliConfig, ...projectConfig.cli };
+        }
+        if (projectConfig.inheritEnv !== undefined) {
+            inheritEnv = projectConfig.inheritEnv;
+        }
+        if (projectConfig.compressionFallbackBehavior) {
+            compressionFallbackBehavior = projectConfig.compressionFallbackBehavior;
+        }
+    }
+    else {
+        console.error(`[Config] No project-level config found at: ${paths.project}`);
+    }
+    if (!hasAnyConfig) {
+        return null;
+    }
+    // Log disabled servers
+    const disabled = aggregatedServers.filter(s => s.enabled === false);
+    if (disabled.length > 0) {
+        console.error(`[Config] Found ${disabled.length} disabled server(s): ${disabled.map(s => s.name).join(', ')}`);
+    }
+    // Log exclude patterns
+    if (aggregatedExcludePatterns.length > 0) {
+        console.error(`[Config] Tool exclude patterns: ${aggregatedExcludePatterns.join(', ')}`);
+    }
+    // Log noCompress patterns
+    if (aggregatedNoCompressPatterns.length > 0) {
+        console.error(`[Config] Tool noCompress patterns: ${aggregatedNoCompressPatterns.join(', ')}`);
+    }
+    // Log default timeout
+    if (defaultTimeout) {
+        console.error(`[Config] Default timeout: ${defaultTimeout} seconds`);
+    }
+    // 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(', ')})`}`);
+    }
+    // Log fallback behavior when it deviates from the default
+    if (compressionFallbackBehavior !== 'original') {
+        console.error(`[Config] Compression fallback behavior: ${compressionFallbackBehavior}`);
+    }
+    console.error(`[Config] Total servers after aggregation: ${aggregatedServers.length}`);
+    return {
+        servers: aggregatedServers,
+        excludePatterns: aggregatedExcludePatterns,
+        noCompressPatterns: aggregatedNoCompressPatterns,
+        defaultTimeout,
+        cli: cliConfig,
+        inheritEnv,
+        compressionFallbackBehavior,
+    };
+}
+/**
+ * Fingerprint of the config files, used to detect edits between reads.
+ * Missing files are part of the fingerprint so creating one invalidates too.
+ */
+function configSignature() {
+    const paths = getConfigPaths();
+    return [paths.user, paths.project]
+        .map((path) => {
+        try {
+            const stat = statSync(path);
+            return `${path}:${stat.mtimeMs}:${stat.size}`;
+        }
+        catch {
+            return `${path}:missing`;
+        }
+    })
+        .join('|');
+}
+let configCache = null;
+/**
+ * Cached wrapper around {@link loadJSONServers}.
+ *
+ * `tools/list` runs on every client refresh, and re-reading, re-validating and
+ * re-logging both config files each time is pure overhead. The cache is keyed
+ * on file mtime/size, so edits are still picked up without a restart.
+ */
+export function loadJSONServersCached() {
+    const signature = configSignature();
+    if (configCache && configCache.signature === signature) {
+        return configCache.result;
+    }
+    const result = loadJSONServers();
+    configCache = { signature, result };
+    return result;
+}
+/**
+ * Drop the cached config. Primarily for tests that swap config files
+ * within a single process.
+ */
+export function clearConfigCache() {
+    configCache = null;
+}
+/**
+ * Get the path that would be used for config
+ * (for migration script purposes)
+ */
+export function getConfigPath() {
+    return join(homedir(), '.mcp-compression-proxy', 'servers.json');
+}
+/**
+ * Get the daemon Unix socket path
+ */
+export function getSocketPath() {
+    return join(homedir(), '.mcp-compression-proxy', 'daemon.sock');
+}
+/**
+ * Get the daemon PID file path
+ */
+export function getPidFilePath() {
+    return join(homedir(), '.mcp-compression-proxy', 'daemon.pid');
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/schema.d.ts

@@ -0,0 +1,164 @@
+/**
+ * JSON Schema for MCP server configuration
+ */
+export declare const serverConfigSchema: {
+    $schema: string;
+    type: string;
+    properties: {
+        mcpServers: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                        description: string;
+                        minLength: number;
+                    };
+                    command: {
+                        type: string;
+                        description: string;
+                        minLength: number;
+                    };
+                    args: {
+                        type: string;
+                        description: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                    env: {
+                        type: string;
+                        description: string;
+                        additionalProperties: {
+                            type: string;
+                        };
+                    };
+                    inheritEnv: {
+                        description: string;
+                        oneOf: ({
+                            type: string;
+                            items?: undefined;
+                        } | {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        })[];
+                    };
+                    enabled: {
+                        type: string;
+                        description: string;
+                    };
+                    timeout: {
+                        type: string;
+                        description: string;
+                    };
+                    type: {
+                        type: string;
+                        description: string;
+                    };
+                    autoApprove: {
+                        type: string;
+                        description: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+        };
+        excludeTools: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+            };
+        };
+        noCompressTools: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+            };
+        };
+        defaultTimeout: {
+            type: string;
+            description: string;
+            minimum: number;
+        };
+        cli: {
+            type: string;
+            description: string;
+            properties: {
+                payloadThreshold: {
+                    type: string;
+                    description: string;
+                    minimum: number;
+                    default: number;
+                };
+                autoStartDaemon: {
+                    type: string;
+                    description: string;
+                    default: boolean;
+                };
+                daemonLogLevel: {
+                    type: string;
+                    description: string;
+                    enum: string[];
+                    default: string;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        inheritEnv: {
+            description: string;
+            oneOf: ({
+                type: string;
+                items?: undefined;
+            } | {
+                type: string;
+                items: {
+                    type: string;
+                };
+            })[];
+        };
+        compressionFallbackBehavior: {
+            type: string;
+            description: string;
+            enum: string[];
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+/** Environment inheritance policy: all, none/safe-defaults, or an allowlist. */
+export type InheritEnv = boolean | string[];
+/** How to describe a tool that has no compressed description cached yet. */
+export type CompressionFallbackBehavior = 'original' | 'blank';
+export type ServerConfigJSON = {
+    mcpServers: Array<{
+        name: string;
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        inheritEnv?: InheritEnv;
+        enabled?: boolean;
+        timeout?: number;
+        type?: string;
+        autoApprove?: string[];
+    }>;
+    excludeTools?: string[];
+    noCompressTools?: string[];
+    defaultTimeout?: number;
+    cli?: {
+        payloadThreshold?: number;
+        autoStartDaemon?: boolean;
+        daemonLogLevel?: string;
+    };
+    inheritEnv?: InheritEnv;
+    compressionFallbackBehavior?: CompressionFallbackBehavior;
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.js

@@ -0,0 +1,127 @@
+/**
+ * JSON Schema for MCP server configuration
+ */
+export const serverConfigSchema = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    properties: {
+        mcpServers: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'Unique name for the MCP server',
+                        minLength: 1,
+                    },
+                    command: {
+                        type: 'string',
+                        description: 'Command to execute',
+                        minLength: 1,
+                    },
+                    args: {
+                        type: 'array',
+                        description: 'Command arguments',
+                        items: {
+                            type: 'string',
+                        },
+                    },
+                    env: {
+                        type: 'object',
+                        description: 'Environment variables',
+                        additionalProperties: {
+                            type: 'string',
+                        },
+                    },
+                    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' } },
+                        ],
+                    },
+                    enabled: {
+                        type: 'boolean',
+                        description: 'Whether the server is enabled',
+                    },
+                    timeout: {
+                        type: 'number',
+                        description: 'Server timeout in seconds',
+                    },
+                    type: {
+                        type: 'string',
+                        description: 'Server transport type (usually "stdio")',
+                    },
+                    autoApprove: {
+                        type: 'array',
+                        description: 'Tools to auto-approve',
+                        items: {
+                            type: 'string',
+                        },
+                    },
+                },
+                required: ['name', 'command'],
+                additionalProperties: true,
+            },
+        },
+        excludeTools: {
+            type: 'array',
+            description: 'Tool name patterns to exclude from tool list entirely (supports wildcards, case-insensitive). Examples: "server__*" (all tools from server), "*__set*" (tools with "set" in name)',
+            items: {
+                type: 'string',
+            },
+        },
+        noCompressTools: {
+            type: 'array',
+            description: 'Tool name patterns whose original descriptions should always be shown to the LLM (supports wildcards, case-insensitive). Tools are still compressed and cached in the background for efficiency, but their original descriptions are always displayed when listing tools.',
+            items: {
+                type: 'string',
+            },
+        },
+        defaultTimeout: {
+            type: 'number',
+            description: 'Default timeout in seconds for all servers (can be overridden per-server). Default is 30 seconds if not specified.',
+            minimum: 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.',
+                    minimum: 0,
+                    default: 500,
+                },
+                autoStartDaemon: {
+                    type: 'boolean',
+                    description: 'Auto-start daemon when running CLI commands. Default: true.',
+                    default: true,
+                },
+                daemonLogLevel: {
+                    type: 'string',
+                    description: 'Log level for the daemon process. Default: "info".',
+                    enum: ['debug', 'info', 'warn', 'error'],
+                    default: 'info',
+                },
+            },
+            additionalProperties: false,
+        },
+        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' } },
+            ],
+        },
+        compressionFallbackBehavior: {
+            type: 'string',
+            description: "What to show for a tool that has no compressed description yet. 'original' (default) shows the server's original description; 'blank' shows an empty description so uncompressed tools consume no context.",
+            enum: ['original', 'blank'],
+        },
+    },
+    required: ['mcpServers'],
+    additionalProperties: false,
+};
+//# sourceMappingURL=schema.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map