mcp-compress-router 1.1.0 → 1.2.0

package/README.md

@@ -27,6 +27,8 @@
     - [Per-Server Tool Selection](#per-server-tool-selection)
     - [Inspecting Tools](#inspecting-tools)
     - [OAuth](#oauth)
+        - [Redirect URL](#redirect-url)
+        - [GitHub MCP (special case)](#github-mcp-special-case)
     - [Custom Headers](#custom-headers)
     - [Secrets and Variable Expansion](#secrets-and-variable-expansion)
 - [Connecting Coding Agents](#connecting-coding-agents)
@@ -329,6 +331,104 @@ the server entry (in `mcp.json`):
 
 Only `clientId` is required; `clientSecret` and `scope` are optional.
 
+#### Redirect URL
+
+During `login` the router starts a temporary local HTTP server and uses
+a loopback redirect URI (per [RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252)):
+
+```text
+http://localhost:<port>/mcp-compress-router/oauth-callback
+```
+
+`<port>` is chosen by the OS at login time, so there is no fixed port to
+register. When a provider requires a pre-registered redirect URI,
+register the loopback form **without a port**:
+
+```text
+http://localhost/mcp-compress-router/oauth-callback
+```
+
+Most providers (GitHub included) match the scheme, host, and path and
+ignore the port on `localhost`. If your provider demands a redirect URI
+with an **exact port**, pin it with `--port`:
+
+```bash
+npx mcp-compress-router login my-http --port 8765
+```
+
+This binds the callback server to `8765`, so the redirect URI becomes
+`http://localhost:8765/mcp-compress-router/oauth-callback` — register
+that exact URL with the provider. To reuse the same port on every
+`login`, persist it in the server's `oauth` block instead of passing the
+flag each time:
+
+```jsonc
+"my-http": {
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "oauth": { "clientId": "${ID}", "callbackPort": 8765 }
+}
+```
+
+`--port` overrides `oauth.callbackPort` for a single run. Pass `--port 0`
+to force an OS-assigned port even when `oauth.callbackPort` is set.
+
+#### GitHub MCP (special case)
+
+The official GitHub MCP server at
+`https://api.githubcopilot.com/mcp` advertises OAuth but does **not**
+support Dynamic Client Registration, so you must pre-register a GitHub
+OAuth App and pass its credentials via the `oauth` block. GitHub also
+requires that the OAuth App be installed to the repositories and
+organizations you want the MCP to access.
+
+1. **Create a GitHub OAuth App.**
+   Open <https://github.com/settings/developers> → *New OAuth App* (or
+   *Register an application*). Give it any name and homepage URL.
+2. **Configure the callback URL.**
+   Set the *Authorization callback URL* to:
+   `http://localhost/mcp-compress-router/oauth-callback`
+3. **Add the GitHub MCP server by URL.**
+
+   ```bash
+   npx mcp-compress-router add github https://api.githubcopilot.com/mcp
+   ```
+
+4. **Set `oauth` credentials in `mcp.json`.**
+   Copy the Client ID and generate a Client Secret, then put them in the
+   server entry (use variable expansion to keep secrets out of the
+   file):
+
+   ```jsonc
+   "github": {
+     "type": "http",
+     "url": "https://api.githubcopilot.com/mcp",
+     "oauth": {
+       "clientId": "${GITHUB_OAUTH_CLIENT_ID}",
+       "clientSecret": "${GITHUB_OAUTH_CLIENT_SECRET}",
+       "scope": "repo read:org"
+     }
+   }
+   ```
+
+   Request only the scopes the tools you need require; `repo read:org`
+   covers the common repo and organization operations. Put the actual
+   values in your `.env` file (see
+   [Secrets and Variable Expansion](#secrets-and-variable-expansion)).
+5. **Run the login command.**
+
+   ```bash
+   npx mcp-compress-router login github
+   ```
+
+   Your browser opens to authorize. After you approve, tokens are stored
+   in `credentials.json` and the router can call GitHub MCP tools.
+
+> **Note:** if you used a *GitHub App* (not a classic OAuth App), the
+> App must be installed to the accounts/repos you want to access before
+> login will succeed, and its client secret is generated under *General*
+> → *Generate a new client secret*.
+
 Other OAuth commands:
 
 ```bash

package/build/cli/add-command.js

@@ -61,6 +61,17 @@ function buildServerEntry(opts) {
     if (opts.disabledTools && opts.disabledTools.length > 0) {
         entry.disabledTools = opts.disabledTools;
     }
+    // A fixed callback port only applies to HTTP servers (OAuth). Persist
+    // it on the `oauth` block so `login` reuses the same redirect URI.
+    if (opts.port !== undefined) {
+        if (type !== 'http') {
+            throw new Error('--port is only supported for HTTP servers (OAuth callback).');
+        }
+        if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535) {
+            throw new Error(`--port must be an integer between 1 and 65535 (got ${opts.port}).`);
+        }
+        entry.oauth = { callbackPort: opts.port };
+    }
     return { entry, type };
 }
 /**
@@ -107,10 +118,13 @@ export async function handleAdd(configPath, opts) {
     return result;
 }
 /**
- * Probes the server for OAuth metadata and, if found, runs the login
- * flow automatically. The probed auth requirement is cached in
- * `credentials.json` regardless of the login outcome so the `list`
- * command can show auth status without re-probing.
+ * Probes the server for OAuth metadata using the spec-compliant two-step
+ * discovery flow (RFC 9728 Protected Resource Metadata, then RFC 8414
+ * Authorization Server Metadata at each advertised authorization server)
+ * and, if OAuth is advertised, runs the login flow automatically. The
+ * probed auth requirement is cached in `credentials.json` regardless of
+ * the login outcome so the `list` command can show auth status without
+ * re-probing.
  *
  * @param configPath - Absolute path to the mcp.json file.
  * @param name - Server name just added.
@@ -119,12 +133,18 @@ export async function handleAdd(configPath, opts) {
  * does not advertise OAuth (or the probe failed).
  */
 async function tryAutoLogin(configPath, name, url) {
-    const { discoverAuthorizationServerMetadata } = await import('@modelcontextprotocol/sdk/client/auth.js');
+    // Use the spec-compliant two-step discovery (RFC 9728 PRM, then RFC 8414
+    // AS metadata at each advertised authorization server). A one-step
+    // `discoverAuthorizationServerMetadata` probe misses servers that
+    // publish their AS only via PRM `authorization_servers` (e.g. Notion,
+    // whose AS metadata lives at the origin root, not the path-qualified
+    // well-known URL).
+    const { discoverAuth } = await import('../services/oauth-discovery.js');
     let requirement;
     let hasOAuth;
     try {
-        const metadata = await discoverAuthorizationServerMetadata(new URL(url));
-        hasOAuth = metadata !== undefined;
+        const discovered = await discoverAuth(new URL(url));
+        hasOAuth = Boolean(discovered.serverMetadata);
         requirement = hasOAuth ? 'oauth' : 'none';
     }
     catch {

package/build/cli/login-command.js

@@ -1,5 +1,6 @@
 import { ensureConfigDir, readConfigFile } from './config-io.js';
 import { loadConfig } from '../services/config.js';
+import { discoverAuth } from '../services/index.js';
 /**
  * Validates that a server exists in config and is eligible for OAuth login.
  *
@@ -48,16 +49,21 @@ async function _getSdkAuth() {
  * @throws If the server does not expose OAuth metadata or registration.
  */
 async function setupOAuthClient(mgr, targetServer, name) {
-    const { discoverOAuthMetadata, registerClient } = await _getSdkAuth();
+    const { registerClient } = await _getSdkAuth();
     const serverUrl = new URL(targetServer.url);
-    const metadata = await discoverOAuthMetadata(serverUrl);
+    const discovered = await discoverAuth(serverUrl);
+    const metadata = discovered.serverMetadata;
     if (!metadata) {
         throw new Error(`Server "${name}" does not expose OAuth metadata.`);
     }
-    if (!metadata.registration_endpoint) {
-        throw new Error(`Server "${name}" does not support dynamic client registration.`);
-    }
+    // DCR is only required when there is no pre-registered client (static
+    // override) and no previously stored client information. Servers without a
+    // registration_endpoint (e.g. GitHub) work when an "oauth.clientId"
+    // override is configured.
     if (!mgr.hasStaticClient() && !(await mgr.clientInformation())) {
+        if (!metadata.registration_endpoint) {
+            throw new Error(`Server "${name}" does not support dynamic client registration. Configure an "oauth.clientId" override in mcp.json with a pre-registered client ID.`);
+        }
         const regResult = await registerClient(new URL(metadata.registration_endpoint), {
             metadata,
             clientMetadata: mgr.clientMetadata,
@@ -76,11 +82,11 @@ async function setupOAuthClient(mgr, targetServer, name) {
  * @returns The authorization code and the full `startAuthorization` result.
  * @throws If the callback times out or the authorization is denied.
  */
-async function acquireAuthorizationCode(mgr, metadata, targetServer) {
+async function acquireAuthorizationCode(mgr, metadata, targetServer, callbackPort) {
     const { startAuthorization } = await _getSdkAuth();
     const { openBrowser } = await import('../utils/open-browser.js');
     const TIMEOUT_MS = _readTimeoutMs();
-    return _startCallbackServerAndWait(mgr, metadata, targetServer, startAuthorization, openBrowser, TIMEOUT_MS);
+    return _startCallbackServerAndWait(mgr, metadata, targetServer, startAuthorization, openBrowser, TIMEOUT_MS, callbackPort);
 }
 /**
  * Creates the HTTP request listener for the temporary OAuth callback server.
@@ -123,14 +129,14 @@ function _makeCallbackHandler(timeoutHandle, tempServer, resolve, reject) {
     };
 }
 /** Creates a temp HTTP server, starts OAuth flow, waits for callback. */
-async function _startCallbackServerAndWait(mgr, metadata, targetServer, startAuthorization, openBrowser, TIMEOUT_MS) {
+async function _startCallbackServerAndWait(mgr, metadata, targetServer, startAuthorization, openBrowser, TIMEOUT_MS, callbackPort) {
     const http = await import('node:http');
     const timeoutHandle = { current: undefined };
     const authResultRef = { value: undefined };
     const authorizationCode = await new Promise((resolve, reject) => {
         const tempServer = http.createServer();
         tempServer.on('request', _makeCallbackHandler(timeoutHandle, tempServer, resolve, reject));
-        tempServer.listen(0, _onServerListen(tempServer, mgr, metadata, targetServer, startAuthorization, openBrowser, TIMEOUT_MS, timeoutHandle, authResultRef, reject));
+        tempServer.listen(callbackPort, _onServerListen(tempServer, mgr, metadata, targetServer, startAuthorization, openBrowser, TIMEOUT_MS, timeoutHandle, authResultRef, reject));
         tempServer.on('error', (err) => {
             if (timeoutHandle.current)
                 clearTimeout(timeoutHandle.current);
@@ -185,6 +191,39 @@ function _readTimeoutMs() {
     }
     return 120_000;
 }
+/**
+ * Validates a requested callback port override from the `--port` flag.
+ *
+ * @param port - The raw port value (0 means "OS-assigned", undefined
+ *   means "use config or OS-assigned").
+ * @returns The validated port number (0 or a positive integer
+ *   1-65535), or undefined when no override was given.
+ * @throws If the port is not a valid integer in range.
+ */
+function _validatePortOverride(port) {
+    if (port === undefined) {
+        return undefined;
+    }
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`--port must be an integer between 0 and 65535 (got ${port}). Use 0 to let the OS assign a port.`);
+    }
+    return port;
+}
+/**
+ * Resolves the effective callback port from the `--port` override, the
+ * server's `oauth.callbackPort` config field, or 0 (OS-assigned) as a
+ * final fallback.
+ *
+ * @param override - The validated `--port` override, or undefined.
+ * @param server - The typed downstream server configuration.
+ * @returns The port to bind the callback server on (0 = OS-assigned).
+ */
+function _resolveCallbackPort(override, server) {
+    if (override !== undefined) {
+        return override;
+    }
+    return server.oauth?.callbackPort ?? 0;
+}
 /**
  * Handles the `login <name>` subcommand.
  *
@@ -196,15 +235,21 @@ function _readTimeoutMs() {
  *
  * @param configPath - Absolute path to the mcp.json file.
  * @param name - Server name to authenticate.
+ * @param portOverride - Optional `--port` override for the local
+ *   callback server. 0 forces an OS-assigned port; a positive integer
+ *   binds to that exact port (overrides `oauth.callbackPort`). When
+ *   omitted, `oauth.callbackPort` from config is used, falling back to
+ *   an OS-assigned port.
  * @returns Human-readable confirmation message.
  * @throws If the server name is not found or is not an HTTP type.
  */
-export async function handleLogin(configPath, name) {
+export async function handleLogin(configPath, name, portOverride) {
     const { targetServer } = await validateServerForLogin(configPath, name);
+    const callbackPort = _resolveCallbackPort(_validatePortOverride(portOverride), targetServer);
     const { OAuthCredentialManager } = await import('../services/oauth.js');
     const mgr = new OAuthCredentialManager(configPath, targetServer);
     const metadata = await setupOAuthClient(mgr, targetServer, name);
-    const { authorizationCode, authResult } = await acquireAuthorizationCode(mgr, metadata, targetServer);
+    const { authorizationCode, authResult } = await acquireAuthorizationCode(mgr, metadata, targetServer, callbackPort);
     const { exchangeAuthorization } = await _getSdkAuth();
     const realRedirectUrl = mgr.redirectUrl;
     const tokens = await exchangeAuthorization(new URL(metadata.token_endpoint), {

package/build/cli/register-commands.js

@@ -34,6 +34,19 @@ export function collectEnv(value, previous) {
 export function collectStringArray(value, previous) {
     return [...previous, value];
 }
+/**
+ * Coerces a `--port` flag value into an integer. Throws on non-numeric
+ * values so the user gets a clear error before any network activity.
+ * Range validation is deferred to the command handlers.
+ * @internal — Exported for tests only; not part of the public module API.
+ */
+export function parsePort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port)) {
+        throw new Error(`--port must be an integer (got "${value}").`);
+    }
+    return port;
+}
 /**
  * Wraps a CLI action handler with error handling.
  * On success, writes the result to stdout. On error, writes to stderr
@@ -70,6 +83,7 @@ function buildAddOptions(name, commandOrUrl, rest, options) {
         disabled: options.disabled || undefined,
         allowedTools: options.allowedTools && options.allowedTools.length > 0 ? options.allowedTools : undefined,
         disabledTools: options.disabledTools && options.disabledTools.length > 0 ? options.disabledTools : undefined,
+        port: options.port,
     };
 }
 function registerAddCommand(program) {
@@ -85,6 +99,7 @@ function registerAddCommand(program) {
         .option('--disabled', 'mark the server as disabled (writes "enabled": false)')
         .option('--allowed-tools <pattern>', 'glob pattern allowlisting tool names (repeatable)', collectStringArray, [])
         .option('--disabled-tools <pattern>', 'glob pattern denylisting tool names (repeatable)', collectStringArray, [])
+        .option('-p, --port <number>', 'fixed local OAuth callback port (HTTP only; written to oauth.callbackPort)', parsePort)
         .action(guardedAction(async (name, commandOrUrl, rest, options) => {
         const configPath = await resolveConfigPath(options.config);
         return handleAdd(configPath, buildAddOptions(name, commandOrUrl, rest, options));
@@ -125,9 +140,10 @@ function registerLoginCommand(program) {
         .command('login <name>')
         .description('Authenticate a downstream server using OAuth')
         .option('-c, --config <path>', 'path to mcp.json configuration file')
+        .option('-p, --port <number>', 'fixed local OAuth callback port (overrides oauth.callbackPort; 0 = OS-assigned)', parsePort)
         .action(guardedAction(async (name, options) => {
         const configPath = await resolveConfigPath(options.config);
-        return handleLogin(configPath, name);
+        return handleLogin(configPath, name, options.port);
     }));
 }
 function registerLogoutCommand(program) {

package/build/cli/tools-command.js

@@ -6,15 +6,22 @@ import { ensureConfigDir } from './config-io.js';
 const DESCRIPTION_MAX_WIDTH = 60;
 /**
  * Truncates a description to {@link DESCRIPTION_MAX_WIDTH} characters,
- * appending an ellipsis when truncated. Returns an empty string for
- * undefined input.
+ * appending an ellipsis when truncated. Collapses all whitespace
+ * (including embedded newlines from markdown descriptions) to single
+ * spaces so downstream table layout stays intact. Returns an empty
+ * string for undefined input.
+ *
+ * @internal Exported for tests only; not part of the public module API.
  */
-function truncateDescription(desc) {
+export function truncateDescription(desc) {
     if (!desc)
         return '';
-    if (desc.length <= DESCRIPTION_MAX_WIDTH)
-        return desc;
-    return desc.slice(0, DESCRIPTION_MAX_WIDTH - 1) + '…';
+    // Collapse all whitespace (including embedded newlines from markdown
+    // descriptions) to single spaces so the table layout stays intact.
+    const flat = desc.replace(/\s+/g, ' ').trim();
+    if (flat.length <= DESCRIPTION_MAX_WIDTH)
+        return flat;
+    return flat.slice(0, DESCRIPTION_MAX_WIDTH - 1) + '…';
 }
 /**
  * Renders the tools table from the filter result.

package/build/services/auth-status.js

@@ -1,16 +1,19 @@
 import { readCredentials, writeCredentials } from '../cli/config-io.js';
+import { discoverAuth } from './oauth-discovery.js';
 /**
- * Probes a downstream HTTP server's OAuth discovery endpoint to
- * determine whether it advertises OAuth support. Makes a single probe
- * of the server's well-known authorization-server metadata.
+ * Probes a downstream HTTP server to determine whether it advertises OAuth
+ * support, following the MCP 2025-06-18 two-step flow: RFC 9728 Protected
+ * Resource Metadata first, then RFC 8414 Authorization Server Metadata at
+ * each advertised authorization server (with an origin-root fallback for
+ * legacy servers).
  *
  * stdio servers never support OAuth, so they short-circuit to `'none'`
  * without any network access.
  *
  * @param server - Typed downstream server config.
  * @param logger - Optional logger for diagnostic output on probe errors.
- * @returns `'oauth'` when metadata is advertised, `'none'` when it is
- *   absent, or `'unknown'` on network/probe errors.
+ * @returns `'oauth'` when authorization-server metadata is advertised,
+ *   `'none'` when it is absent, or `'unknown'` on network/probe errors.
  * @internal Exported for tests only; not part of the public module API.
  */
 export async function probeAuthRequirement(server, logger) {
@@ -21,9 +24,8 @@ export async function probeAuthRequirement(server, logger) {
         return 'unknown';
     }
     try {
-        const { discoverAuthorizationServerMetadata } = await import('@modelcontextprotocol/sdk/client/auth.js');
-        const metadata = await discoverAuthorizationServerMetadata(new URL(server.url));
-        return metadata ? 'oauth' : 'none';
+        const discovered = await discoverAuth(new URL(server.url));
+        return discovered.serverMetadata ? 'oauth' : 'none';
     }
     catch (err) {
         logger?.error(`Failed to probe OAuth metadata for "${server.name}"`, {

package/build/services/config.js

@@ -194,6 +194,7 @@ function parseOauthBlock(entryContext, server) {
         ? expandEnvField(rawClientSecret, `${entryContext} oauth.clientSecret`)
         : undefined;
     const scope = rawScope !== undefined ? expandEnvField(rawScope, `${entryContext} oauth.scope`) : undefined;
+    const callbackPort = parseCallbackPort(oauthRaw.callbackPort, entryContext);
     const oauth = {};
     if (clientId !== undefined)
         oauth.clientId = clientId;
@@ -201,8 +202,31 @@ function parseOauthBlock(entryContext, server) {
         oauth.clientSecret = clientSecret;
     if (scope !== undefined)
         oauth.scope = scope;
+    if (callbackPort !== undefined)
+        oauth.callbackPort = callbackPort;
     return oauth;
 }
+/**
+ * Parses and validates the optional `oauth.callbackPort` field.
+ *
+ * Accepts a JSON number or a numeric string. Must be an integer between
+ * 1 and 65535. No env expansion is applied (ports are not secrets).
+ *
+ * @param value - The raw `callbackPort` value from the oauth block.
+ * @param entryContext - Human-readable context string for error messages.
+ * @returns The validated port number, or undefined when absent.
+ * @throws If the value is present but not a valid port number.
+ */
+function parseCallbackPort(value, entryContext) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const port = typeof value === 'number' ? value : Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Server "${entryContext.slice(8)}" oauth.callbackPort must be an integer between 1 and 65535`);
+    }
+    return port;
+}
 /**
  * Validates the optional `enabled` field on a server entry.
  *

package/build/services/index.js

@@ -4,3 +4,4 @@ export { connectAndDiscover, discoverSingleServer } from './discovery.js';
 export { invokeDownstreamTool } from './invoker.js';
 export { OAuthCredentialManager } from './oauth.js';
 export { computeAuthStatus, persistAuthRequirements } from './auth-status.js';
+export { discoverAuth } from './oauth-discovery.js';

package/build/services/oauth-discovery.js

@@ -0,0 +1,87 @@
+/**
+ * Discovers OAuth metadata for a downstream MCP server following the
+ * MCP 2025-06-18 authorization spec two-step flow:
+ *
+ * 1. RFC 9728 Protected Resource Metadata (PRM) at the server URL. When
+ *    present, its `authorization_servers` array lists the AS URLs to query.
+ * 2. RFC 8414 / OIDC Authorization Server Metadata at each advertised AS URL.
+ *
+ * Legacy servers that publish AS metadata directly at their host root without
+ * PRM are still supported: when no PRM is found (or it advertises no usable
+ * AS), discovery falls back to the server URL and, if that URL has a path,
+ * its origin root.
+ *
+ * All per-candidate discovery errors are swallowed and treated as "not
+ * found" so a single flaky endpoint never aborts the whole flow — discovery
+ * falls through to the next candidate. When no metadata is found anywhere
+ * AND at least one candidate threw, the last error is re-thrown so callers
+ * can distinguish a clean "no OAuth published" (all 404s) from an actual
+ * server/network failure (e.g. the auth probe reports `'unknown'`, the
+ * login command throws a guided error).
+ *
+ * @param serverUrl - The downstream MCP server URL to discover auth for.
+ * @returns The discovered resource and/or server metadata plus the AS URL
+ *   that yielded the metadata. `serverMetadata` is `undefined` when no OAuth
+ *   endpoints could be discovered.
+ * @throws The last discovery error when no metadata was found and at least
+ *   one candidate endpoint errored. Clean "not found" (all 404s) does not
+ *   throw.
+ */
+export async function discoverAuth(serverUrl) {
+    const { discoverOAuthProtectedResourceMetadata, discoverAuthorizationServerMetadata } = await import('@modelcontextprotocol/sdk/client/auth.js');
+    // Tracks the last error seen across all candidates so the caller can be
+    // notified when discovery failed entirely (vs. cleanly finding nothing).
+    let lastError;
+    // Tolerant AS discovery: any error (404-as-throw, 5xx, network) is
+    // recorded and treated as "not found" so the next candidate is tried.
+    const safeDiscoverAs = async (url) => {
+        try {
+            return await discoverAuthorizationServerMetadata(url);
+        }
+        catch (err) {
+            lastError = err;
+            return undefined;
+        }
+    };
+    // Step 1: RFC 9728 Protected Resource Metadata. This SDK function throws
+    // when no PRM is published (treated as "no PRM, fall through"), so its
+    // error is intentionally NOT recorded — absence of PRM is the normal
+    // legacy-server path, not a probe failure.
+    let resourceMetadata;
+    try {
+        resourceMetadata = await discoverOAuthProtectedResourceMetadata(serverUrl);
+    }
+    catch {
+        // No PRM published; fall through to direct AS discovery below.
+    }
+    // Step 2: AS metadata at each advertised authorization server.
+    if (resourceMetadata?.authorization_servers?.length) {
+        for (const asUrlString of resourceMetadata.authorization_servers) {
+            const asUrl = new URL(asUrlString);
+            const metadata = await safeDiscoverAs(asUrl);
+            if (metadata) {
+                return { resourceMetadata, serverMetadata: metadata, authorizationServerUrl: asUrl };
+            }
+        }
+    }
+    // Legacy fallback: direct AS discovery at the server URL, then its origin
+    // root (for servers that host AS metadata at the root with the MCP endpoint
+    // on a subpath and no PRM).
+    const candidates = [serverUrl];
+    if (serverUrl.pathname !== '/') {
+        candidates.push(new URL(serverUrl.origin));
+    }
+    for (const candidate of candidates) {
+        const metadata = await safeDiscoverAs(candidate);
+        if (metadata) {
+            return { resourceMetadata, serverMetadata: metadata, authorizationServerUrl: candidate };
+        }
+    }
+    // No metadata found anywhere. If any candidate actually errored (vs. a
+    // clean 404), surface that so callers can report a probe failure rather
+    // than a misleading "no OAuth supported".
+    if (lastError !== undefined) {
+        throw lastError;
+    }
+    return { resourceMetadata, serverMetadata: undefined, authorizationServerUrl: serverUrl };
+}

package/build/services/oauth.js

@@ -1,4 +1,16 @@
 import { readCredentials, writeCredentials, removeCredentials } from '../cli/config-io.js';
+/**
+ * The OAuth redirect callback path served by the temporary local HTTP
+ * server started during `login`. The full redirect URI is
+ * `http://localhost:<port>/mcp-compress-router/oauth-callback`, where
+ * `<port>` is assigned by the OS. Register this path (on `localhost`,
+ * any port) with OAuth providers that require a pre-registered client.
+ *
+ * @internal Exported for tests only; not part of the public module API.
+ *   The constant is consumed internally by `redirectUrl`; tests import
+ *   it directly to avoid hardcoding the path string.
+ */
+export const OAUTH_CALLBACK_PATH = '/mcp-compress-router/oauth-callback';
 /**
  * Implements OAuthClientProvider backed by credentials.json credential storage.
  *
@@ -29,7 +41,7 @@ export class OAuthCredentialManager {
     get redirectUrl() {
         // Return the callback URL with the actual port assigned by the OS.
         // Falls back to port 0 until setActualPort() is called by login-command.
-        return `http://localhost:${this._actualPort}/callback`;
+        return `http://localhost:${this._actualPort}${OAUTH_CALLBACK_PATH}`;
     }
     get clientMetadata() {
         return {

package/build/tools/get-tool-schema.js

@@ -55,7 +55,5 @@ export function createGetToolSchemaHandler(catalog, logger) {
  */
 export function buildGetToolSchemaDescription(catalog) {
     const compact = renderCompactCatalog(catalog.servers);
-    return ('Get the JSON schema for one or more tools from a connected MCP server.\n\n' +
-        'Available MCP servers and their tools:\n\n' +
-        compact);
+    return 'Get the JSON schema for one or more tools from a connected MCP server.\n\n' + compact;
 }

package/build/utils/text-format.js

@@ -5,20 +5,29 @@
  * Format:
  *   ## {server name}
  *   {description (optional)}
+ *
+ *   Available tools:
  *   {tool1}, {tool2}, ...
  *
+ * When a server has no tools, only the header (and optional
+ * description) is rendered.
+ *
  * @param servers - The catalog server entries.
  * @returns Compact catalog text.
  */
 export function renderCompactCatalog(servers) {
-    const lines = [];
+    const blocks = [];
     for (const server of servers) {
-        lines.push(`## ${server.name}`);
+        const lines = [`## ${server.name}`];
         if (server.description) {
             lines.push(server.description);
         }
-        lines.push(server.tools.map((t) => t.name).join(', '));
-        lines.push(''); // blank line between servers
+        if (server.tools.length > 0) {
+            lines.push('');
+            lines.push('Available tools:');
+            lines.push(server.tools.map((t) => t.name).join(', '));
+        }
+        blocks.push(lines.join('\n'));
     }
-    return lines.join('\n').trimEnd();
+    return blocks.join('\n\n');
 }

package/package.json

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