mcp-compress-router 1.6.0 → 1.6.2

package/build/cli/config-io.js

@@ -130,52 +130,101 @@ export async function readCredentials(configPath) {
  */
 export async function writeCredentials(configPath, name, credentials, logger) {
     const credPath = getCredentialsPath(configPath);
-    // Read existing store (or start fresh)
-    let store = {};
+    const store = (await readCredentialsStore(credPath, 'writing')) ?? {};
+    store[name] = credentials;
+    const { isNewFile, mode } = await resolveCredentialsMode(credPath);
+    // Write atomically (unique temporary sibling + rename): a crash or
+    // forced exit can never leave credentials.json truncated, and
+    // readCredentials treats invalid JSON as a hard startup error.
+    await writeCredentialsFileAtomic(credPath, JSON.stringify(store, null, 2) + '\n', mode);
+    // On first creation, set restrictive permissions (owner read/write only)
+    if (isNewFile) {
+        await restrictNewCredentialsFile(credPath, logger);
+    }
+}
+/**
+ * Reads the credentials store for a read-modify-write update. A missing
+ * file yields `undefined`; any other failure (unreadable file or invalid
+ * JSON) is fatal so a damaged store is never silently overwritten.
+ *
+ * @param credPath - Absolute path to credentials.json.
+ * @param action - Action named in the error message.
+ * @returns The stored credentials, or undefined when no file exists.
+ */
+async function readCredentialsStore(credPath, action) {
     try {
         const raw = await fs.readFile(credPath, 'utf-8');
         const parsed = JSON.parse(raw);
         if (typeof parsed === 'object' && parsed !== null) {
-            store = parsed;
+            return parsed;
         }
+        return {};
     }
     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 });
+            return undefined;
         }
+        throw new Error(`Failed to read credentials file for ${action}: ${credPath}`, { cause: err });
     }
