mcp-compress-router 1.4.0 → 1.5.1

package/README.md

@@ -145,8 +145,9 @@ startup, so you can keep secrets out of the config (see
 
 > **Note on `-c` and credential storage:** when you override the config
 > path with `-c /some/dir/mcp.json`, both `credentials.json` (OAuth
-> tokens) and `mcp.json` live in `/some/dir/` — i.e. next to the config
-> file you specified. The `.env` file, however, is loaded from the
+> tokens) and `tools-cache.json` (cached tool schemas) will be stored
+> in that directory — i.e. next to the config file you specified. The
+> `.env` file, however, is loaded from the
 > [configuration directory](#config-file-location) resolved by
 > `MCP_COMPRESS_ROUTER_HOME` or the platform default, *not* from beside
 > the explicit `-c` path. To co-locate `.env` with a custom config, set
@@ -367,8 +368,10 @@ npx mcp-compress-router@latest login my-http
 This opens your browser to complete the authorization-code flow. Tokens
 are stored in a separate `credentials.json` in the same directory as
 `mcp.json` (with `0600` permissions on Unix), so you can safely
-share or version-control `mcp.json` without exposing tokens. Add
-`credentials.json` to your `.gitignore`.
+share or version-control `mcp.json` without exposing tokens. Cached
+tool schemas are stored in `tools-cache.json` in the same directory.
+Add both `credentials.json` and `tools-cache.json` to your
+`.gitignore`.
 
 By default the router uses
 [Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591).

package/build/cli/login-command.js

@@ -1,6 +1,7 @@
+import { Logger } from '../utils/index.js';
 import { ensureConfigDir, readConfigFile } from './config-io.js';
 import { loadConfig } from '../services/config.js';
-import { discoverAuth } from '../services/index.js';
+import { discoverAuth, discoverSingleServer, saveToolCache } from '../services/index.js';
 /**
  * Validates that a server exists in config and is eligible for OAuth login.
  *
@@ -260,5 +261,16 @@ export async function handleLogin(configPath, name, portOverride) {
         redirectUri: realRedirectUrl,
     });
     await mgr.saveTokens(tokens);
+    // Best-effort: discover tools and save to cache so the next router
+    // startup (or self-recovery) has an up-to-date cache.
+    try {
+        const logger = new Logger('error');
+        const discovered = await discoverSingleServer(targetServer, logger, () => mgr);
+        await saveToolCache(configPath, name, discovered.tools);
+    }
+    catch {
+        // Best-effort — tokens are saved, cache will refresh on next
+        // router startup.
+    }
     return `Successfully authenticated server "${name}". Tokens stored in credentials.json.`;
 }

package/build/cli/router-runner.js

@@ -1,31 +1,53 @@
-import { resolveConfigPath, invokeDownstreamTool, OAuthCredentialManager, persistAuthRequirements, loadConfig, connectAndDiscover, 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';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 /**
- * Creates OAuth credential managers for HTTP servers that have stored
- * credentials or oauth overrides, so the transport can handle auth.
+ * 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.
+ *
+ * @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.
+ * @throws When a server cannot connect AND has no tool cache.
  */
-async function buildAuthProviders(resolved, servers) {
-    const authProviders = new Map();
-    for (const server of servers) {
-        if (server.type === 'http' || server.type === 'streamable-http') {
-            const mgr = new OAuthCredentialManager(resolved, server);
-            const hasCredentials = (await mgr.tokens()) !== undefined;
-            const hasOverrides = server.oauth?.clientId !== undefined;
-            if (hasCredentials || hasOverrides) {
-                authProviders.set(server.name, mgr);
-            }
+async function connectAllServers(servers, configPath, logger) {
+    const enabledServers = servers.filter((server) => {
+        if (server.enabled === false) {
+            logger.info(`Skipping disabled server "${server.name}"`, { server: server.name });
+            return false;
         }
+        return true;
+    });
+    const results = await Promise.all(enabledServers.map(async (server) => {
+        const conn = new ServerConnection(server, configPath, logger);
+        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 authProviders;
+    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, clients, logger) {
+async function startRouterServer(catalog, connections, selectionByServer, logger) {
     const router = new McpServer({
         name: 'mcp-compress-router',
         version: '1.0.0',
@@ -35,7 +57,9 @@ async function startRouterServer(catalog, clients, logger) {
         description: buildGetToolSchemaDescription(catalog),
         inputSchema: GetToolSchemaInputSchema,
     }, createGetToolSchemaHandler(catalog, logger));
-    const invokeFn = (server, tool, args) => invokeDownstreamTool(clients, server, tool, args, 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. ' +
@@ -46,6 +70,29 @@ async function startRouterServer(catalog, clients, 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,
@@ -66,17 +113,15 @@ export async function runRouter(configPath, verbose) {
     const servers = await loadConfig(resolved);
     logger.info('Configuration loaded', { serverCount: servers.length });
     await persistAuthRequirements(resolved, servers, logger);
-    const authProviders = await buildAuthProviders(resolved, servers);
-    const getAuthProvider = (server) => authProviders.get(server.name);
     logger.info('Connecting to downstream servers', {
         servers: servers.map((s) => s.name),
     });
-    const { servers: discovered, clients } = await connectAndDiscover(servers, logger, getAuthProvider);
+    const { connections, discovered } = await connectAllServers(servers, resolved, logger);
     logger.info('Tools discovered', {
         servers: discovered.map((d) => ({
             name: d.name,
             toolCount: d.tools.length,
-            tools: d.tools.map((t) => t.name),
+            status: d.status,
         })),
     });
     const selectionByServer = new Map();
@@ -89,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, clients, 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

@@ -0,0 +1,22 @@
+/**
+ * Tagged error thrown when a downstream server requires OAuth
+ * authentication that cannot be completed from the running router
+ * process.
+ *
+ * The MCP SDK calls `OAuthClientProvider.redirectToAuthorization()` on
+ * a 401 response. This error is thrown from that method so callers
+ * can discriminate auth failures from other errors (network, config,
+ * transport) without relying on substring matching of error messages.
+ */
+export class GuidedAuthError extends Error {
+    /** The downstream server name that requires authentication. */
+    serverName;
+    /**
+     * @param serverName - The name of the server requiring authentication.
+     */
+    constructor(serverName) {
+        super(`Authentication required for server "${serverName}".`);
+        this.name = 'GuidedAuthError';
+        this.serverName = serverName;
+    }
+}

package/build/services/catalog.js

@@ -41,10 +41,54 @@ export function buildCatalog(discovered, selectionByServer = new Map(), logger,
             description: ds.description,
             tools: exposed,
             compressionLevel: compressionLevelByServer.get(ds.name) ?? 'high',
+            status: ds.status ?? 'ok',
         };
     });
     return { servers, toolMap, filteredToolNames };
 }
+/**
+ * Updates a single server's tools and status in an existing catalog
+ * (mutates in place). Removes old `toolMap` entries for the server,
+ * re-applies the tool filter, and inserts the new entries.
+ *
+ * Used by `invokeWithRecovery` after a successful reconnect to make
+ * the freshly-discovered tools visible to `get_tool_schema` and
+ * `invoke_tool` without restarting the router.
+ *
+ * @param catalog - The tool catalog to mutate.
+ * @param serverName - The server to update.
+ * @param tools - The newly-discovered tool descriptors.
+ * @param status - The new connection status.
+ * @param toolSelection - Optional allowlist/denylist to re-apply.
+ */
+export function updateServerInCatalog(catalog, serverName, tools, status, toolSelection) {
+    const server = catalog.servers.find((s) => s.name === serverName);
+    if (!server) {
+        return;
+    }
+    const prefix = `${serverName}::`;
+    for (const key of [...catalog.toolMap.keys()]) {
+        if (key.startsWith(prefix)) {
+            catalog.toolMap.delete(key);
+        }
+    }
+    for (const key of [...catalog.filteredToolNames]) {
+        if (key.startsWith(prefix)) {
+            catalog.filteredToolNames.delete(key);
+        }
+    }
+    const { exposed, entries } = filterTools(tools, toolSelection?.allowedTools, toolSelection?.disabledTools);
+    for (const tool of exposed) {
+        catalog.toolMap.set(`${serverName}::${tool.name}`, tool);
+    }
+    for (const entry of entries) {
+        if (entry.decision === 'filtered') {
+            catalog.filteredToolNames.add(`${serverName}::${entry.descriptor.name}`);
+        }
+    }
+    server.tools = exposed;
+    server.status = status;
+}
 /**
  * Looks up tool schemas in the catalog by server and tool names.
  *

package/build/services/discovery.js

@@ -24,7 +24,7 @@ function isMethodNotFound(err) {
  * @returns The list-tools result (possibly empty).
  * @throws Any non-"Method not found" error from `listTools()`.
  */
-async function listToolsOrEmpty(client) {
+export async function listToolsOrEmpty(client) {
     try {
         return await client.listTools();
     }
@@ -35,44 +35,12 @@ async function listToolsOrEmpty(client) {
         throw err;
     }
 }
-/**
- * Connects to all configured stdio servers in parallel and discovers
- * their tools. Fails fast if any server is unreachable.
- *
- * @param servers - Validated downstream server configs.
- * @param logger - Structured logger for diagnostic output.
- * @param getAuthProvider - Optional factory to provide OAuth credentials for HTTP servers.
- * @returns Discovered server data and live client connections.
- * @throws If any server cannot be connected or tools cannot be listed.
- */
-export async function connectAndDiscover(servers, logger, getAuthProvider) {
-    const enabledServers = [];
-    for (const server of servers) {
-        if (server.enabled === false) {
-            logger.info(`Skipping disabled server "${server.name}"`, {
-                server: server.name,
-            });
-        }
-        else {
-            enabledServers.push(server);
-        }
-    }
-    const results = await Promise.all(enabledServers.map((server) => connectSingleServer(server, logger, getAuthProvider)));
-    const serversList = [];
-    const clients = new Map();
-    for (const { server, client } of results) {
-        serversList.push(server);
-        clients.set(server.name, client);
-    }
-    return { servers: serversList, clients };
-}
 /**
  * Connects to a single downstream server, lists its tools, and closes
- * the connection. Unlike {@link connectAndDiscover}, this function does
+ * the connection. Unlike the router startup path, this function does
  * NOT inspect the server's `enabled` flag — it always probes live. It
- * is the engine behind the `tools <name>` inspection command, which
- * must work for disabled servers (building an allowlist for a disabled
- * server is the primary configuration workflow).
+ * is the engine behind the `tools <name>` inspection command and the
+ * `login` command's post-authentication cache refresh.
  *
  * The returned {@link DiscoveredServer} carries every advertised tool;
  * callers apply the Tool Filter themselves to compute exposure marks.
@@ -81,25 +49,10 @@ export async function connectAndDiscover(servers, logger, getAuthProvider) {
  * @param logger - Structured logger for diagnostic output.
  * @param getAuthProvider - Optional factory to provide OAuth credentials
  *   for HTTP servers.
- * @returns The discovered server data (name, description, tools).
+ * @returns The discovered server data (name, description, tools, status).
  * @throws If the server cannot be connected or tools cannot be listed.
- * @public
  */
 export async function discoverSingleServer(server, logger, getAuthProvider) {
-    const { client, server: discovered } = await connectSingleServer(server, logger, getAuthProvider);
-    await client.close();
-    return discovered;
-}
-/**
- * Connects to a single downstream server and discovers its tools.
- *
- * @param server - Downstream server configuration.
- * @param logger - Structured logger for diagnostic output.
- * @param getAuthProvider - Optional factory to provide OAuth credentials.
- * @returns The discovered server data and live client connection.
- * @throws If the server cannot be connected or tools cannot be listed.
- */
-async function connectSingleServer(server, logger, getAuthProvider) {
     const client = new Client({ name: 'mcp-compress-router', version: '1.0.0' }, { capabilities: {} });
     logger.info(`Connecting to downstream server "${server.name}"`, {
         server: server.name,
@@ -120,12 +73,10 @@ async function connectSingleServer(server, logger, getAuthProvider) {
             inputSchema: t.inputSchema,
         }));
         return {
-            server: {
-                name: server.name,
-                description: server.description,
-                tools,
-            },
-            client,
+            name: server.name,
+            description: server.description,
+            tools,
+            status: 'ok',
         };
     }
     catch (err) {
@@ -137,6 +88,9 @@ async function connectSingleServer(server, logger, getAuthProvider) {
         });
         throw new Error(`Failed to connect to server "${server.name}": ${message}`);
     }
+    finally {
+        await client.close().catch(() => { });
+    }
 }
 /**
  * Creates the appropriate transport for a downstream server config.
@@ -146,7 +100,7 @@ async function connectSingleServer(server, logger, getAuthProvider) {
  * @returns A configured transport instance (stdio or HTTP).
  * @throws If required configuration (command or url) is missing.
  */
-function createTransport(server, getAuthProvider) {
+export function createTransport(server, getAuthProvider) {
     if (server.type === 'stdio') {
         if (!server.command) {
             throw new Error(`Server "${server.name}" (stdio) is missing command`);

package/build/services/guided-error.js

@@ -0,0 +1,106 @@
+/**
+ * Builds a detailed, multi-line error message for an unavailable
+ * downstream server, explaining what happened, showing the underlying
+ * error, and giving actionable steps including the restart fallback.
+ *
+ * The message format is:
+ *
+ * 1. Summary line: server name + what went wrong.
+ * 2. "What happened:" section.
+ * 3. "Underlying error:" — the original error message verbatim.
+ * 4. "To fix this:" — numbered, actionable steps tailored to the
+ *    server type and status.
+ * 5. Restart fallback guidance.
+ *
+ * @param server - The downstream server configuration.
+ * @param underlyingError - The original error that caused the failure.
+ * @param status - The server's current status.
+ * @param recoveryAttempted - Whether automatic recovery was tried and
+ *   failed. When true, an additional note is included.
+ * @returns An `Error` with the detailed message.
+ */
+export function buildGuidedError(server, underlyingError, status, recoveryAttempted) {
+    const underlyingMessage = extractMessage(underlyingError);
+    const isStdio = server.type === 'stdio';
+    const isAuth = status === 'unauthorized';
+    const lines = [];
+    lines.push(`Server "${server.name}" is unavailable: ${headline(server, status)}.`);
+    lines.push('');
+    lines.push('What happened:');
+    lines.push(bodyText(server, status, isStdio, isAuth));
+    lines.push('');
+    lines.push(`Underlying error: ${underlyingMessage}`);
+    if (recoveryAttempted) {
+        lines.push('');
+        lines.push('Automatic recovery was attempted but failed.');
+    }
+    lines.push('');
+    lines.push('To fix this:');
+    lines.push(...fixSteps(server, status, isStdio, isAuth));
+    lines.push('');
+    lines.push(restartGuidance(isStdio));
+    return new Error(lines.join('\n'));
+}
+function headline(server, status) {
+    if (status === 'unauthorized') {
+        return 'authentication is required';
+    }
+    if (server.type === 'stdio') {
+        return 'the downstream process could not start';
+    }
+    return 'connection failed';
+}
+function bodyText(server, status, isStdio, isAuth) {
+    if (isAuth) {
+        return (`The router could not connect to server "${server.name}" because ` +
+            `authentication is required or the stored credentials are invalid.`);
+    }
+    if (isStdio) {
+        return (`The router could not start server "${server.name}" because the ` +
+            `configured command failed to spawn or connect.`);
+    }
+    return `The router could not establish a connection to server "${server.name}".`;
+}
+function fixSteps(server, status, isStdio, isAuth) {
+    if (isAuth) {
+        return [
+            `1. Run:  npx mcp-compress-router login ${server.name}`,
+            '2. Complete the browser authorization flow.',
+            '3. Try your request again — the router will automatically pick up the',
+            '   new credentials and reconnect.',
+        ];
+    }
+    if (isStdio) {
+        const cmd = server.command ?? '(unknown)';
+        return [
+            `1. Verify the command is installed: ${cmd}`,
+            '2. Check that the command is in your PATH.',
+            '3. If using npx, ensure the package is available.',
+            '4. If the configuration has changed, update mcp.json.',
+        ];
+    }
+    return [
+        '1. Verify the server is running and reachable.',
+        '2. Check your network connection and configuration.',
+        '3. If the configuration has changed, update mcp.json.',
+        '',
+        'After fixing, try your request again — the router will attempt to',
+        'reconnect automatically.',
+    ];
+}
+function restartGuidance(isStdio) {
+    const restartClause = isStdio
+        ? 'Stdio servers cannot self-recover without a restart because the ' +
+            'process must be spawned anew.'
+        : '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.');
+}
+function extractMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}

package/build/services/index.js

@@ -1,7 +1,13 @@
 export { buildCatalog, lookupTools } from './catalog.js';
 export { resolveConfigDir, resolveConfigPath, loadConfig } from './config.js';
-export { connectAndDiscover, discoverSingleServer } from './discovery.js';
-export { invokeDownstreamTool } from './invoker.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 { buildGuidedError } from './guided-error.js';