mcp-compress-router 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Andrey Meshkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# MCP Compressing Router
+
+<p align="center">
+    Compress all connected MCP into a single router MCP and save up to 99% on
+    tokens.
+</p>
+
+<p align="center">
+    <img src="docs/assets/mcp-compress-router.png"
+         alt="MCP Compress Router" width="600"/>
+</p>
+
+## The Problem
+
+When you have multiple MCPs every request to the LLM will include ALL their
+tools and descriptions, which can quickly eat up your token limit and increase
+costs.
+
+Check out this [example](docs/assets/tools.json) to understand how
+quickly and how large it can get. This example represents just 3 popular MCP
+servers: Notion MCP, Github MCP and Pylance MCP.
+
+The overhead that is created is about **26K tokens**, but let's check how much
+it actually costs you in USD. I will use Opus API pricing for calculation and
+I'll assume that on average you have a 50-turn coding session (pretty
+reasonable these days).
+
+- Input: `26K tokens * $5 / 1M = $0.13`
+- Cache write (caching is not free): `26K tokens * $6.25 / 1M = $0.1625`
+- Cache read (49 turns): `26K tokens * 49 * $0.50 / 1M = $0.637`
+
+So the total overhead on an average coding session is about **$0.9275**.
+And that's just for 3 MCPs, imagine if you had more!
+
+## The Solution
+
+Instead of sending all the tools and descriptions every time, you can use a
+single router MCP that compresses all the connected MCPs into one with just
+two tools: `get_tool_schema`, `invoke_tool`.
+
+`get_tool_schema` in the description only has a list of MCP servers, optional
+descriptions (you can write them yourself), and a list of tool names for each
+MCP server. [Here is an example](docs/assets/tools-compressed.json) of how the
+compressed version looks like, and it takes about 900 tokens.
+
+If we repeat our exercise with the compressed version, the total overhead on
+an average coding session will be about **$0.032175** so we saved about
+**96.5%** on costs!
+
+This is just a basic example with just 3 MCP servers, the more MCP servers you
+have, the more you save.

package/build/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/cli/add-command.js

@@ -0,0 +1,107 @@
+import { ensureConfigDir, readConfigFile, writeConfigFile, readCredentials, writeCredentials, } from './config-io.js';
+/**
+ * Handles the `add <name> <commandOrUrl> [args...]` subcommand.
+ *
+ * - If commandOrUrl starts with http:// or https://, auto-detects as HTTP.
+ * - Otherwise treats it as a stdio command.
+ * - Writes the entry to the mcpServers object and saves the config file.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param opts - Parsed CLI options.
+ * @returns Human-readable confirmation message.
+ * @throws If the server name already exists.
+ */
+export async function handleAdd(configPath, opts) {
+    await ensureConfigDir(configPath);
+    const servers = await readConfigFile(configPath);
+    if (opts.name in servers) {
+        throw new Error(`Server "${opts.name}" already exists. Use "remove ${opts.name}" first to replace it.`);
+    }
+    // Auto-detect HTTP from URL pattern
+    const isUrl = opts.commandOrUrl.startsWith('http://') || opts.commandOrUrl.startsWith('https://');
+    const type = isUrl ? 'http' : opts.transport;
+    const entry = { type };
+    if (type === 'http') {
+        entry.url = opts.commandOrUrl;
+        if (opts.headers && Object.keys(opts.headers).length > 0) {
+            entry.headers = opts.headers;
+        }
+    }
+    else {
+        entry.command = opts.commandOrUrl;
+        if (opts.rest && opts.rest.length > 0) {
+            entry.args = opts.rest;
+        }
+        if (opts.env && Object.keys(opts.env).length > 0) {
+            entry.env = opts.env;
+        }
+    }
+    servers[opts.name] = entry;
+    await writeConfigFile(configPath, servers);
+    let result = `Added server "${opts.name}" (${type}).`;
+    // For HTTP servers, proactively check whether the server advertises
+    // OAuth metadata. If it does, start the login flow automatically so
+    // the user is not left with an unauthenticated server.
+    if (type === 'http') {
+        try {
+            const loginResult = await tryAutoLogin(configPath, opts.name, opts.commandOrUrl);
+            if (loginResult) {
+                result += `\n${loginResult}`;
+            }
+        }
+        catch {
+            // Best-effort — don't block add on auto-login failure
+        }
+    }
+    return result;
+}
+/**
+ * Probes the server for OAuth metadata and, if found, runs the login
+ * flow automatically. The probed auth requirement is cached in
+ * `credentials.json` regardless of the login outcome so the `list`
+ * command can show auth status without re-probing.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param name - Server name just added.
+ * @param url - Server URL to probe for OAuth metadata.
+ * @returns The login confirmation message, or undefined if the server
+ * does not advertise OAuth (or the probe failed).
+ */
+async function tryAutoLogin(configPath, name, url) {
+    const { discoverAuthorizationServerMetadata } = await import('@modelcontextprotocol/sdk/client/auth.js');
+    let requirement;
+    let hasOAuth;
+    try {
+        const metadata = await discoverAuthorizationServerMetadata(new URL(url));
+        hasOAuth = metadata !== undefined;
+        requirement = hasOAuth ? 'oauth' : 'none';
+    }
+    catch {
+        // Probe failed — cache 'unknown' and don't block the add.
+        await persistAuthRequirement(configPath, name, 'unknown');
+        return undefined;
+    }
+    // Cache the requirement regardless of the login outcome.
+    await persistAuthRequirement(configPath, name, requirement);
+    if (!hasOAuth) {
+        return undefined;
+    }
+    const { handleLogin } = await import('./login-command.js');
+    return handleLogin(configPath, name);
+}
+/**
+ * Caches the probed auth requirement for a server in credentials.json,
+ * preserving any previously stored tokens or client registration.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param name - Server name.
+ * @param requirement - The probed auth requirement to cache.
+ */
+async function persistAuthRequirement(configPath, name, requirement) {
+    const existing = await readCredentials(configPath);
+    await writeCredentials(configPath, name, {
+        ...existing[name],
+        authRequirement: requirement,
+        checkedAt: new Date().toISOString(),
+    });
+}