-    // Merge in the new/updated entry
-    store[name] = credentials;
-    // Determine if this is a first-time creation
-    let isNewFile = false;
+}
+/**
+ * Resolves the permissions to use when replacing the credentials file:
+ * an existing file keeps its mode, a new file is created owner-only.
+ *
+ * @param credPath - Absolute path to credentials.json.
+ * @returns Whether the file is new, and the mode to apply.
+ */
+async function resolveCredentialsMode(credPath) {
     try {
-        await fs.access(credPath);
+        const stat = await fs.stat(credPath);
+        return { isNewFile: false, mode: stat.mode & 0o777 };
     }
     catch {
-        isNewFile = true;
+        return { isNewFile: true, mode: 0o600 };
     }
-    // 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}`);
+}
+/**
+ * Writes `data` atomically: the content goes to a unique temporary
+ * sibling file first, then is renamed over the target, so a crash or a
+ * forced exit can never leave a truncated credentials file behind.
+ *
+ * @param credPath - Target credentials file path.
+ * @param data - Full file content to write.
+ * @param mode - Permissions to create the replacement file with.
+ */
+async function writeCredentialsFileAtomic(credPath, data, mode) {
+    const tempPath = `${credPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await fs.writeFile(tempPath, data, { mode });
+        await fs.rename(tempPath, credPath);
+    }
+    catch (err) {
+        await fs.unlink(tempPath).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Restricts a freshly created credentials file to owner read/write and
+ * warns when the platform cannot enforce it.
+ *
+ * @param credPath - Absolute path to credentials.json.
+ * @param logger - Optional logger for permission warnings.
+ */
+async function restrictNewCredentialsFile(credPath, logger) {
+    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.
@@ -187,20 +236,10 @@ export async function writeCredentials(configPath, name, credentials, logger) {
  */
 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 });
+    const store = await readCredentialsStore(credPath, 'removal');
+    if (store === undefined) {
+        // File does not exist — nothing to remove
+        return;
     }
     delete store[name];
     if (Object.keys(store).length === 0) {
@@ -208,6 +247,7 @@ export async function removeCredentials(configPath, name) {
         await fs.unlink(credPath);
     }
     else {
-        await fs.writeFile(credPath, JSON.stringify(store, null, 2) + '\n');
+        const { mode } = await resolveCredentialsMode(credPath);
+        await writeCredentialsFileAtomic(credPath, JSON.stringify(store, null, 2) + '\n', mode);
     }
 }

package/build/cli/router-runner.js

@@ -1,21 +1,27 @@
 import process from 'node:process';
-import { resolveConfigPath, persistAuthRequirements, loadConfig, ServerConnection, invokeWithRecovery, buildCatalog, ShutdownCoordinator, installShutdownTriggers, } from '../services/index.js';
+import { resolveConfigPath, persistAuthRequirements, loadConfig, ServerConnection, invokeWithRecovery, buildCatalog, replaceCatalogContents, 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';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { startRouterServer } from './router-server.js';
 /**
  * Connects to all enabled downstream servers via ServerConnection.
  * Disabled servers are skipped entirely. On failure, warm-cache
  * servers are degraded; cold-cache servers cause fail-fast.
  *
+ * Each connection is registered in the shared `connections` map BEFORE
+ * its connect starts, so a shutdown triggered mid-connect still tears
+ * the in-flight child process down instead of orphaning it.
+ *
  * @param servers - Validated downstream server configs.
  * @param configPath - Absolute path to the config file.
  * @param logger - Structured logger.
- * @returns Map of server name to ServerConnection and discovered data.
+ * @param connections - Shared connection registry (populated as connects
+ *   start; used for shutdown cleanup and runtime invocation).
+ * @param coordinator - Shutdown coordinator (stops launching new
+ *   connects once shutdown has started).
+ * @returns Discovered data for every connected server, in config order.
  * @throws When a server cannot connect AND has no tool cache.
  */
-async function connectAllServers(servers, configPath, logger) {
+async function connectAllServers(servers, configPath, logger, connections, coordinator) {
     const enabledServers = servers.filter((server) => {
         if (server.enabled === false) {
             logger.info(`Skipping disabled server "${server.name}"`, { server: server.name });
@@ -24,60 +30,24 @@ async function connectAllServers(servers, configPath, logger) {
         return true;
     });
     const results = await Promise.all(enabledServers.map(async (server) => {
+        if (coordinator.isShuttingDown) {
+            return undefined;
+        }
         const conn = new ServerConnection(server, configPath, logger);
+        connections.set(conn.serverName, conn);
+        if (coordinator.isShuttingDown) {
+            return undefined;
+        }
         const ds = await conn.connect();
         return { conn, ds };
     }));
-    const connections = new Map();
     const discovered = [];
-    for (const { conn, ds } of results) {
-        connections.set(conn.serverName, conn);
-        discovered.push(ds);
-    }
-    return { connections, discovered };
-}
-/**
- * Creates the MCP server, registers router tools, and starts the
- * stdio transport.
- *
- * @param catalog - The mutable tool catalog.
- * @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({
-        name: 'mcp-compress-router',
-        version: '1.0.0',
-    });
-    router.registerTool('get_tool_schema', {
-        title: 'Get Tool Schema',
-        description: buildGetToolSchemaDescription(catalog),
-        inputSchema: GetToolSchemaInputSchema,
-    }, createGetToolSchemaHandler(catalog, logger));
-    const invokeFn = async (server, tool, args) => {
-        return invokeWithRecovery(server, tool, args, catalog, connections, selectionByServer, logger);
-    };
-    router.registerTool('invoke_tool', {
-        title: 'Invoke Tool',
-        description: 'Invoke a specific tool on a connected MCP server. ' +
-            'You MUST first use get_tool_schema to retrieve the required parameters ' +
-            'for this tool before calling invoke_tool.',
-        inputSchema: InvokeToolInputSchema,
-    }, createInvokeToolHandler(catalog, invokeFn, 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.
+    for (const result of results) {
+        if (result) {
+            discovered.push(result.ds);
         }
-    };
+    }
+    return discovered;
 }
 /**
  * Closes every downstream server connection in parallel. Each
@@ -95,15 +65,10 @@ async function closeAllConnections(connections, logger) {
     await Promise.all([...connections.values()].map((conn) => conn.close().catch(() => { })));
 }
 /**
- * Runs the router: loads config, refreshes cached auth requirements,
- * connects to downstream servers, builds the catalog, and starts the
- * stdio MCP server.
- *
- * @param configPath - Explicit config path, or undefined for default.
- * @param verbose - When true, enables debug-level logging.
+ * Loads the config file and derives the per-server tool-selection and
+ * compression-level maps used for filtering/rendering.
  */
-export async function runRouter(configPath, verbose) {
-    const logger = new Logger(verbose ? 'debug' : 'info');
+async function loadConfigForRun(configPath, verbose, logger) {
     logger.info('Starting mcp-compress-router', {
         verbose,
         config: configPath ?? '(default)',
@@ -112,36 +77,6 @@ export async function runRouter(configPath, verbose) {
     logger.info('Loading configuration', { path: resolved });
     const servers = await loadConfig(resolved);
     logger.info('Configuration loaded', { serverCount: servers.length });
-    // Refresh the cached OAuth auth requirements CONCURRENTLY with the
-    // downstream connects. Both phases are network-bound, so running them
-    // sequentially would stack their worst-case latencies; in parallel the
-    // startup time is bounded by the slower of the two — and each default
-    // timeout (see timeout.ts) stays well below the 30 s startup budget
-    // most MCP hosts allow, so even a hung server cannot blow it.
-    // `Promise.allSettled` avoids unhandled rejections when both phases
-    // fail; the connect failure is surfaced first because it is the one
-    // the host needs to act on.
-    logger.info('Connecting to downstream servers', {
-        servers: servers.map((s) => s.name),
-    });
-    const [authRefresh, connectResult] = await Promise.allSettled([
-        persistAuthRequirements(resolved, servers, logger),
-        connectAllServers(servers, resolved, logger),
-    ]);
-    if (connectResult.status === 'rejected') {
-        throw connectResult.reason;
-    }
-    if (authRefresh.status === 'rejected') {
-        throw authRefresh.reason;
-    }
-    const { connections, discovered } = connectResult.value;
-    logger.info('Tools discovered', {
-        servers: discovered.map((d) => ({
-            name: d.name,
-            toolCount: d.tools.length,
-            status: d.status,
-        })),
-    });
     const selectionByServer = new Map();
     const compressionLevelByServer = new Map();
     for (const server of servers) {
@@ -151,12 +86,120 @@ export async function runRouter(configPath, verbose) {
         });
         compressionLevelByServer.set(server.name, server.compressionLevel);
     }
-    const catalog = buildCatalog(discovered, selectionByServer, logger, compressionLevelByServer);
-    const closeRouter = await startRouterServer(catalog, connections, selectionByServer, logger);
+    return { resolved, servers, selectionByServer, compressionLevelByServer };
+}
+/**
+ * Installs the shutdown coordinator + triggers and the shared connection
+ * registry. MUST run before any downstream child is spawned so a host
+ * disconnect during the connect phase tears in-flight children down.
+ */
+function installShutdownManager(logger) {
+    const connections = new Map();
     const coordinator = new ShutdownCoordinator(logger);
     coordinator.register(() => closeAllConnections(connections, logger));
-    coordinator.register(closeRouter);
     installShutdownTriggers(coordinator, logger);
+    return { coordinator, connections };
+}
+/**
+ * Creates the empty live catalog, its ready signal, and the downstream
+ * invocation function. Tool handlers hold the catalog by reference; the
+ * final contents are published in place once discovery completes.
+ */
+function createCatalogState(connections, selectionByServer, logger) {
+    const catalog = {
+        servers: [],
+        toolMap: new Map(),
+        filteredToolNames: new Set(),
+    };
+    let markCatalogReady;
+    const catalogReady = new Promise((resolve) => {
+        markCatalogReady = resolve;
+    });
+    const invokeFn = async (server, tool, args) => {
+        return invokeWithRecovery(server, tool, args, catalog, connections, selectionByServer, logger);
+    };
+    return { catalog, catalogReady, markCatalogReady, invokeFn };
+}
+/**
+ * Kicks off the downstream connect phase (including the OAuth
+ * auth-requirement refresh) without awaiting it. Both phases run in
+ * parallel, each bounded by per-operation timeouts.
+ */
+function launchConnectPhase(servers, resolved, connections, coordinator, logger) {
+    return (async () => {
+        const [authRefresh, connectResult] = await Promise.allSettled([
+            persistAuthRequirements(resolved, servers, logger),
+            connectAllServers(servers, resolved, logger, connections, coordinator),
+        ]);
+        if (connectResult.status === 'rejected') {
+            throw connectResult.reason;
+        }
+        if (authRefresh.status === 'rejected') {
+            throw authRefresh.reason;
+        }
+        return connectResult.value;
+    })();
+}
+/**
+ * Awaits the connect phase, racing it against shutdown. On shutdown the
+ * connect phase is abandoned (its in-flight children were already closed
+ * by the cleanup hooks). On a cold connect failure, cleanup runs first,
+ * then the error is rethrown so the entry point logs + exits non-zero.
+ */
+async function awaitConnectOutcome(connectPhase, coordinator) {
+    try {
+        return await Promise.race([
+            connectPhase.then((discovered) => ({ discovered })),
+            coordinator.whenShutdownStarted().then(() => ({ shutdown: true })),
+        ]);
+    }
+    catch (err) {
+        await coordinator.shutdown('startup-failure');
+        throw err;
+    }
+}
+/**
+ * Publishes the discovered servers into the live catalog, unblocks
+ * tools/list, and logs the discovery summary.
+ */
+function publishCatalog(catalog, markCatalogReady, discovered, selectionByServer, compressionLevelByServer, logger) {
+    replaceCatalogContents(catalog, buildCatalog(discovered, selectionByServer, logger, compressionLevelByServer));
+    markCatalogReady();
+    logger.info('Tools discovered', {
+        servers: discovered.map((d) => ({
+            name: d.name,
+            toolCount: d.tools.length,
+            status: d.status,
+        })),
+    });
+}
+/**
+ * Runs the router: starts the host-facing stdio server IMMEDIATELY (so
+ * the host's `initialize` is answered without waiting for downstream
+ * connects), then connects to downstream servers concurrently, publishes
+ * the discovered tools into the live catalog, and blocks until a
+ * shutdown trigger fires.
+ *
+ * Shutdown triggers are installed before ANY network activity so a host
+ * disconnect during the connect phase still tears down in-flight
+ * downstream children (the most common cause of orphaned processes).
+ *
+ * @param configPath - Explicit config path, or undefined for default.
+ * @param verbose - When true, enables debug-level logging.
+ */
+export async function runRouter(configPath, verbose) {
+    const logger = new Logger(verbose ? 'debug' : 'info');
+    const { resolved, servers, selectionByServer, compressionLevelByServer } = await loadConfigForRun(configPath, verbose, logger);
+    const { coordinator, connections } = installShutdownManager(logger);
+    const { catalog, catalogReady, markCatalogReady, invokeFn } = createCatalogState(connections, selectionByServer, logger);
+    const closeRouter = await startRouterServer(catalog, invokeFn, logger, coordinator, catalogReady);
+    coordinator.register(closeRouter);
+    const outcome = await awaitConnectOutcome(launchConnectPhase(servers, resolved, connections, coordinator, logger), coordinator);
+    if ('shutdown' in outcome) {
+        await coordinator.whenShutdown();
+        process.exit(0);
+    }
+    publishCatalog(catalog, markCatalogReady, outcome.discovered, selectionByServer, compressionLevelByServer, 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

package/build/cli/router-server.js

@@ -0,0 +1,117 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { createGetToolSchemaHandler, buildGetToolSchemaDescription } from '../tools/index.js';
+import { createInvokeToolHandler, GetToolSchemaInputSchema, InvokeToolInputSchema, } from '../tools/index.js';
+/** Zod object for get_tool_schema arguments (validation + JSON schema). */
+const getToolSchemaArgs = z.object(GetToolSchemaInputSchema);
+/** Zod object for invoke_tool arguments (validation + JSON schema). */
+const invokeToolArgs = z.object(InvokeToolInputSchema);
+/** Whether a tools/list request is unblocked (catalog ready or shutdown). */
+async function waitForCatalog(catalogReady, coordinator) {
+    await Promise.race([
+        catalogReady,
+        coordinator.whenShutdownStarted().then(() => {
+            throw new McpError(ErrorCode.ConnectionClosed, 'Router is shutting down');
+        }),
+    ]);
+}
+/**
+ * Builds the router's two tool entries from the live catalog. Called per
+ * `tools/list` request so the compact catalog (and the per-server status)
+ * always reflects the latest discovery/reconnect state.
+ *
+ * @param catalog - The tool catalog (read live).
+ * @returns Tool entries for the MCP tools/list response.
+ */
+function buildRouterToolList(catalog) {
+    return [
+        {
+            name: 'get_tool_schema',
+            title: 'Get Tool Schema',
+            description: buildGetToolSchemaDescription(catalog),
+            inputSchema: z.toJSONSchema(getToolSchemaArgs),
+        },
+        {
+            name: 'invoke_tool',
+            title: 'Invoke Tool',
+            description: 'Invoke a specific tool on a connected MCP server. ' +
+                'You MUST first use get_tool_schema to retrieve the required parameters ' +
+                'for this tool before calling invoke_tool.',
+            inputSchema: z.toJSONSchema(invokeToolArgs),
+        },
+    ];
+}
+/**
+ * Validates tool arguments against the tool's Zod schema, mirroring the
+ * SDK's McpServer behavior of rejecting malformed input with
+ * `InvalidParams` (rather than passing garbage into the handlers).
+ *
+ * @param schema - The Zod object for the tool's arguments.
+ * @param toolName - The tool name (for the error message).
+ * @param args - The raw arguments from the tools/call request.
+ * @returns The validated + trimmed arguments.
+ * @throws McpError(InvalidParams) when the arguments do not match.
+ */
+function parseToolArguments(schema, toolName, args) {
+    const parsed = schema.safeParse(args);
+    if (!parsed.success) {
+        const detail = parsed.error.issues.map((issue) => issue.message).join('; ');
+        throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for tool "${toolName}": ${detail}`);
+    }
+    return parsed.data;
+}
+/**
+ * Creates the router's MCP server (low-level SDK Server) and starts the
+ * stdio transport IMMEDIATELY, before downstream servers have connected.
+ * The host's `initialize` is answered right away; `tools/list` waits for
+ * the catalog to be filled (bounded by the per-server connect timeouts,
+ * aborted on shutdown) so the compact catalog always reflects the final
+ * discovery state.
+ *
+ * Tool handlers receive only the catalog (plus the injected invocation
+ * function) — never raw transport clients.
+ *
+ * @param catalog - The mutable tool catalog (empty at start).
+ * @param invokeFn - Function forwarding tool calls to downstreams.
+ * @param logger - Structured logger.
+ * @param coordinator - Shutdown coordinator (aborts pending requests).
+ * @param catalogReady - Resolves once the catalog has been populated.
+ * @returns A cleanup function closing the router's MCP server.
+ */
+export async function startRouterServer(catalog, invokeFn, logger, coordinator, catalogReady) {
+    const server = new Server({ name: 'mcp-compress-router', version: '1.0.0' }, { capabilities: { tools: {} } });
+    const getToolSchemaHandler = createGetToolSchemaHandler(catalog, logger);
+    const invokeToolHandler = createInvokeToolHandler(catalog, invokeFn, logger);
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        await waitForCatalog(catalogReady, coordinator);
+        return { tools: buildRouterToolList(catalog) };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        // Like tools/list, a direct tool call must wait for discovery to
+        // publish the catalog (bounded by the per-server connect timeouts,
+        // aborted on shutdown) so handlers never see an empty catalog.
+        await waitForCatalog(catalogReady, coordinator);
+        const { name, arguments: rawArgs } = request.params;
+        switch (name) {
+            case 'get_tool_schema':
+                return getToolSchemaHandler(parseToolArguments(getToolSchemaArgs, name, rawArgs ?? {}));
+            case 'invoke_tool':
+                return invokeToolHandler(parseToolArguments(invokeToolArgs, name, rawArgs ?? {}));
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('Server started on stdio');
+    return async () => {
+        try {
+            await server.close();
+        }
+        catch {
+            // Ignore close errors during shutdown — the process is exiting.
+        }
+    };
+}

package/build/services/catalog.js

@@ -89,6 +89,30 @@ export function updateServerInCatalog(catalog, serverName, tools, status, toolSe
     server.tools = exposed;
     server.status = status;
 }
+/**
+ * Replaces the contents of a live catalog with a freshly-built one
+ * (mutates the same object in place).
+ *
+ * Used by the entry point to publish discovered servers into the catalog
+ * that tool handlers hold by reference: the router starts serving the
+ * host immediately with an empty catalog, then swaps the final contents
+ * in once discovery completes — without re-registering tool handlers.
+ *
+ * @param catalog - The catalog to fill (kept by reference by handlers).
+ * @param built - The catalog whose contents replace `catalog`'s.
+ */
+export function replaceCatalogContents(catalog, built) {
+    catalog.servers.length = 0;
+    catalog.servers.push(...built.servers);
+    catalog.toolMap.clear();
+    for (const [key, value] of built.toolMap) {
+        catalog.toolMap.set(key, value);
+    }
+    catalog.filteredToolNames.clear();
+    for (const key of built.filteredToolNames) {
+        catalog.filteredToolNames.add(key);
+    }
+}
 /**
  * Looks up tool schemas in the catalog by server and tool names.
  *

package/build/services/dedicated-fetch.js

@@ -47,3 +47,131 @@ export function createDedicatedFetch() {
         dispatcher: agent,
     });
 }
+/**
+ * Wraps a {@link FetchLike} so the awaits in the HTTP transport connect
+ * path are bounded: the SSE session GET, the OAuth metadata discovery
+ * GETs, and the OAuth token exchange POST (a TCP-accepting-but-silent
+ * server, or a hung token endpoint, would otherwise stall
+ * `client.connect()` forever).
+ *
+ * The timeout covers the response-header phase for every bounded request
+ * and additionally the response-body read for requests whose body is
+ * consumed during connect (metadata + token exchange). The long-lived SSE
+ * response body is deliberately exempt: its `Accept: text/event-stream`
+ * header marks it, so it streams for its natural duration. An abort
+ * raises a descriptive timeout error instead of undici's bare
+ * `AbortError`.
+ *
+ * Requests that can legitimately run long are NOT bounded:
+ * - JSON message POSTs (`tools/call` and friends) — the response headers
+ *   only arrive once the downstream finishes processing the request.
+ * - Any other method (e.g. the session DELETE on close).
+ *
+ * @param baseFetch - The underlying fetch (e.g. a dedicated undici fetch).
+ * @param timeoutMs - Connect timeout in milliseconds.
+ * @returns A fetch-compatible function with the connect timeout applied.
+ */
+export function createConnectTimeoutFetch(baseFetch, timeoutMs) {
+    return (url, init) => {
+        const bound = classifyConnectBound(init);
+        if (bound === undefined) {
+            return baseFetch(url, init);
+        }
+        const controller = new AbortController();
+        const timedOut = { current: false };
+        const timer = setTimeout(() => {
+            timedOut.current = true;
+            controller.abort();
+        }, timeoutMs);
+        timer.unref?.();
+        const signal = init !== undefined && init.signal
+            ? AbortSignal.any([init.signal, controller.signal])
+            : controller.signal;
+        return baseFetch(url, { ...init, signal })
+            .then((response) => {
+            if (bound === 'headers') {
+                clearTimeout(timer);
+                return response;
+            }
+            return boundResponseBody(response, timer, timedOut, timeoutMs);
+        })
+            .catch((err) => {
+            clearTimeout(timer);
+            if (timedOut.current) {
+                throw timeoutError('response headers', timeoutMs);
+            }
+            throw err;
+        });
+    };
+}
+/**
+ * Decides whether a request is part of the connect/auth handshake that
+ * must be bounded, and how far the timeout reaches. GETs bound their body
+ * too (metadata discovery) unless they request an SSE stream — the SSE
+ * session GET streams forever and must only be bounded at the header
+ * phase. Form-encoded POSTs bound their body (OAuth token exchange).
+ * JSON message POSTs are deliberately excluded — their headers arrive
+ * only when the downstream finishes the request, which may take minutes
+ * for a long tool call.
+ *
+ * @param init - Request init, if any.
+ * @returns The bound scope, or undefined when the request is unbounded.
+ */
+function classifyConnectBound(init) {
+    const method = (init?.method ?? 'GET').toUpperCase();
+    if (method === 'GET') {
+        return acceptsEventStream(init) ? 'headers' : 'body';
+    }
+    if (method === 'POST') {
+        const contentType = new Headers(init?.headers).get('content-type') ?? '';
+        return contentType.includes('application/x-www-form-urlencoded') ? 'body' : undefined;
+    }
+    return undefined;
+}
+/**
+ * Whether the request asks for an SSE stream (`Accept: text/event-stream`),
+ * which is exempt from the body-phase timeout.
+ */
+function acceptsEventStream(init) {
+    const accept = new Headers(init?.headers).get('accept') ?? '';
+    return accept.includes('text/event-stream');
+}
+/**
+ * Keeps the connect timer armed after headers arrive and wraps the
+ * response body readers so a timeout mid-read surfaces as a descriptive
+ * error (and the timer is cleared once a read settles).
+ */
+function boundResponseBody(response, timer, timedOut, timeoutMs) {
+    response.json = withBodyTimeout(response.json.bind(response), timer, timedOut, timeoutMs);
+    response.text = withBodyTimeout(response.text.bind(response), timer, timedOut, timeoutMs);
+    response.arrayBuffer = withBodyTimeout(response.arrayBuffer.bind(response), timer, timedOut, timeoutMs);
+    response.blob = withBodyTimeout(response.blob.bind(response), timer, timedOut, timeoutMs);
+    return response;
+}
+/**
+ * Wraps a body reader so it clears the connect timer when it settles and
+ * converts an abort caused by that timer into a descriptive error.
+ */
+function withBodyTimeout(read, timer, timedOut, timeoutMs) {
+    return async () => {
+        try {
+            return await read();
+        }
+        catch (err) {
+            if (timedOut.current) {
+                throw timeoutError('the response body', timeoutMs);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+/**
+ * Builds the error raised when the connect timeout fires while waiting for
+ * the given handshake phase.
+ */
+function timeoutError(phase, timeoutMs) {
+    return new Error(`Timed out after ${timeoutMs}ms waiting for ${phase} from the downstream server.`);
+}

package/build/services/discovery.js

@@ -2,9 +2,47 @@ 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';
-import { createDedicatedFetch } from './dedicated-fetch.js';
+import { createDedicatedFetch, createConnectTimeoutFetch } from './dedicated-fetch.js';
 /** JSON-RPC error code for "Method not found". */
 const METHOD_NOT_FOUND = -32601;
+/**
+ * A {@link StdioClientTransport} whose `start()` (the child-process spawn
+ * wait inside `client.connect()`) is bounded by a timeout. The SDK's own
+ * transport resolves `start()` only on the process `'spawn'` event, so a
+ * spawn that never completes — e.g. an executable on a stalled filesystem —
+ * would stall the connect phase forever with no timeout of any kind.
+ *
+ * On timeout the child is force-closed (graduated kill) and the attempt
+ * is rejected, so the router degrades or fails fast instead of hanging.
+ */
+class TimeoutStdioClientTransport extends StdioClientTransport {
+    spawnTimeoutMs;
+    constructor(params, spawnTimeoutMs) {
+        super(params);
+        this.spawnTimeoutMs = spawnTimeoutMs;
+    }
+    async start() {
+        let timer;
+        const spawnTimeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error(`Timed out after ${this.spawnTimeoutMs}ms waiting for the stdio server process to start.`));
+            }, this.spawnTimeoutMs);
+            timer.unref?.();
+        });
+        try {
+            await Promise.race([super.start(), spawnTimeout]);
+        }
+        catch (err) {
+            await this.close().catch(() => { });
+            throw err;
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+}
 /**
  * Returns true when an error is a JSON-RPC "Method not found" response,
  * which a downstream server returns for `tools/list` when it advertises
@@ -114,11 +152,11 @@ export function createTransport(server, getAuthProvider) {
         if (!server.command) {
             throw new Error(`Server "${server.name}" (stdio) is missing command`);
         }
-        return new StdioClientTransport({
+        return new TimeoutStdioClientTransport({
             command: server.command,
             args: server.args,
             env: server.env,
-        });
+        }, getDownstreamTimeoutMs());
     }
     // http or streamable-http
     if (!server.url) {
@@ -133,7 +171,10 @@ export function createTransport(server, getAuthProvider) {
         requestInit: Object.keys(requestInit).length > 0 ? requestInit : undefined,
         authProvider,
         // Route all of this server's traffic through its own undici agent so
-        // it uses a private connection pool instead of the shared default one.
-        fetch: createDedicatedFetch(),
+        // it uses a private connection pool instead of the shared default one,
+        // and bound the connect/auth handshakes (SSE session GET, OAuth
+        // metadata + token flows) so a silent server cannot stall startup —
+        // runtime message POSTs are deliberately left unbounded.
+        fetch: createConnectTimeoutFetch(createDedicatedFetch(), getDownstreamTimeoutMs()),
     });
 }

package/build/services/index.js

@@ -1,4 +1,4 @@
-export { buildCatalog, lookupTools } from './catalog.js';
+export { buildCatalog, lookupTools, replaceCatalogContents } from './catalog.js';
 export { resolveConfigDir, resolveConfigPath, loadConfig } from './config.js';
 export { discoverSingleServer } from './discovery.js';
 export { ServerConnection } from './server-connection.js';

package/build/services/shutdown-coordinator.js

@@ -22,6 +22,10 @@ export class ShutdownCoordinator {
     shutdownPromise = new Promise((resolve) => {
         this.resolveShutdown = resolve;
     });
+    resolveShutdownStarted;
+    shutdownStartedPromise = new Promise((resolve) => {
+        this.resolveShutdownStarted = resolve;
+    });
     triggered = false;
     /**
      * @param logger - Structured logger for shutdown diagnostics.
@@ -53,6 +57,15 @@ export class ShutdownCoordinator {
         }
         this.cleanups.push(cleanup);
     }
+    /**
+     * Resolves as soon as shutdown is triggered, BEFORE cleanup hooks run.
+     * Lets long-running phases (downstream connects, pending MCP requests)
+     * abort promptly the moment the host disconnects, instead of waiting
+     * for the full cleanup window.
+     */
+    whenShutdownStarted() {
+        return this.shutdownStartedPromise;
+    }
     /**
      * Triggers shutdown: runs every registered hook (each racing the shared
      * cleanup timeout), never rejecting. Safe to call repeatedly — only the
@@ -67,6 +80,7 @@ export class ShutdownCoordinator {
             return this.shutdownPromise;
         }
         this.triggered = true;
+        this.resolveShutdownStarted();
         this.logger.info('Shutdown triggered', { reason });
         void this.runCleanups(reason).finally(() => this.resolveShutdown());
         return this.shutdownPromise;

package/build/services/tool-cache.js

@@ -47,13 +47,39 @@ function serializeCacheWrite(cachePath, task) {
 function isNodeError(err) {
     return err instanceof Error && typeof err.code === 'string';
 }
+/**
+ * Sanitizes a parsed cache store: keeps only entries that are plain
+ * objects carrying a `tools` array, and drops everything else. A cache
+ * file that is damaged in parts therefore degrades to the subset of
+ * still-valid entries instead of being rejected wholesale; a root that
+ * is not a plain object degrades to an empty store.
+ *
+ * @param parsed - The raw JSON.parse() result of the cache file.
+ * @returns A validated store containing only well-formed entries.
+ */
+function sanitizeStore(parsed) {
+    const store = {};
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return store;
+    }
+    for (const [serverName, entry] of Object.entries(parsed)) {
+        const candidate = entry;
+        if (candidate !== null && typeof candidate === 'object' && Array.isArray(candidate.tools)) {
+            store[serverName] = candidate;
+        }
+    }
+    return store;
+}
 /**
  * Reads the full tool cache store from disk. Returns an empty object
- * when the file does not exist.
+ * when the file does not exist. A corrupted cache file (invalid JSON,
+ * a non-object root, or entries without a `tools` array) never throws:
+ * it is treated as empty or partially empty so a damaged cache can
+ * never break the router. The next write simply rebuilds the file.
  *
  * @param configPath - Absolute path to the mcp.json file.
- * @returns The tool cache store, or empty object if file is absent.
- * @throws If the file exists but contains invalid JSON.
+ * @returns The tool cache store (possibly empty or partial).
+ * @throws Only on unexpected I/O errors (e.g. permission denied).
  */
 async function readCacheStore(configPath) {
     const cachePath = getCachePath(configPath);
@@ -67,17 +93,36 @@ async function readCacheStore(configPath) {
         }
         throw new Error(`Failed to read tool cache file: ${cachePath}`, { cause: err });
     }
-    let parsed;
     try {
-        parsed = JSON.parse(raw);
+        return sanitizeStore(JSON.parse(raw));
     }
-    catch (err) {
-        throw new Error(`Tool cache file contains invalid JSON: ${cachePath}`, { cause: err });
+    catch {
+        // Invalid JSON: treat the whole cache as empty rather than throwing.
+        // loadToolCache reports "no cache" and saveToolCache rebuilds it.
+        return {};
     }
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Tool cache file must contain a JSON object: ${cachePath}`);
+}
+/**
+ * Writes `data` to `cachePath` atomically: the content is first written
+ * to a unique temporary sibling file and then renamed over the target.
+ * Renaming within the same directory is atomic on POSIX, so a reader
+ * (or a crash mid-write) can never observe a truncated or half-written
+ * cache file — it sees either the previous complete file or the new
+ * complete file.
+ *
+ * @param cachePath - Target cache file path.
+ * @param data - Full file content to write.
+ */
+async function writeCacheFileAtomic(cachePath, data) {
+    const tempPath = `${cachePath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        await fs.writeFile(tempPath, data);
+        await fs.rename(tempPath, cachePath);
+    }
+    catch (err) {
+        await fs.unlink(tempPath).catch(() => { });
+        throw err;
     }
-    return parsed;
 }
 /**
  * Saves discovered tools to the on-disk tool cache for a single server.
@@ -98,7 +143,7 @@ export async function saveToolCache(configPath, serverName, tools) {
             tools,
             cachedAt: new Date().toISOString(),
         };
-        await fs.writeFile(cachePath, JSON.stringify(store, null, 2) + '\n');
+        await writeCacheFileAtomic(cachePath, JSON.stringify(store, null, 2) + '\n');
     });
 }
 /**
@@ -108,8 +153,8 @@ export async function saveToolCache(configPath, serverName, tools) {
  *
  * @param configPath - Absolute path to the mcp.json file.
  * @param serverName - The server whose cached tools to load.
- * @returns The cached tool descriptors, or `undefined` when not cached.
- * @throws If the cache file exists but contains invalid JSON.
+ * @returns The cached tool descriptors, or `undefined` when not cached
+ *   (including when the cache file is missing or corrupted).
  */
 export async function loadToolCache(configPath, serverName) {
     const store = await readCacheStore(configPath);
@@ -143,7 +188,7 @@ export async function clearToolCache(configPath, serverName) {
             await fs.unlink(cachePath).catch(() => { });
         }
         else {
-            await fs.writeFile(cachePath, JSON.stringify(store, null, 2) + '\n');
+            await writeCacheFileAtomic(cachePath, JSON.stringify(store, null, 2) + '\n');
         }
     });
 }

