mcp-compress-router 1.0.0

package/build/services/oauth.js

@@ -0,0 +1,145 @@
+import { readCredentials, writeCredentials, removeCredentials } from '../cli/config-io.js';
+/**
+ * Implements OAuthClientProvider backed by credentials.json credential storage.
+ *
+ * Each instance manages credentials for one downstream server.
+ * When `oauth` overrides are present in the server config, dynamic
+ * client registration is skipped and static client info is used.
+ */
+export class OAuthCredentialManager {
+    _configPath;
+    _server;
+    _codeVerifier;
+    _staticClientInfo;
+    _actualPort = 0;
+    constructor(configPath, server) {
+        this._configPath = configPath;
+        this._server = server;
+        // If oauth overrides are present, set up static client info
+        if (server.oauth?.clientId) {
+            const info = {
+                client_id: server.oauth.clientId,
+            };
+            if (server.oauth.clientSecret) {
+                info.client_secret = server.oauth.clientSecret;
+            }
+            this._staticClientInfo = info;
+        }
+    }
+    get redirectUrl() {
+        // Return the callback URL with the actual port assigned by the OS.
+        // Falls back to port 0 until setActualPort() is called by login-command.
+        return `http://localhost:${this._actualPort}/callback`;
+    }
+    get clientMetadata() {
+        return {
+            redirect_uris: [this.redirectUrl],
+            client_name: 'mcp-compress-router',
+        };
+    }
+    /**
+     * Sets the actual listening port of the temporary HTTP callback server.
+     * Must be called before startAuthorization so the redirect_uri is correct.
+     *
+     * @param port - The actual port the callback server is listening on.
+     */
+    setActualPort(port) {
+        this._actualPort = port;
+    }
+    /**
+     * Whether this manager has static (override) client information,
+     * bypassing dynamic client registration.
+     */
+    hasStaticClient() {
+        return this._staticClientInfo !== undefined;
+    }
+    async clientInformation() {
+        // Static overrides take precedence
+        if (this._staticClientInfo) {
+            return this._staticClientInfo;
+        }
+        const creds = await this._loadCredentials();
+        return creds?.clientRegistration;
+    }
+    async saveClientInformation(clientInformation) {
+        if (this._staticClientInfo) {
+            // Don't overwrite static overrides
+            return;
+        }
+        const creds = await this._loadCredentials();
+        const updated = {
+            clientRegistration: clientInformation,
+            // Preserve existing tokens; omit when none (tokens is optional).
+            ...(creds?.tokens ? { tokens: creds.tokens } : {}),
+            // Successful OAuth client registration proves the server supports
+            // OAuth. Override any stale cached requirement.
+            authRequirement: 'oauth',
+            checkedAt: new Date().toISOString(),
+        };
+        await writeCredentials(this._configPath, this._server.name, updated);
+    }
+    async tokens() {
+        const creds = await this._loadCredentials();
+        if (!creds?.tokens?.access_token) {
+            return undefined;
+        }
+        return creds.tokens;
+    }
+    async saveTokens(tokens) {
+        const creds = await this._loadCredentials();
+        const updated = {
+            clientRegistration: creds?.clientRegistration,
+            tokens: {
+                access_token: tokens.access_token,
+                refresh_token: tokens.refresh_token,
+                expires_in: tokens.expires_in,
+                scope: tokens.scope,
+                token_type: tokens.token_type,
+            },
+            // A successful OAuth token exchange proves the server supports
+            // OAuth. Override any stale cached requirement (e.g. 'none' from
+            // a failed startup probe) with 'oauth'.
+            authRequirement: 'oauth',
+            checkedAt: new Date().toISOString(),
+        };
+        await writeCredentials(this._configPath, this._server.name, updated);
+    }
+    async redirectToAuthorization(authorizationUrl) {
+        // Open the authorization URL in the default browser.
+        const { openBrowser } = await import('../utils/open-browser.js');
+        await openBrowser(authorizationUrl.toString());
+    }
+    async saveCodeVerifier(codeVerifier) {
+        this._codeVerifier = codeVerifier;
+    }
+    async codeVerifier() {
+        if (!this._codeVerifier) {
+            throw new Error('No code verifier saved');
+        }
+        return this._codeVerifier;
+    }
+    /**
+     * Removes stored OAuth tokens and client registration for this server
+     * (used by logout). Preserves the cached auth requirement so the
+     * `list` command still shows the correct status (e.g. "requires
+     * login") after logout. When there is no cached auth requirement to
+     * keep, the entire entry is removed (and the credentials file deleted
+     * when it becomes empty).
+     */
+    async clearTokens() {
+        this._codeVerifier = undefined;
+        const creds = await this._loadCredentials();
+        if (creds?.authRequirement) {
+            await writeCredentials(this._configPath, this._server.name, {
+                authRequirement: creds.authRequirement,
+                checkedAt: creds.checkedAt,
+            });
+            return;
+        }
+        await removeCredentials(this._configPath, this._server.name);
+    }
+    async _loadCredentials() {
+        const all = await readCredentials(this._configPath);
+        return all[this._server.name];
+    }
+}