package/build/cli/config-io.js

@@ -0,0 +1,213 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { parseJsonc } from '../utils/index.js';
+/**
+ * Type guard for Node.js system errors that carry a `code` property.
+ *
+ * @param err - The error to inspect.
+ * @returns True if the error has a string `code` property (e.g., 'ENOENT').
+ */
+function isNodeError(err) {
+    return err instanceof Error && typeof err.code === 'string';
+}
+/**
+ * Derives the credentials.json path from the config path.
+ *
+ * @param configPath - Absolute path to mcp.json.
+ * @returns Absolute path to credentials.json in the same directory.
+ */
+function getCredentialsPath(configPath) {
+    return path.join(path.dirname(configPath), 'credentials.json');
+}
+/**
+ * Ensures the parent directory and config file exist.
+ * If the file does not exist, creates it with an empty mcpServers object.
+ * Idempotent — does nothing if the file already exists.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ */
+export async function ensureConfigDir(configPath) {
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    try {
+        await fs.access(configPath);
+    }
+    catch {
+        await fs.writeFile(configPath, JSON.stringify({ mcpServers: {} }, null, 2) + '\n');
+    }
+}
+/**
+ * Reads the mcpServers object from the config file.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @returns The raw mcpServers object.
+ * @throws If the file is missing, invalid JSON, or missing mcpServers key.
+ */
+export async function readConfigFile(configPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(configPath, 'utf-8');
+    }
+    catch {
+        throw new Error(`Config file not found: ${configPath}`);
+    }
+    let parsed;
+    try {
+        parsed = parseJsonc(raw, configPath);
+    }
+    catch {
+        throw new Error(`Failed to parse config file: ${configPath}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || !('mcpServers' in parsed)) {
+        throw new Error(`Config file must contain an mcpServers object`);
+    }
+    return parsed.mcpServers;
+}
+/**
+ * Writes the mcpServers object to the config file.
+ * Preserves non-credential top-level keys other than mcpServers.
+ * Silently drops any legacy "credentials" key (credentials are now
+ * stored in credentials.json).
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param mcpServers - The mcpServers object to write.
+ */
+export async function writeConfigFile(configPath, mcpServers) {
+    // Preserve any existing top-level keys except credentials
+    // (credentials are stored in credentials.json)
+    let existing = { mcpServers: {} };
+    try {
+        const raw = await fs.readFile(configPath, 'utf-8');
+        existing = parseJsonc(raw, configPath);
+    }
+    catch {
+        // File doesn't exist or is invalid — start fresh
+    }
+    // Drop legacy credentials key that may exist from before the
+    // credentials.json separation
+    delete existing.credentials;
+    existing.mcpServers = mcpServers;
+    await fs.writeFile(configPath, JSON.stringify(existing, null, 2) + '\n');
+}
+/**
+ * Reads the credentials object from credentials.json.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @returns The credentials store, or empty object if the file does not exist.
+ * @throws If the file exists but cannot be read (permission denied) or
+ *   contains invalid JSON.
+ */
+export async function readCredentials(configPath) {
+    const credPath = getCredentialsPath(configPath);
+    let raw;
+    try {
+        raw = await fs.readFile(credPath, 'utf-8');
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT') {
+            return {};
+        }
+        throw new Error(`Failed to read credentials file: ${credPath}`, { cause: err });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Credentials file contains invalid JSON: ${credPath}`, { cause: err });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Credentials file must contain a JSON object: ${credPath}`);
+    }
+    return parsed;
+}
+/**
+ * Writes (or overwrites) credentials for a single server.
+ * Preserves existing mcpServers and credentials for other servers.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param name - Server name.
+ * @param credentials - The credentials to store.
+ */
+export async function writeCredentials(configPath, name, credentials, logger) {
+    const credPath = getCredentialsPath(configPath);
+    // Read existing store (or start fresh)
+    let store = {};
+    try {
+        const raw = await fs.readFile(credPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null) {
+            store = parsed;
+        }
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT') {
+            // File does not exist — will be created below
+        }
+        else {
+            throw new Error(`Failed to read credentials file for writing: ${credPath}`, { cause: err });
+        }
+    }
+    // Merge in the new/updated entry
+    store[name] = credentials;
+    // Determine if this is a first-time creation
+    let isNewFile = false;
+    try {
+        await fs.access(credPath);
+    }
+    catch {
+        isNewFile = true;
+    }
+    // Write the store
+    await fs.writeFile(credPath, JSON.stringify(store, null, 2) + '\n');
+    // On first creation, set restrictive permissions (owner read/write only)
+    if (isNewFile) {
+        try {
+            await fs.chmod(credPath, 0o600);
+        }
+        catch {
+            // chmod is a no-op on Windows; if it somehow fails on Unix, log a warning
+            if (logger) {
+                logger.info(`Warning: Failed to set restrictive permissions on new credentials file: ${credPath}`);
+            }
+        }
+        // On Windows, verify chmod did something; if not, log a warning
+        if (process.platform === 'win32' && logger) {
+            logger.info(`Warning: File permissions cannot be restricted on Windows. ` +
+                `Credentials stored in: ${credPath}`);
+        }
+    }
+}
+/**
+ * Removes credentials for a server from the config file.
+ * No-op if the server has no stored credentials.
+ * Deletes the credentials file when the last entry is removed.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param name - Server name.
+ */
+export async function removeCredentials(configPath, name) {
+    const credPath = getCredentialsPath(configPath);
+    let store = {};
+    try {
+        const raw = await fs.readFile(credPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null) {
+            store = parsed;
+        }
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT') {
+            // File does not exist — nothing to remove
+            return;
+        }
+        throw new Error(`Failed to read credentials file for removal: ${credPath}`, { cause: err });
+    }
+    delete store[name];
+    if (Object.keys(store).length === 0) {
+        // No remaining entries — delete the file entirely
+        await fs.unlink(credPath);
+    }
+    else {
+        await fs.writeFile(credPath, JSON.stringify(store, null, 2) + '\n');
+    }
+}

package/build/cli/config-path-note.js

@@ -0,0 +1,21 @@
+/**
+ * Appends the resolved config file path to a command's output when no
+ * explicit `-c`/`--config` flag was provided, so the user can see which
+ * default configuration file was operated on.
+ *
+ * When an explicit path was given via `-c`, the output is returned
+ * unchanged.
+ *
+ * @param result - The original command output (may be empty or undefined).
+ * @param explicitConfig - The raw `-c` value, or undefined when omitted.
+ * @param resolvedPath - The config file path that was actually used.
+ * @returns The output followed by a default-path note when `-c` was
+ * omitted; otherwise the original output unchanged.
+ */
+export function appendConfigPathNote(result, explicitConfig, resolvedPath) {
+    if (explicitConfig !== undefined) {
+        return result;
+    }
+    const note = `Using config: ${resolvedPath}`;
+    return result ? `${result}\n${note}` : note;
+}

package/build/cli/get-command.js

@@ -0,0 +1,49 @@
+import { ensureConfigDir, readConfigFile } from './config-io.js';
+/**
+ * Handles the `get <name>` subcommand: prints details for one server.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param name - Server name to look up.
+ * @returns Human-readable output to print to stdout.
+ * @throws If the server name is not found.
+ */
+export async function handleGet(configPath, name) {
+    await ensureConfigDir(configPath);
+    const servers = await readConfigFile(configPath);
+    const entry = servers[name];
+    if (!entry) {
+        const available = Object.keys(servers);
+        const hint = available.length > 0
+            ? ` Available servers: ${available.join(', ')}`
+            : ' No servers configured.';
+        throw new Error(`Server "${name}" not found.${hint}`);
+    }
+    const lines = [];
+    lines.push(`Name: ${name}`);
+    lines.push(`Type: ${entry.type}`);
+    if (entry.description) {
+        lines.push(`Description: ${entry.description}`);
+    }
+    if (entry.command) {
+        lines.push(`Command: ${entry.command}`);
+    }
+    if (entry.args && entry.args.length > 0) {
+        lines.push(`Args: ${entry.args.join(' ')}`);
+    }
+    if (entry.env && Object.keys(entry.env).length > 0) {
+        lines.push('Environment:');
+        for (const [k, v] of Object.entries(entry.env)) {
+            lines.push(`  ${k}=${v}`);
+        }
+    }
+    if (entry.url) {
+        lines.push(`URL: ${entry.url}`);
+    }
+    if (entry.headers && Object.keys(entry.headers).length > 0) {
+        lines.push('Headers:');
+        for (const [k, v] of Object.entries(entry.headers)) {
+            lines.push(`  ${k}: ${v}`);
+        }
+    }
+    return lines.join('\n');
+}

package/build/cli/index.js

@@ -0,0 +1,6 @@
+export { handleAdd } from './add-command.js';
+export { handleRemove } from './remove-command.js';
+export { handleGet } from './get-command.js';
+export { handleList } from './list-command.js';
+export { handleLogin } from './login-command.js';
+export { handleLogout } from './logout-command.js';

package/build/cli/list-command.js

@@ -0,0 +1,79 @@
+import { ensureConfigDir, readConfigFile, readCredentials } from './config-io.js';
+import { computeAuthStatus } from '../services/index.js';
+/**
+ * Builds the display string for the command (stdio) or URL (http)
+ * column of a server row.
+ *
+ * @param server - Typed downstream server config.
+ * @returns The command plus args, or the URL.
+ */
+function buildCommandOrUrl(server) {
+    if (server.type === 'stdio') {
+        const parts = [];
+        if (server.command) {
+            parts.push(server.command);
+        }
+        if (server.args?.length) {
+            parts.push(...server.args);
+        }
+        return parts.join(' ');
+    }
+    return server.url ?? '';
+}
+/**
+ * Renders the list header and server rows as a fixed-width table. The
+ * final (Auth) column is left unpadded so lines never carry trailing
+ * whitespace.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @param rows - Prepared server rows.
+ * @returns The formatted table as a single string.
+ */
+function formatList(configPath, rows) {
+    const header = `Configuration was loaded from ${configPath}`;
+    if (rows.length === 0) {
+        return header;
+    }
+    const nameWidth = Math.max('Name'.length, ...rows.map((r) => r.name.length));
+    const typeWidth = Math.max('Type'.length, ...rows.map((r) => r.type.length));
+    const commandWidth = Math.max('CommandOrUrl'.length, ...rows.map((r) => r.commandOrUrl.length));
+    const pad = (val, width) => val.padEnd(width);
+    const columns = (name, type, command, auth) => `${pad(name, nameWidth)}  ${pad(type, typeWidth)}  ${pad(command, commandWidth)}  ${auth}`;
+    return [
+        header,
+        '',
+        columns('Name', 'Type', 'CommandOrUrl', 'Auth'),
+        ...rows.map((r) => columns(r.name, r.type, r.commandOrUrl, r.auth)),
+    ].join('\n');
+}
+/**
+ * Handles the `list` subcommand: prints the configuration file that was
+ * loaded followed by a table of every configured server and its auth
+ * status. Reads only local files (`mcp.json` and `credentials.json`) —
+ * no network access.
+ *
+ * @param configPath - Absolute path to the mcp.json file.
+ * @returns Human-readable output to print to stdout.
+ */
+export async function handleList(configPath) {
+    await ensureConfigDir(configPath);
+    const servers = await readConfigFile(configPath);
+    const credentials = await readCredentials(configPath);
+    const rows = Object.entries(servers).map(([name, entry]) => {
+        const typed = {
+            name,
+            type: entry.type,
+            command: entry.command,
+            args: entry.args,
+            url: entry.url,
+            headers: entry.headers,
+        };
+        return {
+            name,
+            type: entry.type,
+            commandOrUrl: buildCommandOrUrl(typed),
+            auth: computeAuthStatus(typed, credentials[name]),
+        };
+    });
+    return formatList(configPath, rows);
+}