mcp-compress-router 1.0.0

package/build/services/auth-status.js

@@ -0,0 +1,113 @@
+import { readCredentials, writeCredentials } from '../cli/config-io.js';
+/**
+ * Probes a downstream HTTP server's OAuth discovery endpoint to
+ * determine whether it advertises OAuth support. Makes a single probe
+ * of the server's well-known authorization-server metadata.
+ *
+ * stdio servers never support OAuth, so they short-circuit to `'none'`
+ * without any network access.
+ *
+ * @param server - Typed downstream server config.
+ * @param logger - Optional logger for diagnostic output on probe errors.
+ * @returns `'oauth'` when metadata is advertised, `'none'` when it is
+ *   absent, or `'unknown'` on network/probe errors.
+ * @internal Exported for tests only; not part of the public module API.
+ */
+export async function probeAuthRequirement(server, logger) {
+    if (server.type === 'stdio') {
+        return 'none';
+    }
+    if (!server.url) {
+        return 'unknown';
+    }
+    try {
+        const { discoverAuthorizationServerMetadata } = await import('@modelcontextprotocol/sdk/client/auth.js');
+        const metadata = await discoverAuthorizationServerMetadata(new URL(server.url));
+        return metadata ? 'oauth' : 'none';
+    }
+    catch (err) {
+        logger?.error(`Failed to probe OAuth metadata for "${server.name}"`, {
+            server: server.name,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return 'unknown';
+    }
+}
+/**
+ * Determines the final display auth status for a server using only
+ * local (non-network) information: the cached auth requirement from
+ * `credentials.json`, any stored tokens, and configured HTTP headers.
+ *
+ * @param server - Typed downstream server config.
+ * @param stored - The server's entry from `credentials.json`, or
+ *   `undefined` when no entry exists.
+ * @returns The auth status label shown in the `list` table.
+ */
+export function computeAuthStatus(server, stored) {
+    if (server.type === 'stdio') {
+        return 'none';
+    }
+    // A static Authorization header takes precedence over OAuth state.
+    if (hasAuthorizationHeader(server.headers)) {
+        return 'header';
+    }
+    const requirement = stored?.authRequirement ?? 'unknown';
+    const hasTokens = Boolean(stored?.tokens?.access_token);
+    switch (requirement) {
+        case 'oauth':
+            return hasTokens ? 'authenticated' : 'requires login';
+        case 'none':
+            return 'public';
+        case 'unknown':
+            return 'unknown';
+    }
+}
+/**
+ * Returns true when the headers map contains an `Authorization` header
+ * (case-insensitive key match).
+ *
+ * @param headers - Optional HTTP headers map.
+ */
+function hasAuthorizationHeader(headers) {
+    if (!headers) {
+        return false;
+    }
+    return Object.keys(headers).some((key) => key.toLowerCase() === 'authorization');
+}
+/**
+ * Probes every HTTP downstream server for OAuth metadata and caches the
+ * result in `credentials.json` so the `list` command can show auth
+ * status without any network access. stdio servers are skipped (they
+ * never support OAuth). Probe errors are recorded as `'unknown'` so a
+ * single flaky server never blocks startup.
+ *
+ * The network probes run in parallel for speed, but the credential file
+ * writes are serialized to avoid concurrent read-modify-write races.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param servers - Typed downstream server configs.
+ * @param logger - Logger for diagnostic output.
+ */
+export async function persistAuthRequirements(configPath, servers, logger) {
+    // Read the existing store once so per-server tokens and client
+    // registration survive the auth-requirement update.
+    const existing = await readCredentials(configPath);
+    const httpServers = servers.filter((server) => server.type !== 'stdio');
+    // Network-bound: probe in parallel for speed.
+    const results = await Promise.all(httpServers.map(async (server) => ({
+        name: server.name,
+        requirement: await probeAuthRequirement(server, logger),
+    })));
+    const checkedAt = new Date().toISOString();
+    // Serialize writes to avoid concurrent file read-modify-write races.
+    for (const { name, requirement } of results) {
+        await writeCredentials(configPath, name, {
+            ...existing[name],
+            authRequirement: requirement,
+            checkedAt,
+        });
+    }
+    logger.debug('Cached auth requirements', {
+        servers: Object.fromEntries(results.map((r) => [r.name, r.requirement])),
+    });
+}

package/build/services/catalog.js

@@ -0,0 +1,54 @@
+/**
+ * Builds the immutable tool catalog from discovered server data.
+ *
+ * @param discovered - Results from parallel discovery.
+ * @returns An immutable ToolCatalog.
+ */
+export function buildCatalog(discovered) {
+    const toolMap = new Map();
+    const servers = discovered.map((ds) => {
+        for (const tool of ds.tools) {
+            const key = `${ds.name}::${tool.name}`;
+            toolMap.set(key, tool);
+        }
+        return {
+            name: ds.name,
+            description: ds.description,
+            tools: ds.tools,
+        };
+    });
+    return { servers, toolMap };
+}
+/**
+ * Looks up tool schemas in the catalog by server and tool names.
+ *
+ * @param catalog - The tool catalog.
+ * @param serverName - The server to look up.
+ * @param toolNames - The tool names to retrieve.
+ * @returns The matching tool descriptors.
+ * @throws If the server or any tool is not found.
+ */
+export function lookupTools(catalog, serverName, toolNames) {
+    const server = catalog.servers.find((s) => s.name === serverName);
+    if (!server) {
+        const available = catalog.servers.map((s) => s.name).join(', ');
+        throw new Error(`Server "${serverName}" not found. Available servers: ${available}`);
+    }
+    const results = [];
+    const missing = [];
+    for (const toolName of toolNames) {
+        const key = `${serverName}::${toolName}`;
+        const tool = catalog.toolMap.get(key);
+        if (!tool) {
+            missing.push(toolName);
+        }
+        else {
+            results.push(tool);
+        }
+    }
+    if (missing.length > 0) {
+        const valid = server.tools.map((t) => t.name).join(', ');
+        throw new Error(`Tool(s) not found on server "${serverName}": ${missing.join(', ')}. Valid tools: ${valid}`);
+    }
+    return results;
+}

package/build/services/config.js

@@ -0,0 +1,273 @@
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as fs from 'node:fs/promises';
+import { expandEnvField, parseJsonc } from '../utils/index.js';
+/** Recognized MCP transport types. */
+const VALID_TYPES = new Set(['stdio', 'http', 'streamable-http']);
+/** Per-application directory name used inside the user data folder. */
+const APP_DIR_NAME = 'mcp-compress-router';
+/**
+ * Resolves the base configuration directory.
+ *
+ * Priority: (1) MCP_COMPRESS_ROUTER_HOME env var, (2) the
+ * platform-specific default (see {@link defaultConfigDir}). This is a
+ * synchronous function that only reads environment variables and
+ * performs path operations.
+ *
+ * @returns The absolute path to the configuration directory.
+ */
+export function resolveConfigDir() {
+    return process.env.MCP_COMPRESS_ROUTER_HOME ?? defaultConfigDir();
+}
+/**
+ * Returns the platform-specific default configuration directory.
+ *
+ * - Windows (`win32`): `%APPDATA%\mcp-compress-router` (falls back to
+ *   `%USERPROFILE%\AppData\Roaming\mcp-compress-router` when `APPDATA`
+ *   is unset).
+ * - macOS (`darwin`): `~/Library/Application Support/mcp-compress-router`.
+ * - Linux and other Unixes: `~/.local/share/mcp-compress-router`
+ *   (XDG Base Directory style).
+ *
+ * The function is pure and side-effect free so it can be unit tested
+ * for every platform regardless of the host the tests run on.
+ *
+ * @param platform - The Node platform identifier. Defaults to the host's.
+ * @param home - The user home directory. Defaults to the host's.
+ * @param appData - The Windows `%APPDATA%` path. Defaults to the env var.
+ * @returns The absolute path to the default configuration directory.
+ * @internal Exported for tests only; not part of the public module API.
+ */
+export function defaultConfigDir(platform = process.platform, home = os.homedir(), appData = process.env.APPDATA) {
+    switch (platform) {
+        case 'win32':
+            return path.join(appData ?? path.join(home, 'AppData', 'Roaming'), APP_DIR_NAME);
+        case 'darwin':
+            return path.join(home, 'Library', 'Application Support', APP_DIR_NAME);
+        default:
+            return path.join(home, '.local', 'share', APP_DIR_NAME);
+    }
+}
+/**
+ * Resolves the configuration file path.
+ *
+ * Priority: (1) explicit path argument, (2) MCP_COMPRESS_ROUTER_HOME env var,
+ * (3) the platform-specific default (see {@link defaultConfigDir}). Within the
+ * resolved directory, `mcp.jsonc` is preferred over `mcp.json` when both exist.
+ * If neither exists, returns `mcp.json` (created on first use).
+ *
+ * @param explicitPath - An explicit config path, or undefined.
+ * @returns The resolved absolute path to the config file.
+ */
+export async function resolveConfigPath(explicitPath) {
+    if (explicitPath !== undefined) {
+        return explicitPath;
+    }
+    return resolveDirectoryConfig(resolveConfigDir());
+}
+/**
+ * Returns the existing mcp.jsonc or mcp.json path from a directory,
+ * preferring jsonc. When neither file exists, returns mcp.json.
+ */
+async function resolveDirectoryConfig(dir) {
+    const jsoncPath = path.join(dir, 'mcp.jsonc');
+    const jsonPath = path.join(dir, 'mcp.json');
+    if (await pathExists(jsoncPath))
+        return jsoncPath;
+    if (await pathExists(jsonPath))
+        return jsonPath;
+    return jsonPath;
+}
+/**
+ * Checks whether a file exists at the given path.
+ */
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates the "type" field and per-type required fields for a server.
+ *
+ * @param name - Server name (for error messages).
+ * @param server - The server entry object from mcp.json.
+ * @returns The validated transport type.
+ * @throws If type is missing, unsupported, or required fields are absent.
+ */
+function validateServerType(name, server) {
+    const rawType = server.type;
+    if (typeof rawType !== 'string' || rawType.length === 0) {
+        throw new Error(`Server "${name}" is missing required "type" field. Must be one of: ${[...VALID_TYPES].join(', ')}`);
+    }
+    if (!VALID_TYPES.has(rawType)) {
+        throw new Error(`Server "${name}" has unsupported type "${rawType}". Must be one of: ${[...VALID_TYPES].join(', ')}`);
+    }
+    const type = rawType;
+    if (type === 'stdio') {
+        if (typeof server.command !== 'string' || server.command.length === 0) {
+            throw new Error(`Server "${name}" (stdio) is missing required "command" field`);
+        }
+    }
+    else {
+        if (typeof server.url !== 'string' || server.url.length === 0) {
+            throw new Error(`Server "${name}" (${type}) is missing required "url" field`);
+        }
+    }
+    return type;
+}
+/**
+ * Converts a Record<string, unknown> to Record<string, string> by coercing
+ * each value to a string, or returns undefined when the input is missing.
+ *
+ * @param obj - The raw object or undefined/null.
+ * @returns The string map or undefined.
+ */
+function toStringMap(obj) {
+    if (obj === undefined || obj === null || typeof obj !== 'object') {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, String(v)]));
+}
+/**
+ * Expands env vars in every value of a string map.
+ *
+ * @param map - The string map to expand.
+ * @param keyContext - Context prefix for expansion error messages (e.g. "env").
+ * @param entryContext - Server-level context (e.g. 'server "github"').
+ * @returns The expanded string map.
+ */
+function expandStringMap(map, keyContext, entryContext) {
+    return Object.fromEntries(Object.entries(map).map(([k, v]) => [
+        k,
+        expandEnvField(v, `${entryContext} ${keyContext}.${k}`),
+    ]));
+}
+/**
+ * Extracts and expands raw fields from a server entry.
+ *
+ * @param entryContext - Human-readable context string for env var expansion.
+ * @param server - The server entry object from mcp.json.
+ * @returns An object containing expanded command, args, env, url, and headers.
+ */
+function buildServerFields(entryContext, server) {
+    const rawCommand = typeof server.command === 'string' ? server.command : undefined;
+    const rawArgs = Array.isArray(server.args)
+        ? server.args.map(String)
+        : undefined;
+    const rawEnv = toStringMap(server.env);
+    const rawUrl = typeof server.url === 'string' ? server.url : undefined;
+    const rawHeaders = toStringMap(server.headers);
+    const command = rawCommand !== undefined ? expandEnvField(rawCommand, `${entryContext} command`) : undefined;
+    const args = rawArgs?.map((a, i) => expandEnvField(a, `${entryContext} args[${i}]`));
+    const env = rawEnv !== undefined ? expandStringMap(rawEnv, 'env', entryContext) : undefined;
+    const url = rawUrl !== undefined ? expandEnvField(rawUrl, `${entryContext} url`) : undefined;
+    const headers = rawHeaders !== undefined ? expandStringMap(rawHeaders, 'headers', entryContext) : undefined;
+    return { command, args, env, url, headers };
+}
+/**
+ * Parses the optional `oauth` block from a server entry with env expansion.
+ *
+ * @param entryContext - Human-readable context string for env var expansion.
+ * @param server - The server entry object from mcp.json.
+ * @returns The parsed OAuth config, or undefined if absent.
+ * @throws If the oauth block is not an object.
+ */
+function parseOauthBlock(entryContext, server) {
+    if (server.oauth === undefined || server.oauth === null) {
+        return undefined;
+    }
+    if (typeof server.oauth !== 'object') {
+        throw new Error(`Server "${entryContext.slice(8)}" oauth block must be an object`);
+    }
+    const oauthRaw = server.oauth;
+    const rawClientId = typeof oauthRaw.clientId === 'string' ? oauthRaw.clientId : undefined;
+    const rawClientSecret = typeof oauthRaw.clientSecret === 'string' ? oauthRaw.clientSecret : undefined;
+    const rawScope = typeof oauthRaw.scope === 'string' ? oauthRaw.scope : undefined;
+    const clientId = rawClientId !== undefined
+        ? expandEnvField(rawClientId, `${entryContext} oauth.clientId`)
+        : undefined;
+    const clientSecret = rawClientSecret !== undefined
+        ? expandEnvField(rawClientSecret, `${entryContext} oauth.clientSecret`)
+        : undefined;
+    const scope = rawScope !== undefined ? expandEnvField(rawScope, `${entryContext} oauth.scope`) : undefined;
+    const oauth = {};
+    if (clientId !== undefined)
+        oauth.clientId = clientId;
+    if (clientSecret !== undefined)
+        oauth.clientSecret = clientSecret;
+    if (scope !== undefined)
+        oauth.scope = scope;
+    return oauth;
+}
+/**
+ * Parses a single server entry from the mcpServers object.
+ *
+ * Orchestrates validation, field extraction, and env var expansion for
+ * one named server entry, then returns the resulting config object.
+ *
+ * @param name - Server name (key in mcpServers).
+ * @param entry - The raw server value.
+ * @param names - Set of already-seen names for duplicate detection.
+ * @returns A validated DownstreamServerConfig.
+ * @throws If the entry is invalid or the name is a duplicate.
+ */
+function parseServerEntry(name, entry, names) {
+    if (typeof entry !== 'object' || entry === null) {
+        throw new Error(`Server "${name}" must be an object`);
+    }
+    const server = entry;
+    const type = validateServerType(name, server);
+    if (names.has(name)) {
+        throw new Error(`Duplicate server name: "${name}"`);
+    }
+    names.add(name);
+    const entryContext = `server "${name}"`;
+    const fields = buildServerFields(entryContext, server);
+    const description = typeof server.description === 'string' ? server.description : undefined;
+    const oauth = parseOauthBlock(entryContext, server);
+    return { name, type, ...fields, description, oauth };
+}
+/**
+ * Loads and validates the MCP configuration file.
+ *
+ * Reads a JSON file with a top-level mcpServers object, extracts stdio
+ * entries, and validates uniqueness. HTTP servers and variable expansion
+ * are deferred to later slices.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @returns An array of validated DownstreamServerConfig objects.
+ * @throws If the file is missing, invalid JSON, contains duplicate names,
+ *   or contains zero servers (the router has nothing to route).
+ */
+export async function loadConfig(configPath) {
+    const raw = await fs.readFile(configPath, 'utf-8');
+    let parsed;
+    try {
+        parsed = parseJsonc(raw, configPath);
+    }
+    catch {
+        throw new Error(`Failed to parse config file: ${configPath}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('Config file must contain a JSON object with mcpServers');
+    }
+    const obj = parsed;
+    const mcpServers = obj.mcpServers;
+    if (typeof mcpServers !== 'object' || mcpServers === null) {
+        throw new Error('Config file must contain an mcpServers object');
+    }
+    const names = new Set();
+    const servers = [];
+    for (const [name, entry] of Object.entries(mcpServers)) {
+        servers.push(parseServerEntry(name, entry, names));
+    }
+    if (servers.length === 0) {
+        throw new Error('Configuration contains no downstream MCP servers. Add at least one ' +
+            'server before starting the router (e.g. via the "add" subcommand).');
+    }
+    return servers;
+}

package/build/services/discovery.js

@@ -0,0 +1,104 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/**
+ * Connects to all configured stdio servers in parallel and discovers
+ * their tools. Fails fast if any server is unreachable.
+ *
+ * @param servers - Validated downstream server configs.
+ * @param logger - Structured logger for diagnostic output.
+ * @param getAuthProvider - Optional factory to provide OAuth credentials for HTTP servers.
+ * @returns Discovered server data and live client connections.
+ * @throws If any server cannot be connected or tools cannot be listed.
+ */
+export async function connectAndDiscover(servers, logger, getAuthProvider) {
+    const results = await Promise.all(servers.map((server) => connectSingleServer(server, logger, getAuthProvider)));
+    const serversList = [];
+    const clients = new Map();
+    for (const { server, client } of results) {
+        serversList.push(server);
+        clients.set(server.name, client);
+    }
+    return { servers: serversList, clients };
+}
+/**
+ * Connects to a single downstream server and discovers its tools.
+ *
+ * @param server - Downstream server configuration.
+ * @param logger - Structured logger for diagnostic output.
+ * @param getAuthProvider - Optional factory to provide OAuth credentials.
+ * @returns The discovered server data and live client connection.
+ * @throws If the server cannot be connected or tools cannot be listed.
+ */
+async function connectSingleServer(server, logger, getAuthProvider) {
+    const client = new Client({ name: 'mcp-compress-router', version: '1.0.0' }, { capabilities: {} });
+    logger.info(`Connecting to downstream server "${server.name}"`, {
+        server: server.name,
+        type: server.type,
+    });
+    const transport = createTransport(server, getAuthProvider);
+    try {
+        await client.connect(transport);
+        const listResult = await client.listTools();
+        logger.info(`Connected to "${server.name}" — ${listResult.tools.length} tools discovered`, {
+            server: server.name,
+            toolCount: listResult.tools.length,
+            tools: listResult.tools.map((t) => t.name),
+        });
+        const tools = listResult.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        }));
+        return {
+            server: {
+                name: server.name,
+                description: server.description,
+                tools,
+            },
+            client,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`Failed to connect to server "${server.name}"`, {
+            server: server.name,
+            type: server.type,
+            error: message,
+        });
+        throw new Error(`Failed to connect to server "${server.name}": ${message}`);
+    }
+}
+/**
+ * Creates the appropriate transport for a downstream server config.
+ *
+ * @param server - Downstream server configuration.
+ * @param getAuthProvider - Optional factory to provide OAuth credentials.
+ * @returns A configured transport instance (stdio or HTTP).
+ * @throws If required configuration (command or url) is missing.
+ */
+function createTransport(server, getAuthProvider) {
+    if (server.type === 'stdio') {
+        if (!server.command) {
+            throw new Error(`Server "${server.name}" (stdio) is missing command`);
+        }
+        return new StdioClientTransport({
+            command: server.command,
+            args: server.args,
+            env: server.env,
+        });
+    }
+    // http or streamable-http
+    if (!server.url) {
+        throw new Error(`Server "${server.name}" (${server.type}) is missing url`);
+    }
+    const requestInit = {};
+    if (server.headers) {
+        requestInit.headers = server.headers;
+    }
+    const authProvider = getAuthProvider?.(server);
+    return new StreamableHTTPClientTransport(new URL(server.url), {
+        requestInit: Object.keys(requestInit).length > 0 ? requestInit : undefined,
+        authProvider,
+    });
+}

package/build/services/index.js

@@ -0,0 +1,6 @@
+export { buildCatalog, lookupTools } from './catalog.js';
+export { resolveConfigDir, resolveConfigPath, loadConfig } from './config.js';
+export { connectAndDiscover } from './discovery.js';
+export { invokeDownstreamTool } from './invoker.js';
+export { OAuthCredentialManager } from './oauth.js';
+export { computeAuthStatus, persistAuthRequirements } from './auth-status.js';

package/build/services/invoker.js

@@ -0,0 +1,72 @@
+/**
+ * Checks whether an error message indicates an authentication failure.
+ *
+ * @param message - The error message string to inspect.
+ * @returns `true` when the message contains an auth-related keyword.
+ */
+function isAuthError(message) {
+    return (message.includes('Unauthorized') || message.includes('unauthorized') || message.includes('auth'));
+}
+/**
+ * Looks up a downstream MCP client by server name.
+ *
+ * @param clients - Map of server name to live MCP client.
+ * @param serverName - The downstream server name.
+ * @param logger - Structured logger for diagnostic output.
+ * @returns The matching client.
+ * @throws When no client is registered for the given server name.
+ */
+function getClient(clients, serverName, logger) {
+    const client = clients.get(serverName);
+    if (!client) {
+        logger.error('Downstream server not found for invocation', {
+            server: serverName,
+            availableServers: [...clients.keys()],
+        });
+        throw new Error(`Server "${serverName}" not found. Available servers: ${[...clients.keys()].join(', ')}`);
+    }
+    return client;
+}
+/**
+ * Invokes a tool on a downstream MCP server and returns the result
+ * verbatim.
+ *
+ * @param clients - Map of server name to live MCP client.
+ * @param serverName - The downstream server name.
+ * @param toolName - The tool to invoke.
+ * @param args - The arguments to pass to the tool.
+ * @param logger - Structured logger for diagnostic output.
+ * @returns The downstream call result verbatim (content blocks
+ *   unchanged in structure and order).
+ */
+export async function invokeDownstreamTool(clients, serverName, toolName, args, logger) {
+    logger.debug('Forwarding invocation to downstream server', {
+        server: serverName,
+        tool: toolName,
+        arguments: args,
+    });
+    const client = getClient(clients, serverName, logger);
+    try {
+        const result = (await client.callTool({ name: toolName, arguments: args }));
+        logger.debug('Downstream invocation result', {
+            server: serverName,
+            tool: toolName,
+            isError: result.isError ?? false,
+            contentBlockCount: result.content.length,
+        });
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isAuthError(message)) {
+            logger.error('Downstream server authentication failed', {
+                server: serverName,
+                tool: toolName,
+                error: message,
+            });
+            throw new Error(`Authentication failed for server "${serverName}". ` +
+                `Run "mcp-compress-router login ${serverName}" to re-authenticate.`);
+        }
+        throw err;
+    }
+}