package/build/text-format.js

@@ -0,0 +1,24 @@
+/**
+ * Renders the compact catalog as Markdown text suitable for inclusion
+ * in the `get_tool_schema` tool description.
+ *
+ * Format:
+ *   ## {server name}
+ *   {description (optional)}
+ *   {tool1}, {tool2}, ...
+ *
+ * @param servers - The catalog server entries.
+ * @returns Compact catalog text.
+ */
+export function renderCompactCatalog(servers) {
+    const lines = [];
+    for (const server of servers) {
+        lines.push(`## ${server.name}`);
+        if (server.description) {
+            lines.push(server.description);
+        }
+        lines.push(server.tools.map((t) => t.name).join(', '));
+        lines.push(''); // blank line between servers
+    }
+    return lines.join('\n').trimEnd();
+}

package/build/tools/get-tool-schema.js

@@ -0,0 +1,61 @@
+import { lookupTools } from '../services/index.js';
+import { renderCompactCatalog } from '../utils/index.js';
+import { z } from 'zod';
+/**
+ * Schema for get_tool_schema parameters.
+ */
+export const GetToolSchemaInputSchema = {
+    server: z.string().describe('The name of the MCP server to query.'),
+    tools: z.array(z.string()).min(1).max(50).describe('List of tool names to get the schema for.'),
+};
+/**
+ * Creates the get_tool_schema handler closure over the catalog.
+ *
+ * @param catalog - The immutable tool catalog built at startup.
+ * @param logger - Structured logger for diagnostic output.
+ * @returns A handler function for the get_tool_schema MCP tool.
+ */
+export function createGetToolSchemaHandler(catalog, logger) {
+    return async (params) => {
+        logger.info('get_tool_schema called', {
+            server: params.server,
+            tools: params.tools,
+        });
+        try {
+            const schemas = lookupTools(catalog, params.server, params.tools);
+            const result = schemas.map((t) => ({
+                name: t.name,
+                description: t.description ?? '',
+                inputSchema: t.inputSchema,
+            }));
+            logger.debug('get_tool_schema result', { result });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error('get_tool_schema failed', {
+                server: params.server,
+                tools: params.tools,
+                error: message,
+            });
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    };
+}
+/**
+ * Builds the description string for get_tool_schema from the catalog.
+ *
+ * @param catalog - The tool catalog.
+ * @returns A description string containing the compact catalog.
+ */
+export function buildGetToolSchemaDescription(catalog) {
+    const compact = renderCompactCatalog(catalog.servers);
+    return ('Get the JSON schema for one or more tools from a connected MCP server.\n\n' +
+        'Available MCP servers and their tools:\n\n' +
+        compact);
+}

package/build/tools/index.js

@@ -0,0 +1,2 @@
+export { createGetToolSchemaHandler, buildGetToolSchemaDescription, GetToolSchemaInputSchema, } from './get-tool-schema.js';
+export { createInvokeToolHandler, InvokeToolInputSchema } from './invoke-tool.js';

package/build/tools/invoke-tool.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { validateArguments } from '../utils/index.js';
+import { lookupTools } from '../services/index.js';
+/**
+ * Schema for invoke_tool parameters.
+ */
+export const InvokeToolInputSchema = {
+    server: z.string().describe('The name of the MCP server that has the tool.'),
+    tool: z.string().describe('The name of the tool to invoke.'),
+    arguments: z.object({}).passthrough().describe('The arguments to pass to the tool.'),
+};
+/**
+ * Validates invocation arguments against the tool's cached input
+ * schema. Returns an error response when validation fails, or null
+ * when arguments are valid.
+ *
+ * @param catalog - The immutable tool catalog.
+ * @param server - The downstream server name.
+ * @param tool - The tool name.
+ * @param args - The arguments to validate.
+ * @param logger - Structured logger for diagnostic output.
+ * @returns A validation error response, or null when valid.
+ */
+function validateInvokeArgs(catalog, server, tool, args, logger) {
+    const descriptor = catalog.toolMap.get(`${server}::${tool}`);
+    if (descriptor) {
+        const validation = validateArguments(args, descriptor.inputSchema);
+        if (!validation.valid) {
+            logger.error('invoke_tool validation failed', {
+                server,
+                tool,
+                errors: validation.errors,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Invalid arguments:\n${validation.errors.join('\n')}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Creates the invoke_tool handler closure over the catalog and an
+ * invoker function. The handler receives only the catalog and a
+ * function — never raw transport clients.
+ *
+ * @param catalog - The immutable tool catalog built at startup.
+ * @param invokeDownstream - Function to forward a tool call to the
+ *   correct downstream server.
+ * @param logger - Structured logger for diagnostic output.
+ * @returns A handler function for the invoke_tool MCP tool.
+ */
+export function createInvokeToolHandler(catalog, invokeDownstream, logger) {
+    return async (params) => {
+        logger.info('invoke_tool called', {
+            server: params.server,
+            tool: params.tool,
+        });
+        logger.debug('invoke_tool arguments', { arguments: params.arguments });
+        try {
+            // Validate server and tool exist in catalog
+            lookupTools(catalog, params.server, [params.tool]);
+            // Validate arguments against the cached input schema
+            const validationError = validateInvokeArgs(catalog, params.server, params.tool, params.arguments, logger);
+            if (validationError)
+                return validationError;
+            const result = await invokeDownstream(params.server, params.tool, params.arguments);
+            // Return content verbatim. The result type is looser than what
+            // the MCP SDK expects, so we cast through unknown to satisfy
+            // the handler signature while preserving the actual content
+            // structure.
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error('invoke_tool failed', {
+                server: params.server,
+                tool: params.tool,
+                error: message,
+            });
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    };
+}

package/build/types.js

@@ -0,0 +1 @@
+export {};

package/build/utils/expand-env.js

@@ -0,0 +1,47 @@
+/**
+ * Error thrown when a `${VAR}` reference references an undefined
+ * environment variable and has no default value.
+ *
+ * @public
+ */
+export class ExpandEnvError extends Error {
+    /** The name of the unresolved variable. */
+    variableName;
+    /** The field or context where the unresolved variable was found. */
+    context;
+    constructor(variableName, context) {
+        super(`Environment variable "${variableName}" is not set (referenced in ${context})`);
+        this.name = 'ExpandEnvError';
+        this.variableName = variableName;
+        this.context = context;
+    }
+}
+// Matches ${VAR} and ${VAR:-default}
+const ENV_REF_RE = /\$\{([A-Za-z_]\w*)(?::-(.*?))?\}/g;
+/**
+ * Expands `${VAR}` and `${VAR:-default}` references in a string value.
+ *
+ * - `${VAR}` is replaced with `process.env[VAR]`. If VAR is not set,
+ *   throws {@link ExpandEnvError}.
+ * - `${VAR:-default}` is replaced with `process.env[VAR]` if set and
+ *   non-empty, otherwise with `default`.
+ *
+ * @param value - The string containing potentially unexpanded references.
+ * @param context - Human-readable description of where the value comes
+ *   from (e.g. `server "github" command`), used in error messages.
+ * @returns The expanded string.
+ * @throws {ExpandEnvError} When a `${VAR}` reference has no default and
+ *   the variable is not set in the environment.
+ */
+export function expandEnvField(value, context) {
+    return value.replace(ENV_REF_RE, (match, varName, defaultVal) => {
+        const envValue = process.env[varName];
+        if (envValue !== undefined && envValue !== '') {
+            return envValue;
+        }
+        if (defaultVal !== undefined) {
+            return defaultVal;
+        }
+        throw new ExpandEnvError(varName, context);
+    });
+}

package/build/utils/index.js

@@ -0,0 +1,7 @@
+export { renderCompactCatalog } from './text-format.js';
+export { validateArguments } from './validate-arguments.js';
+export { expandEnvField } from './expand-env.js';
+export { Logger } from './logger.js';
+export { parseJsonc } from './parse-jsonc.js';
+/** @public */
+export { openBrowser } from './open-browser.js';

package/build/utils/logger.js

@@ -0,0 +1,78 @@
+const LEVEL_ORDER = {
+    error: 0,
+    info: 1,
+    debug: 2,
+};
+/**
+ * A lightweight structured logger that writes timestamped JSON lines
+ * to stderr with configurable level filtering.
+ */
+export class Logger {
+    currentLevel;
+    /**
+     * Creates a Logger at the given level. Messages below this level
+     * are silently dropped.
+     *
+     * @param level - Minimum log level to emit.
+     */
+    constructor(level = 'info') {
+        this.currentLevel = level;
+    }
+    /**
+     * Returns true if messages at the given level would be emitted.
+     *
+     * @param level - The level to check.
+     */
+    isLevelEnabled(level) {
+        return LEVEL_ORDER[level] <= LEVEL_ORDER[this.currentLevel];
+    }
+    /**
+     * Changes the minimum log level at runtime.
+     *
+     * @param level - New minimum log level.
+     */
+    setLevel(level) {
+        this.currentLevel = level;
+    }
+    /**
+     * Emits an error-level log entry.
+     *
+     * @param message - Human-readable error message.
+     * @param context - Optional key-value metadata (server name, error details).
+     */
+    error(message, context) {
+        this.log('error', message, context);
+    }
+    /**
+     * Emits an info-level log entry. Suppressed when level is 'error'.
+     *
+     * @param message - Human-readable info message.
+     * @param context - Optional key-value metadata.
+     */
+    info(message, context) {
+        this.log('info', message, context);
+    }
+    /**
+     * Emits a debug-level log entry. Suppressed unless level is 'debug'.
+     *
+     * @param message - Human-readable debug message.
+     * @param context - Optional key-value metadata (payloads, state).
+     */
+    debug(message, context) {
+        this.log('debug', message, context);
+    }
+    log(level, message, context) {
+        if (!this.isLevelEnabled(level)) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+        };
+        if (context !== undefined && Object.keys(context).length > 0) {
+            entry.context = context;
+        }
+        process.stderr.write(JSON.stringify(entry) + '\n');
+    }
+}

package/build/utils/open-browser.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+/**
+ * Opens a URL in the default browser using the platform-native command.
+ *
+ * The browser command can be overridden with the
+ * `MCP_COMPRESS_ROUTER_BROWSER` environment variable. Set it to the
+ * executable plus any preset arguments (e.g.
+ * `node /path/to/headless-browser.js --flag`); the URL is always appended
+ * as a single, final argument. No shell is used, so there is no
+ * shell-injection risk — this also makes the override safe to drive OAuth
+ * flows in headless and CI environments.
+ *
+ * @param url - The URL to open.
+ */
+export async function openBrowser(url) {
+    const customBrowser = process.env.MCP_COMPRESS_ROUTER_BROWSER;
+    if (customBrowser && customBrowser.trim().length > 0) {
+        const [command, ...presetArgs] = customBrowser.trim().split(/\s+/);
+        return spawnBrowser(command, [...presetArgs, url]);
+    }
+    const platform = process.platform;
+    if (platform === 'darwin') {
+        return spawnBrowser('open', [url]);
+    }
+    if (platform === 'win32') {
+        // `start` is a shell built-in, so shell: true is unavoidable on Windows.
+        // No user-controlled string is interpolated into the command template.
+        return spawnBrowser('start', ['""', url], { shell: true });
+    }
+    return spawnBrowser('xdg-open', [url]);
+}
+/**
+ * Spawns a browser command and resolves once it has spawned.
+ *
+ * The browser process is fire-and-forget; this only waits for a successful
+ * spawn, not for the process to exit.
+ *
+ * @param command - The executable to run.
+ * @param args - Arguments to pass to the executable (including the URL).
+ * @param options - Optional spawn options (e.g. `shell: true` on Windows).
+ * @throws If the process fails to spawn.
+ */
+function spawnBrowser(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = options ? spawn(command, args, options) : spawn(command, args);
+        child.on('error', reject);
+        child.on('spawn', () => resolve());
+    });
+}

package/build/utils/parse-jsonc.js

@@ -0,0 +1,24 @@
+import { parse, printParseErrorCode } from 'jsonc-parser';
+/**
+ * Parses JSON or JSONC (comments + trailing commas) text.
+ *
+ * The parser is fault-tolerant: trailing commas, extra whitespace, and
+ * other minor issues produce warnings but still yield a result. Only
+ * unrecoverable syntax errors throw.
+ *
+ * @param text - The text to parse.
+ * @param context - Human-readable description of where the text comes
+ *   from (e.g. a file path), used in error messages.
+ * @returns The parsed value.
+ * @throws Error when the text contains unrecoverable syntax errors.
+ */
+export function parseJsonc(text, context) {
+    const errors = [];
+    const result = parse(text, errors);
+    // parse() uses error recovery — only the first error that prevents
+    // any valid result makes result undefined.
+    if (result === undefined && errors.length > 0) {
+        throw new Error(`Failed to parse ${context}: ${printParseErrorCode(errors[0].error)}`);
+    }
+    return result;
+}

package/build/utils/text-format.js

@@ -0,0 +1,24 @@
+/**
+ * Renders the compact catalog as Markdown text suitable for inclusion
+ * in the `get_tool_schema` tool description.
+ *
+ * Format:
+ *   ## {server name}
+ *   {description (optional)}
+ *   {tool1}, {tool2}, ...
+ *
+ * @param servers - The catalog server entries.
+ * @returns Compact catalog text.
+ */
+export function renderCompactCatalog(servers) {
+    const lines = [];
+    for (const server of servers) {
+        lines.push(`## ${server.name}`);
+        if (server.description) {
+            lines.push(server.description);
+        }
+        lines.push(server.tools.map((t) => t.name).join(', '));
+        lines.push(''); // blank line between servers
+    }
+    return lines.join('\n').trimEnd();
+}

package/build/utils/types.js

@@ -0,0 +1 @@
+export {};