mcp-compress-router 1.5.0 → 1.5.1

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/index.js

@@ -2,6 +2,8 @@ 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';

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.1",
   "description": "Compress all connected MCP servers into a single router MCP to save tokens",
   "license": "MIT",
   "type": "module",