mcp-compress-router 1.5.0 → 1.5.2

package/build/cli/router-runner.js

@@ -1,4 +1,5 @@
-import { resolveConfigPath, persistAuthRequirements, loadConfig, ServerConnection, invokeWithRecovery, buildCatalog, } from '../services/index.js';
+import process from 'node:process';
+import { resolveConfigPath, persistAuthRequirements, loadConfig, ServerConnection, invokeWithRecovery, buildCatalog, ShutdownCoordinator, installShutdownTriggers, } from '../services/index.js';
 import { Logger } from '../utils/index.js';
 import { createGetToolSchemaHandler, buildGetToolSchemaDescription, GetToolSchemaInputSchema, createInvokeToolHandler, InvokeToolInputSchema, } from '../tools/index.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -43,6 +44,8 @@ async function connectAllServers(servers, configPath, logger) {
  * @param connections - Live ServerConnection instances keyed by name.
  * @param selectionByServer - Per-server tool selection for re-filtering.
  * @param logger - Structured logger.
+ * @returns A cleanup function that closes the MCP server (and its stdio
+ *   transport) during shutdown.
  */
 async function startRouterServer(catalog, connections, selectionByServer, logger) {
     const router = new McpServer({
@@ -67,6 +70,29 @@ async function startRouterServer(catalog, connections, selectionByServer, logger
     const transport = new StdioServerTransport();
     await router.connect(transport);
     logger.info('Server started on stdio');
+    return async () => {
+        try {
+            await router.close();
+        }
+        catch {
+            // Ignore close errors during shutdown — the process is exiting.
+        }
+    };
+}
+/**
+ * Closes every downstream server connection in parallel. Each
+ * `ServerConnection.close()` drives the SDK's graduated kill (end stdin,
+ * SIGTERM, then SIGKILL) so spawned downstream servers are terminated
+ * rather than orphaned when the router exits.
+ *
+ * @param connections - Live ServerConnection instances keyed by name.
+ * @param logger - Structured logger.
+ */
+async function closeAllConnections(connections, logger) {
+    logger.info('Closing downstream server connections', {
+        servers: [...connections.keys()],
+    });
+    await Promise.all([...connections.values()].map((conn) => conn.close().catch(() => { })));
 }
 /**
  * Runs the router: loads config, refreshes cached auth requirements,
@@ -108,5 +134,15 @@ export async function runRouter(configPath, verbose) {
         compressionLevelByServer.set(server.name, server.compressionLevel);
     }
     const catalog = buildCatalog(discovered, selectionByServer, logger, compressionLevelByServer);
-    await startRouterServer(catalog, connections, selectionByServer, logger);
+    const closeRouter = await startRouterServer(catalog, connections, selectionByServer, logger);
+    const coordinator = new ShutdownCoordinator(logger);
+    coordinator.register(() => closeAllConnections(connections, logger));
+    coordinator.register(closeRouter);
+    installShutdownTriggers(coordinator, logger);
+    // Block here until a shutdown trigger fires (signal or stdin EOF), then
+    // force-exit so lingering grandchild pipes (e.g. browser processes
+    // forked by a downstream server) cannot keep the router alive. Without
+    // this, the router would linger as a ghost process forever.
+    await coordinator.whenShutdown();
+    process.exit(0);
 }

package/build/services/auth-errors.js

@@ -20,3 +20,76 @@ export class GuidedAuthError extends Error {
         this.serverName = serverName;
     }
 }
+/**
+ * HTTP status codes that indicate an authentication or authorization
+ * failure at the transport layer. The MCP SDK's streamable HTTP
+ * transport surfaces the upstream response status as a numeric `code`
+ * property on the thrown error — e.g. 401 when the server rejects a
+ * request without driving the SDK's `redirectToAuthorization` flow.
+ */
+const AUTH_ERROR_STATUSES = new Set([401, 403]);
+/**
+ * Error message substrings that indicate a downstream OAuth /
+ * access-token failure rather than a network, transport, or tool-level
+ * error. These surface when a server rejects a request in the response
+ * body (e.g. with an OAuth error code) instead of returning a clean 401
+ * that would drive the SDK's `redirectToAuthorization` flow (which
+ * throws {@link GuidedAuthError} directly).
+ *
+ * Matching is case-insensitive to tolerate casing differences across
+ * SDK versions and server implementations.
+ */
+const AUTH_ERROR_PATTERNS = [
+    'invalid_token',
+    'invalid_grant',
+    'invalid_client',
+    'missing or invalid access token',
+];
+/**
+ * Reads the HTTP status code attached to an error, if any.
+ *
+ * The MCP SDK's `StreamableHTTPError` exposes the upstream HTTP status
+ * as a numeric `code` property. JSON-RPC error codes (e.g. `-32601`
+ * Method not found) are negative and never collide with HTTP status
+ * codes, so a positive value here is unambiguously an HTTP status.
+ * Duck-typed to avoid importing the SDK error class (mirrors the
+ * `isMethodNotFound` approach in `discovery.ts`).
+ *
+ * @param err - The thrown value from connect, reconnect, or invoke.
+ * @returns The HTTP status code, or `undefined` when none is present.
+ */
+function getHttpStatus(err) {
+    if (typeof err === 'object' && err !== null && 'code' in err) {
+        const code = err.code;
+        return typeof code === 'number' ? code : undefined;
+    }
+    return undefined;
+}
+/**
+ * Determines whether an error represents an authentication failure
+ * (missing, invalid, or expired OAuth credentials) rather than a
+ * network, transport, or tool-level error.
+ *
+ * Returns true for {@link GuidedAuthError} instances, for raw
+ * transport errors carrying an HTTP 401/403 status (read from the
+ * `code` property), and for errors whose message carries an OAuth
+ * error code such as `invalid_token` or `invalid_grant`. Without
+ * this, a server that rejects a request is misclassified as a generic
+ * connection failure, and the guided error tells the user to check
+ * their network instead of running `login`.
+ *
+ * @param err - The error thrown during connect, reconnect, or invoke.
+ * @returns True when the error indicates authentication is required.
+ */
+export function isAuthError(err) {
+    if (err instanceof GuidedAuthError) {
+        return true;
+    }
+    const status = getHttpStatus(err);
+    if (status !== undefined && AUTH_ERROR_STATUSES.has(status)) {
+        return true;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const lower = message.toLowerCase();
+    return AUTH_ERROR_PATTERNS.some((pattern) => lower.includes(pattern));
+}

package/build/services/guided-error.js

@@ -95,8 +95,7 @@ function restartGuidance(isStdio) {
         : 'If the issue persists, restart the MCP server in your coding agent.';
     return (restartClause +
         ' If you have already fixed the issue, restart the MCP server in your ' +
-        'coding agent (e.g. restart Claude Code, opencode, or Codex) so it ' +
-        're-initializes the connection.');
+        'coding agent so it re-initializes the connection.');
 }
 function extractMessage(err) {
     if (err instanceof Error) {

package/build/services/index.js

@@ -2,10 +2,12 @@ export { buildCatalog, lookupTools } from './catalog.js';
 export { resolveConfigDir, resolveConfigPath, loadConfig } from './config.js';
 export { discoverSingleServer } from './discovery.js';
 export { ServerConnection } from './server-connection.js';
+export { ShutdownCoordinator } from './shutdown-coordinator.js';
+export { installShutdownTriggers } from './shutdown-triggers.js';
 export { invokeWithRecovery } from './invoke-with-recovery.js';
 export { saveToolCache } from './tool-cache.js';
 export { OAuthCredentialManager } from './oauth.js';
 export { computeAuthStatus, persistAuthRequirements } from './auth-status.js';
 export { discoverAuth } from './oauth-discovery.js';
-export { GuidedAuthError } from './auth-errors.js';
+export { GuidedAuthError, isAuthError } from './auth-errors.js';
 export { buildGuidedError } from './guided-error.js';

package/build/services/invoke-with-recovery.js

@@ -1,5 +1,5 @@
 import { updateServerInCatalog } from './catalog.js';
-import { buildGuidedError, GuidedAuthError } from './index.js';
+import { buildGuidedError, isAuthError } from './index.js';
 /**
  * Set of error message substrings that indicate a recoverable
  * network/transport failure (as opposed to a tool-level or protocol
@@ -30,7 +30,7 @@ const RECOVERABLE_PATTERNS = [
  * @returns True when a reconnect + retry might succeed.
  */
 export function isRecoverable(err) {
-    if (err instanceof GuidedAuthError) {
+    if (isAuthError(err)) {
         return true;
     }
     const message = err instanceof Error ? err.message : String(err);
@@ -154,7 +154,7 @@ async function invokeToolWithRetry(conn, tool, args, server, serverConfig, selec
                 // server is reachable, so 'unavailable' would be misleading —
                 // surface auth errors as 'authentication required', re-throw
                 // the rest as-is so the caller sees the real downstream error.
-                if (retryErr instanceof GuidedAuthError) {
+                if (isAuthError(retryErr)) {
                     throw buildGuidedError(serverConfig, retryErr, 'unauthorized', true);
                 }
                 throw retryErr;
@@ -162,7 +162,7 @@ async function invokeToolWithRetry(conn, tool, args, server, serverConfig, selec
             // Reconnect itself failed: the server is down or requires auth.
             // doReconnect has already transitioned the connection's status
             // + cooldown so subsequent calls back off.
-            const status = retryErr instanceof GuidedAuthError ? 'unauthorized' : 'unavailable';
+            const status = isAuthError(retryErr) ? 'unauthorized' : 'unavailable';
             throw buildGuidedError(serverConfig, retryErr, status, true);
         }
     }

package/build/services/server-connection.js

@@ -2,7 +2,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { createTransport, listToolsOrEmpty } from './discovery.js';
 import { OAuthCredentialManager } from './oauth.js';
 import { saveToolCache, loadToolCache } from './tool-cache.js';
-import { GuidedAuthError } from './index.js';
+import { isAuthError } from './index.js';
 /**
  * 30-second cooldown after a failed reconnect attempt. Subsequent
  * `invokeWithRecovery` calls within this window return the cached
@@ -122,7 +122,7 @@ export class ServerConnection {
                     cause: err,
                 });
             }
-            const status = err instanceof GuidedAuthError ? 'unauthorized' : 'unavailable';
+            const status = isAuthError(err) ? 'unauthorized' : 'unavailable';
             this._status = status;
             this.logger.warn(`Server "${this.server.name}" failed (${status}) — using ${cachedTools.length} cached tools`, { server: this.server.name, type: this.server.type, error: message, status });
             return {
@@ -202,7 +202,7 @@ export class ServerConnection {
             // backoff. Auth failures are classified as 'unauthorized' so
             // guided errors point at `login` instead of "connection failed".
             this._lastError = err instanceof Error ? err.message : String(err);
-            this._status = err instanceof GuidedAuthError ? 'unauthorized' : 'unavailable';
+            this._status = isAuthError(err) ? 'unauthorized' : 'unavailable';
             throw err;
         }
     }

package/build/services/shutdown-coordinator.js

@@ -0,0 +1,120 @@
+/** Default overall budget for running every registered cleanup hook. */
+const DEFAULT_CLEANUP_TIMEOUT_MS = 5_000;
+/**
+ * Coordinates graceful shutdown of the router. Downstream resources
+ * (server connections, the MCP server) register async cleanup hooks; a
+ * single trigger — a process signal or the disappearance of stdin — runs
+ * every hook once (each racing a shared timeout) and resolves the awaited
+ * {@link ShutdownCoordinator.whenShutdown} promise so the entry point can
+ * force-exit.
+ *
+ * This is the fix for ghost router processes that linger forever: without
+ * it, the spawned downstream servers (and their own child processes, e.g.
+ * browser processes forked by a downstream server) keep the Node event
+ * loop alive even after the host closes the router's stdin pipe, so the
+ * router never exits on its own.
+ */
+export class ShutdownCoordinator {
+    logger;
+    cleanupTimeoutMs;
+    cleanups = [];
+    resolveShutdown;
+    shutdownPromise = new Promise((resolve) => {
+        this.resolveShutdown = resolve;
+    });
+    triggered = false;
+    /**
+     * @param logger - Structured logger for shutdown diagnostics.
+     * @param cleanupTimeoutMs - Overall budget for running every hook
+     *   before the coordinator stops waiting and lets the process exit.
+     *   Defaults to 5 seconds; overridable (mainly for tests).
+     */
+    constructor(logger, cleanupTimeoutMs = DEFAULT_CLEANUP_TIMEOUT_MS) {
+        this.logger = logger;
+        this.cleanupTimeoutMs = cleanupTimeoutMs;
+    }
+    /**
+     * Whether shutdown has already been triggered. A `true` value means
+     * cleanup hooks are running (or have run); newly registered hooks are
+     * ignored from this point on.
+     */
+    get isShuttingDown() {
+        return this.triggered;
+    }
+    /**
+     * Registers a cleanup hook. Hooks added after shutdown has already
+     * started are ignored — the process is already tearing down.
+     *
+     * @param cleanup - Async function run once during shutdown.
+     */
+    register(cleanup) {
+        if (this.triggered) {
+            return;
+        }
+        this.cleanups.push(cleanup);
+    }
+    /**
+     * Triggers shutdown: runs every registered hook (each racing the shared
+     * cleanup timeout), never rejecting. Safe to call repeatedly — only the
+     * first call runs the hooks; later calls return the same promise.
+     *
+     * @param reason - Why shutdown was triggered (e.g. `signal:SIGTERM`,
+     *   `stdin-closed`).
+     * @returns Resolves when all hooks finish or time out.
+     */
+    shutdown(reason) {
+        if (this.triggered) {
+            return this.shutdownPromise;
+        }
+        this.triggered = true;
+        this.logger.info('Shutdown triggered', { reason });
+        void this.runCleanups(reason).finally(() => this.resolveShutdown());
+        return this.shutdownPromise;
+    }
+    /**
+     * Resolves once shutdown has completed. The router's main loop awaits
+     * this so the process stays alive while serving and exits the moment
+     * cleanup finishes. Does NOT trigger shutdown on its own.
+     */
+    whenShutdown() {
+        return this.shutdownPromise;
+    }
+    /**
+     * Runs every hook in parallel. A slow or throwing hook never blocks the
+     * others or the final exit: each is raced against the shared deadline,
+     * and rejections are logged and swallowed.
+     */
+    async runCleanups(reason) {
+        const deadline = this.createDeadline();
+        await Promise.all(this.cleanups.map((cleanup, index) => this.runOne(cleanup, index, reason, deadline)));
+        this.logger.info('Shutdown complete', { reason });
+    }
+    /**
+     * Runs a single hook against the shared deadline. Defers invocation so
+     * a synchronous throw becomes a rejection we can race and swallow
+     * rather than an uncaught exception.
+     */
+    async runOne(cleanup, index, reason, deadline) {
+        const pending = Promise.resolve().then(() => cleanup());
+        // Swallow late rejections so a hook that fails after the deadline
+        // already resolved never surfaces an unhandled-rejection warning.
+        void pending.catch(() => { });
+        try {
+            await Promise.race([pending, deadline]);
+        }
+        catch (err) {
+            this.logger.warn('Cleanup hook failed during shutdown', {
+                reason,
+                hook: index,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /** Creates an unref'd timer that resolves after the cleanup budget. */
+    createDeadline() {
+        return new Promise((resolve) => {
+            const handle = setTimeout(resolve, this.cleanupTimeoutMs);
+            handle.unref?.();
+        });
+    }
+}

package/build/services/shutdown-triggers.js

@@ -0,0 +1,57 @@
+import process from 'node:process';
+/**
+ * Signals whose arrival should trigger a graceful shutdown. `SIGHUP` is
+ * included because some hosts send it when the controlling terminal
+ * disappears.
+ */
+const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+/**
+ * Installs process-global triggers that call
+ * {@link ShutdownCoordinator.shutdown} when the router should stop:
+ *
+ * - `SIGINT` / `SIGTERM` / `SIGHUP` — the host asked us to terminate.
+ * - stdin `'end'` / `'close'` — the host closed our input pipe without
+ *   sending a signal. This is the most common cause of ghost router
+ *   processes that never exit: the MCP SDK's stdio server transport only
+ *   listens for `'data'` / `'error'` on stdin, so without this hook the
+ *   router lingers forever while spawned downstream servers keep the
+ *   event loop alive.
+ *
+ * A second shutdown signal force-exits immediately so that a stuck
+ * cleanup never traps the user with an unresponsive process.
+ *
+ * @param coordinator - The coordinator to trigger on signal or stdin EOF.
+ * @param logger - Structured logger for trigger diagnostics.
+ */
+export function installShutdownTriggers(coordinator, logger) {
+    for (const signal of SHUTDOWN_SIGNALS) {
+        process.on(signal, () => {
+            if (coordinator.isShuttingDown) {
+                logger.warn('Forcing immediate exit on signal during shutdown', { signal });
+                process.exit(1);
+            }
+            void coordinator.shutdown(`signal:${signal}`);
+        });
+    }
+    watchStdinClose(coordinator);
+}
+/**
+ * Treats stdin EOF as a shutdown trigger. The host (IDE/editor/agent)
+ * typically ends the router by closing its stdin pipe without sending a
+ * signal; without this watcher the router would linger as a ghost
+ * process because the SDK ignores stdin EOF.
+ *
+ * Listeners are removed after the first trigger so a later `'close'`
+ * event (e.g. from the SDK tearing the transport down during cleanup)
+ * cannot re-enter the coordinator.
+ */
+function watchStdinClose(coordinator) {
+    const stdin = process.stdin;
+    const trigger = () => {
+        stdin.off('end', trigger);
+        stdin.off('close', trigger);
+        void coordinator.shutdown('stdin-closed');
+    };
+    stdin.on('end', trigger);
+    stdin.on('close', trigger);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-compress-router",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Compress all connected MCP servers into a single router MCP to save tokens",
   "license": "MIT",
   "type": "module",