mcp-compress-router 1.5.2 → 1.5.5

package/README.md

@@ -20,6 +20,9 @@
 - [The Solution](#the-solution)
 - [Prerequisites](#prerequisites)
 - [Quick Start](#quick-start)
+    - [1. Connect your coding agent](#1-connect-your-coding-agent)
+    - [2. Add downstream MCP servers](#2-add-downstream-mcp-servers)
+    - [3. Verify and use](#3-verify-and-use)
 - [Configuration](#configuration)
     - [Config File Location](#config-file-location)
     - [Adding Downstream Servers](#adding-downstream-servers)
@@ -29,17 +32,12 @@
     - [Inspecting Tools](#inspecting-tools)
     - [OAuth](#oauth)
         - [Redirect URL](#redirect-url)
-        - [GitHub MCP (special case)](#github-mcp-special-case)
-        - [Figma MCP (special case)](#figma-mcp-special-case)
+        - [GitHub MCP with OAuth (special case)](#github-mcp-with-oauth-special-case)
+        - [Figma MCP with OAuth (special case)](#figma-mcp-with-oauth-special-case)
     - [Custom Headers](#custom-headers)
     - [Secrets and Variable Expansion](#secrets-and-variable-expansion)
-- [Connecting Coding Agents](#connecting-coding-agents)
-    - [Opencode](#opencode)
-    - [Claude Code](#claude-code)
-    - [Codex](#codex)
-    - [GitHub Copilot](#github-copilot)
 - [How It Works](#how-it-works)
-- [Aknowledgements](#acknowledgements)
+- [Acknowledgements](#acknowledgements)
 
 ## The Problem
 
@@ -95,17 +93,99 @@ have, the more you save.
 
 The router is published on npm as
 [`mcp-compress-router`](https://www.npmjs.com/package/mcp-compress-router).
-You do not need to install it — just run it with `npx`:
+You do not need to install it — just run it with `npx`.
+
+Setup is two steps: first connect your coding agent to the router, then
+add the MCP servers you want to compress behind it.
+
+### 1. Connect your coding agent
+
+Point your agent at the router the same way you would point it at any
+other MCP server. The router reads its server list from a
+[user-wide config file](#config-file-location) by default, so register
+it at the **user** scope (or your agent's equivalent) — every project
+then gets the same compressed catalog with no per-project setup.
+
+- **Claude Code** — see the
+  [Claude Code MCP docs](https://code.claude.com/docs/en/mcp).
+  Add it at `user` scope so it applies everywhere (Claude Code also
+  supports `local` for a single private project and `project` for a
+  shareable `.mcp.json`):
+
+  ```sh
+  claude mcp add mcp-compress-router --scope user -- npx -y mcp-compress-router@latest
+  ```
+
+- **Opencode** — see the
+  [opencode MCP servers docs](https://opencode.ai/docs/mcp-servers/).
+
+  ```sh
+  opencode mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
+  ```
+
+- **Codex** — see the
+  [Codex MCP docs](https://developers.openai.com/codex/mcp).
+
+  ```sh
+  codex mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
+  ```
+
+- **GitHub Copilot (VS Code)** — see the
+  [VS Code MCP docs](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
+  Open the Command Palette (`Cmd+Shift+P`) →
+  `MCP: Open User Configuration` and add the server block under
+  `mcp.servers` (project-level `.vscode/mcp.json` is also supported
+  and merged with the user-level settings, project taking precedence):
+
+  ```json
+  {
+    "servers": {
+      "mcp-compress-router": {
+        "command": "npx",
+        "args": ["-y", "mcp-compress-router@latest"]
+      }
+    }
+  }
+  ```
+
+### 2. Add downstream MCP servers
+
+Use the `add` command to register each MCP server you want to compress.
+The router writes them to its [config file](#config-file-location) and
+they appear in the catalog the next time the router starts.
 
 ```bash
 npx mcp-compress-router@latest add playwright -- npx -y @playwright/mcp
 ```
 
-This registers a downstream MCP server named `playwright` and writes it
-to your [config file](#config-file-location). Repeat for every MCP server
-you want to compress.
+Add a description so the LLM can pick the right server, and use
+environment variables to keep secrets out of the config:
+
+```bash
+npx mcp-compress-router@latest add github \
+  --description "GitHub API tools" \
+  -e GITHUB_PERSONAL_TOKEN=ghp_xxx \
+  -- npx -y @modelcontextprotocol/server-github
+```
 
-Then point your [coding agent](#connecting-coding-agents) at the router:
+Repeat for every MCP server you want to compress. See
+[Adding Downstream Servers](#adding-downstream-servers) for HTTP
+servers, custom headers, OAuth, and other options.
+
+### 3. Verify and use
+
+Check that everything is wired up:
+
+```bash
+npx mcp-compress-router@latest list
+```
+
+Then start a new session in your coding agent. The agent picks up the
+router's two tools — `get_tool_schema` and `invoke_tool` — and uses
+them to discover and call every server you added, without the agent
+ever seeing the raw tool listings of each downstream server.
+
+Under the hood your agent spawns the router as a child process with:
 
 ```bash
 npx mcp-compress-router@latest
@@ -113,7 +193,8 @@ npx mcp-compress-router@latest
 
 When started without a subcommand, the router runs the MCP server over
 stdio and exposes exactly two tools (`get_tool_schema`,
-`invoke_tool`) to the agent.
+`invoke_tool`) to the agent. You normally do not run this yourself —
+your agent spawns the router automatically.
 
 ## Configuration
 
@@ -338,6 +419,16 @@ A good rule of thumb:
 - Use `low` sparingly — only when full descriptions must be visible
   without a `get_tool_schema` call, since it costs the most tokens.
 
+> **Note for Claude Code:** Claude Code truncates any single tool
+> description at 2000 characters. The router renders the entire
+> compressed catalog into the `get_tool_schema` description that the
+> agent receives on every turn, so with several downstream servers or
+> many tools per server the `high`, `medium`, or `low` listings can
+> exceed that limit and get truncated — breaking routing. When using
+> Claude Code, set `compressionLevel: "max"` on your servers (or pass
+> `--compression-level max` to `add`) so each server's tool listing
+> collapses to a comma-separated single line.
+
 ### Inspecting Tools
 
 To see exactly which tools a server advertises — and which are
@@ -640,52 +731,6 @@ MY_SERVER_TOKEN=secret-token
 
 Shell environment variables always take precedence over `.env` values.
 
-## Connecting Coding Agents
-
-Once your downstream servers are configured, connect your agent to the
-router the same way you would connect any other MCP server — by
-pointing it at `npx mcp-compress-router@latest`. The examples below assume the
-default [config location](#config-file-location); pass `-c <path>` if
-you use a custom one.
-
-### Opencode
-
-```sh
-opencode mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
-```
-
-### Claude Code
-
-```sh
-claude mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
-```
-
-### Codex
-
-```sh
-codex mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
-```
-
-### GitHub Copilot (VS Code)
-
-Add this to `.vscode/mcp.json` in your workspace (project-level, applies
-only to that workspace), or to your **user-level** MCP settings which
-apply across every workspace: open the Command Palette (`Cmd+Shift+P`) →
-`MCP: Open User Configuration` and add the same `servers`
-block under the `mcp` key. Project-level and user-level entries are
-merged, with project-level taking precedence.
-
-```json
-{
-  "servers": {
-    "mcp-compress-router": {
-      "command": "npx",
-      "args": ["-y", "mcp-compress-router@latest"]
-    }
-  }
-}
-```
-
 ## How It Works
 
 Once connected, the agent sees exactly **two tools**:

package/build/cli/add-command.js

@@ -17,7 +17,7 @@ function validateToolListPatterns(field, patterns) {
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
-            throw new Error(`Invalid "${field}" pattern "${pattern}": ${reason}`);
+            throw new Error(`Invalid "${field}" pattern "${pattern}": ${reason}`, { cause: err });
         }
     }
 }

package/build/cli/register-commands.js

@@ -3,7 +3,7 @@ import { handleAdd, handleRemove, handleGet, handleList, handleLogin, handleLogo
 import { runRouter } from './router-runner.js';
 /**
  * Collects repeated `--header "K: V"` flags into a headers record.
- * @internal — Exported for tests only; not part of the public module API.
+ * @internal Exported for tests only; not part of the public module API.
  */
 export function collectHeaders(value, previous) {
     const colonIdx = value.indexOf(':');
@@ -16,7 +16,7 @@ export function collectHeaders(value, previous) {
 }
 /**
  * Collects repeated `-e KEY=value` flags into an env record.
- * @internal — Exported for tests only; not part of the public module API.
+ * @internal Exported for tests only; not part of the public module API.
  */
 export function collectEnv(value, previous) {
     const eqIdx = value.indexOf('=');
@@ -29,7 +29,7 @@ export function collectEnv(value, previous) {
 }
 /**
  * Collects repeated `--flag <value>` flags into an ordered string array.
- * @internal — Exported for tests only; not part of the public module API.
+ * @internal Exported for tests only; not part of the public module API.
  */
 export function collectStringArray(value, previous) {
     return [...previous, value];
@@ -38,7 +38,7 @@ export function collectStringArray(value, previous) {
  * Coerces a `--port` flag value into an integer. Throws on non-numeric
  * values so the user gets a clear error before any network activity.
  * Range validation is deferred to the command handlers.
- * @internal — Exported for tests only; not part of the public module API.
+ * @internal Exported for tests only; not part of the public module API.
  */
 export function parsePort(value) {
     const port = Number(value);

package/build/services/config.js

@@ -297,7 +297,9 @@ function validateToolList(name, field, value) {
         }
         catch (err) {
             const reason = err instanceof Error ? err.message : String(err);
-            throw new Error(`Server "${name}" has invalid "${field}" pattern "${entry}": ${reason}`);
+            throw new Error(`Server "${name}" has invalid "${field}" pattern "${entry}": ${reason}`, {
+                cause: err,
+            });
         }
         patterns.push(entry);
     }

package/build/services/discovery.js

@@ -1,6 +1,7 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { getDownstreamTimeoutMs } from '../utils/index.js';
 /** JSON-RPC error code for "Method not found". */
 const METHOD_NOT_FOUND = -32601;
 /**
@@ -21,12 +22,14 @@ function isMethodNotFound(err) {
  * propagated as a connection failure.
  *
  * @param client - A connected MCP client.
+ * @param options - Optional {@link RequestOptions} (e.g. `timeout`)
+ *   forwarded to `client.listTools()`.
  * @returns The list-tools result (possibly empty).
  * @throws Any non-"Method not found" error from `listTools()`.
  */
-export async function listToolsOrEmpty(client) {
+export async function listToolsOrEmpty(client, options) {
     try {
-        return await client.listTools();
+        return await client.listTools(undefined, options);
     }
     catch (err) {
         if (isMethodNotFound(err)) {
@@ -59,9 +62,14 @@ export async function discoverSingleServer(server, logger, getAuthProvider) {
         type: server.type,
     });
     const transport = createTransport(server, getAuthProvider);
+    // Cap the initialize handshake and tools/list call so a server that
+    // accepts the connection but never replies surfaces a clear error
+    // instead of hanging the command indefinitely (the SDK's own default
+    // is 60s; we use a shorter, configurable budget).
+    const requestOptions = { timeout: getDownstreamTimeoutMs() };
     try {
-        await client.connect(transport);
-        const listResult = await listToolsOrEmpty(client);
+        await client.connect(transport, requestOptions);
+        const listResult = await listToolsOrEmpty(client, requestOptions);
         logger.info(`Connected to "${server.name}" — ${listResult.tools.length} tools discovered`, {
             server: server.name,
             toolCount: listResult.tools.length,
@@ -86,7 +94,7 @@ export async function discoverSingleServer(server, logger, getAuthProvider) {
             type: server.type,
             error: message,
         });
-        throw new Error(`Failed to connect to server "${server.name}": ${message}`);
+        throw new Error(`Failed to connect to server "${server.name}": ${message}`, { cause: err });
     }
     finally {
         await client.close().catch(() => { });

package/build/services/oauth-discovery.js

@@ -1,3 +1,4 @@
+import { createTimeoutFetch, getAuthDiscoveryTimeoutMs } from '../utils/index.js';
 /**
  * Discovers OAuth metadata for a downstream MCP server following the
  * MCP 2025-06-18 authorization spec two-step flow:
@@ -29,6 +30,10 @@
  */
 export async function discoverAuth(serverUrl) {
     const { discoverOAuthProtectedResourceMetadata, discoverAuthorizationServerMetadata } = await import('@modelcontextprotocol/sdk/client/auth.js');
+    // The SDK discovery helpers use a raw fetch with no timeout; a server
+    // that hangs its well-known endpoint would trap discovery forever. Pass
+    // a fetch that aborts after a short, configurable budget.
+    const fetchFn = createTimeoutFetch(getAuthDiscoveryTimeoutMs());
     // Tracks the last error seen across all candidates so the caller can be
     // notified when discovery failed entirely (vs. cleanly finding nothing).
     let lastError;
@@ -36,7 +41,7 @@ export async function discoverAuth(serverUrl) {
     // recorded and treated as "not found" so the next candidate is tried.
     const safeDiscoverAs = async (url) => {
         try {
-            return await discoverAuthorizationServerMetadata(url);
+            return await discoverAuthorizationServerMetadata(url, { fetchFn });
         }
         catch (err) {
             lastError = err;
@@ -49,7 +54,7 @@ export async function discoverAuth(serverUrl) {
     // legacy-server path, not a probe failure.
     let resourceMetadata;
     try {
-        resourceMetadata = await discoverOAuthProtectedResourceMetadata(serverUrl);
+        resourceMetadata = await discoverOAuthProtectedResourceMetadata(serverUrl, {}, fetchFn);
     }
     catch {
         // No PRM published; fall through to direct AS discovery below.

package/build/services/server-connection.js

@@ -3,6 +3,7 @@ import { createTransport, listToolsOrEmpty } from './discovery.js';
 import { OAuthCredentialManager } from './oauth.js';
 import { saveToolCache, loadToolCache } from './tool-cache.js';
 import { isAuthError } from './index.js';
+import { getDownstreamTimeoutMs } from '../utils/index.js';
 /**
  * 30-second cooldown after a failed reconnect attempt. Subsequent
  * `invokeWithRecovery` calls within this window return the cached
@@ -218,8 +219,12 @@ export class ServerConnection {
             ? (_s) => this.authProvider
             : undefined;
         const transport = createTransport(this.server, getAuthProvider);
-        await this.client.connect(transport);
-        const listResult = await listToolsOrEmpty(this.client);
+        // Cap the initialize handshake and tools/list call so a hung
+        // downstream server fails fast instead of stalling startup (or
+        // self-recovery) for the SDK's 60s default.
+        const requestOptions = { timeout: getDownstreamTimeoutMs() };
+        await this.client.connect(transport, requestOptions);
+        const listResult = await listToolsOrEmpty(this.client, requestOptions);
         return listResult.tools.map((t) => ({
             name: t.name,
             description: t.description,

package/build/utils/index.js

@@ -6,3 +6,4 @@ export { expandEnvField } from './expand-env.js';
 export { Logger } from './logger.js';
 export { parseJsonc } from './parse-jsonc.js';
 export { VALID_COMPRESSION_LEVELS, isCompressionLevel } from './compression-level.js';
+export { getDownstreamTimeoutMs, getAuthDiscoveryTimeoutMs, createTimeoutFetch, } from './timeout.js';

package/build/utils/timeout.js

@@ -0,0 +1,75 @@
+import process from 'node:process';
+/**
+ * Default timeout (ms) for a downstream server's `initialize` request and
+ * `tools/list` call during discovery. The MCP SDK's own default is 60s;
+ * we cap these fast handshake operations sooner so a server that accepts
+ * the TCP/TLS connection but never replies (a real-world hang observed on
+ * some Streamable HTTP servers behind CDNs) surfaces a clear error instead
+ * of blocking the `tools` command or router startup indefinitely.
+ *
+ * @internal Exported for tests only; not part of the public module API.
+ */
+export const DEFAULT_DOWNSTREAM_TIMEOUT_MS = 30_000;
+/**
+ * Default timeout (ms) for OAuth metadata discovery probes (RFC 9728 /
+ * RFC 8414 well-known endpoint fetches). These are best-effort probes;
+ * a server that hangs its well-known endpoint must not stall startup.
+ *
+ * @internal Exported for tests only; not part of the public module API.
+ */
+export const DEFAULT_AUTH_DISCOVERY_TIMEOUT_MS = 10_000;
+/**
+ * Reads a positive-integer environment variable, returning `undefined`
+ * when unset or invalid (non-integer or non-positive). Invalid values
+ * silently fall back to the default rather than aborting startup.
+ */
+function readPositiveIntEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * Resolves the downstream connect/listTools timeout in milliseconds.
+ * Override with `MCP_COMPRESS_ROUTER_DOWNSTREAM_TIMEOUT_MS` (a positive
+ * integer); invalid values fall back to
+ * {@link DEFAULT_DOWNSTREAM_TIMEOUT_MS}.
+ */
+export function getDownstreamTimeoutMs() {
+    return (readPositiveIntEnv('MCP_COMPRESS_ROUTER_DOWNSTREAM_TIMEOUT_MS') ?? DEFAULT_DOWNSTREAM_TIMEOUT_MS);
+}
+/**
+ * Resolves the OAuth discovery probe timeout in milliseconds. Override
+ * with `MCP_COMPRESS_ROUTER_AUTH_DISCOVERY_TIMEOUT_MS` (a positive
+ * integer); invalid values fall back to
+ * {@link DEFAULT_AUTH_DISCOVERY_TIMEOUT_MS}.
+ */
+export function getAuthDiscoveryTimeoutMs() {
+    return (readPositiveIntEnv('MCP_COMPRESS_ROUTER_AUTH_DISCOVERY_TIMEOUT_MS') ??
+        DEFAULT_AUTH_DISCOVERY_TIMEOUT_MS);
+}
+/**
+ * Wraps the global `fetch` so each request aborts after `timeoutMs`.
+ * The caller's own `init.signal` (if any) is honored alongside the
+ * timeout signal via `AbortSignal.any`.
+ *
+ * Used to add a request-level timeout to SDK helpers (OAuth metadata
+ * discovery) that accept a custom `fetchFn` but expose no timeout option
+ * of their own — without it, a server that hangs the well-known endpoint
+ * traps discovery forever.
+ *
+ * @param timeoutMs - Per-request timeout in milliseconds.
+ * @returns A fetch-compatible function that aborts on timeout.
+ */
+export function createTimeoutFetch(timeoutMs) {
+    return (input, init) => {
+        const timeoutSignal = AbortSignal.timeout(timeoutMs);
+        const signal = init?.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+        return fetch(input, { ...init, signal });
+    };
+}

package/build/utils/validate-glob.js

@@ -16,6 +16,6 @@ export function validateGlobPattern(pattern) {
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`Invalid glob pattern "${pattern}": ${reason}`);
+        throw new Error(`Invalid glob pattern "${pattern}": ${reason}`, { cause: err });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-compress-router",
-  "version": "1.5.2",
+  "version": "1.5.5",
   "description": "Compress all connected MCP servers into a single router MCP to save tokens",
   "license": "MIT",
   "type": "module",
@@ -25,17 +25,17 @@
     "url": "https://github.com/ameshkov/mcp-compress-router/issues"
   },
   "scripts": {
-    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
-    "typecheck": "tsc && tsc --project tsconfig.test.json",
+    "build": "tsc -p tsconfig.app.json && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "typecheck": "tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.test.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "clean": "rm -rf node_modules build",
     "format:check": "prettier --check --no-error-on-unmatched-pattern --cache . && markdownlint-cli2 .",
     "format:fix": "prettier --write --no-error-on-unmatched-pattern --cache . && markdownlint-cli2 --fix .",
-    "lint": "eslint src && pnpm knip",
-    "lint:fix": "eslint src --fix",
+    "lint": "oxlint src && pnpm knip",
+    "lint:fix": "oxlint src --fix",
     "knip": "knip --production",
-    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run test",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run build && pnpm run test",
     "prepare": "husky || true"
   },
   "files": [
@@ -51,25 +51,23 @@
   ],
   "author": "Andrey Meshkov <am@adguard.com>",
   "devDependencies": {
-    "@eslint/js": "9.16.0",
-    "@types/node": "24.13.2",
+    "@types/node": "26.1.2",
     "@types/picomatch": "4.0.3",
-    "eslint": "9.16.0",
     "husky": "9.1.7",
-    "knip": "6.6.2",
-    "markdownlint-cli2": "0.22.0",
-    "prettier": "3.7.4",
-    "tsx": "4.20.3",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.57.0",
-    "vitest": "3.2.4"
+    "knip": "6.29.0",
+    "markdownlint-cli2": "0.23.2",
+    "oxlint": "1.76.0",
+    "prettier": "3.9.6",
+    "tsx": "4.23.1",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.24.3",
-    "commander": "14.0.2",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "commander": "15.0.0",
     "dotenv": "17.4.2",
     "jsonc-parser": "3.3.1",
-    "picomatch": "4.0.4",
-    "zod": "3.25.76"
+    "picomatch": "4.0.5",
+    "zod": "4.4.3"
   }
 }