package/build/utils/open-browser.js

@@ -1,12 +1,51 @@
 import { spawn } from 'node:child_process';
+/**
+ * Splits a command line into executable + arguments, honoring shell-style
+ * quoting so paths with spaces work. Supports single and double quotes;
+ * no escape sequences (environment overrides never need them).
+ *
+ * @param input - The command line to split.
+ * @returns The program and its pre-set arguments.
+ */
+function splitCommandLine(input) {
+    const parts = [];
+    let current = '';
+    let quote;
+    for (const char of input) {
+        if (quote !== undefined) {
+            if (char === quote) {
+                quote = undefined;
+            }
+            else {
+                current += char;
+            }
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+        }
+        else if (char === ' ' || char === '\t') {
+            if (current.length > 0) {
+                parts.push(current);
+                current = '';
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.length > 0) {
+        parts.push(current);
+    }
+    return parts;
+}
 /**
  * Opens a URL in the default browser using the platform-native command.
  *
  * The browser command can be overridden with the
  * `MCP_COMPRESS_ROUTER_BROWSER` environment variable. Set it to the
  * executable plus any preset arguments (e.g.
- * `node /path/to/headless-browser.js --flag`); the URL is always appended
- * as a single, final argument. No shell is used, so there is no
+ * `node "/path/with spaces/headless-browser.js" --flag`); the URL is always
+ * appended as a single, final argument. No shell is used, so there is no
  * shell-injection risk — this also makes the override safe to drive OAuth
  * flows in headless and CI environments.
  *
@@ -15,7 +54,7 @@ import { spawn } from 'node:child_process';
 export async function openBrowser(url) {
     const customBrowser = process.env.MCP_COMPRESS_ROUTER_BROWSER;
     if (customBrowser && customBrowser.trim().length > 0) {
-        const [command, ...presetArgs] = customBrowser.trim().split(/\s+/);
+        const [command, ...presetArgs] = splitCommandLine(customBrowser.trim());
         return spawnBrowser(command, [...presetArgs, url]);
     }
     const platform = process.platform;

package/package.json

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