mcp-compress-router 1.3.0 → 1.4.0

package/README.md

@@ -25,10 +25,12 @@
     - [Adding Downstream Servers](#adding-downstream-servers)
     - [Per-Server Enable/Disable](#per-server-enabledisable)
     - [Per-Server Tool Selection](#per-server-tool-selection)
+    - [Compression Levels](#compression-levels)
     - [Inspecting Tools](#inspecting-tools)
     - [OAuth](#oauth)
         - [Redirect URL](#redirect-url)
         - [GitHub MCP (special case)](#github-mcp-special-case)
+        - [Figma MCP (special case)](#figma-mcp-special-case)
     - [Custom Headers](#custom-headers)
     - [Secrets and Variable Expansion](#secrets-and-variable-expansion)
 - [Connecting Coding Agents](#connecting-coding-agents)
@@ -37,6 +39,7 @@
     - [Codex](#codex)
     - [GitHub Copilot](#github-copilot)
 - [How It Works](#how-it-works)
+- [Aknowledgements](#acknowledgements)
 
 ## The Problem
 
@@ -95,17 +98,17 @@ The router is published on npm as
 You do not need to install it — just run it with `npx`:
 
 ```bash
-npx mcp-compress-router add github -- npx -y @modelcontextprotocol/server-github
+npx mcp-compress-router@latest add playwright -- npx -y @playwright/mcp
 ```
 
-This registers a downstream MCP server named `github` and writes it to
-your [config file](#config-file-location). Repeat for every MCP server you
-want to compress.
+This registers a downstream MCP server named `playwright` and writes it
+to your [config file](#config-file-location). Repeat for every MCP server
+you want to compress.
 
 Then point your [coding agent](#connecting-coding-agents) at the router:
 
 ```bash
-npx mcp-compress-router
+npx mcp-compress-router@latest
 ```
 
 When started without a subcommand, the router runs the MCP server over
@@ -163,11 +166,11 @@ far better than a bare name.
 **stdio server** (a local process):
 
 ```bash
-npx mcp-compress-router add github --description "GitHub API tools" \
+npx mcp-compress-router@latest add github --description "GitHub API tools" \
   -- npx -y @modelcontextprotocol/server-github
 
 # With environment variables
-npx mcp-compress-router add github -e GITHUB_PERSONAL_TOKEN=ghp_xxx \
+npx mcp-compress-router@latest add github -e GITHUB_PERSONAL_TOKEN=ghp_xxx \
   --description "GitHub API tools" \
   -- npx -y @modelcontextprotocol/server-github
 ```
@@ -176,10 +179,10 @@ npx mcp-compress-router add github -e GITHUB_PERSONAL_TOKEN=ghp_xxx \
 URL):
 
 ```bash
-npx mcp-compress-router add my-http https://localhost:3100/mcp
+npx mcp-compress-router@latest add my-http https://localhost:3100/mcp
 
 # With a custom header
-npx mcp-compress-router add my-http \
+npx mcp-compress-router@latest add my-http \
   --header "Authorization: Bearer mytoken" \
   https://localhost:3100/mcp
 ```
@@ -212,9 +215,9 @@ supported. CLI commands write plain `.json`; hand-edited files may use
 Other management commands:
 
 ```bash
-npx mcp-compress-router list            # list all servers + auth status
-npx mcp-compress-router get my-http     # show one server's config
-npx mcp-compress-router remove my-http  # remove a server
+npx mcp-compress-router@latest list            # list all servers + auth status
+npx mcp-compress-router@latest get my-http     # show one server's config
+npx mcp-compress-router@latest remove my-http  # remove a server
 ```
 
 ### Per-Server Enable/Disable
@@ -229,14 +232,14 @@ enabled, keeping `mcp.json` clean and fully backward compatible.
 Toggle it from the CLI without touching the rest of the config:
 
 ```bash
-npx mcp-compress-router disable github   # writes "enabled": false
-npx mcp-compress-router enable github    # removes the field
+npx mcp-compress-router@latest disable github   # writes "enabled": false
+npx mcp-compress-router@latest enable github    # removes the field
 ```
 
 You can also set it at creation time:
 
 ```bash
-npx mcp-compress-router add archive --disabled -- npx -y server-archive
+npx mcp-compress-router@latest add archive --disabled -- npx -y server-archive
 ```
 
 ### Per-Server Tool Selection
@@ -273,12 +276,67 @@ hard error at startup. Set filters at creation time with repeatable
 flags:
 
 ```bash
-npx mcp-compress-router add github \
+npx mcp-compress-router@latest add github \
   --allowed-tools list_issues \
   --allowed-tools get_pull_request \
   -- npx -y server-github
 ```
 
+### Compression Levels
+
+Each server's tools are listed in the `get_tool_schema` description at a
+configurable `compressionLevel`. The level trades catalog compactness
+for routing detail: lower levels give the LLM more information up front
+(fewer `get_tool_schema` round-trips), while higher levels minimize the
+per-request token overhead. The full JSON parameter schema is always
+available via `get_tool_schema` regardless of the level — only the
+catalog *listing* changes.
+
+Four levels are supported, from most to least compact:
+
+| Level | Tool listing format | Description shown? |
+| --- | --- | --- |
+| `max` | `toolA, toolB, toolC` (comma-separated, single line) | No |
+| `high` (default) | `toolName(arg1, arg2)` (one per line) | No |
+| `medium` | `toolName(arg1, arg2): first sentence...` (one per line) | Snippet |
+| `low` | `<tool>toolName(arg1, arg2): full description</tool>` (one per line) | Full |
+
+Argument names are extracted from each tool's `inputSchema.properties`
+keys in definition order. When a tool has no description, the `medium`
+and `low` listings omit the description portion and show just the
+signature.
+
+Omitting `compressionLevel` (the default) is equivalent to `high`. Set
+it per server in `mcp.json`:
+
+```jsonc
+"github": {
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "compressionLevel": "medium"
+}
+```
+
+Or set it at creation time with the `--compression-level` flag:
+
+```bash
+npx mcp-compress-router@latest add github \
+  --compression-level medium \
+  -- npx -y @modelcontextprotocol/server-github
+```
+
+A good rule of thumb:
+
+- Use `max` for servers whose tool names are self-describing and you
+  want the smallest possible catalog.
+- Use `high` (the default) for most servers — argument names are
+  usually enough for the LLM to pick the right tool.
+- Use `medium` when tool names alone are ambiguous and a one-line
+  hint helps disambiguate.
+- Use `low` sparingly — only when full descriptions must be visible
+  without a `get_tool_schema` call, since it costs the most tokens.
+
 ### Inspecting Tools
 
 To see exactly which tools a server advertises — and which are
@@ -286,7 +344,7 @@ To see exactly which tools a server advertises — and which are
 it live without starting the full router:
 
 ```bash
-npx mcp-compress-router tools github
+npx mcp-compress-router@latest tools github
 ```
 
 This works regardless of the server's `enabled` state (inspecting a
@@ -303,7 +361,7 @@ flow automatically if OAuth is advertised. You can also trigger it
 manually:
 
 ```bash
-npx mcp-compress-router login my-http
+npx mcp-compress-router@latest login my-http
 ```
 
 This opens your browser to complete the authorization-code flow. Tokens
@@ -353,7 +411,7 @@ 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
+npx mcp-compress-router@latest login my-http --port 8765
 ```
 
 This binds the callback server to `8765`, so the redirect URI becomes
@@ -373,7 +431,7 @@ flag each time:
 `--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)
+#### GitHub MCP with OAuth (special case)
 
 The official GitHub MCP server at
 `https://api.githubcopilot.com/mcp` advertises OAuth but does **not**
@@ -391,7 +449,7 @@ organizations you want the MCP to access.
 3. **Add the GitHub MCP server by URL.**
 
    ```bash
-   npx mcp-compress-router add github https://api.githubcopilot.com/mcp
+   npx mcp-compress-router@latest add github https://api.githubcopilot.com/mcp
    ```
 
 4. **Set `oauth` credentials in `mcp.json`.**
@@ -418,7 +476,7 @@ organizations you want the MCP to access.
 5. **Run the login command.**
 
    ```bash
-   npx mcp-compress-router login github
+   npx mcp-compress-router@latest login github
    ```
 
    Your browser opens to authorize. After you approve, tokens are stored
@@ -429,10 +487,93 @@ organizations you want the MCP to access.
 > login will succeed, and its client secret is generated under *General*
 > → *Generate a new client secret*.
 
+#### Figma MCP with OAuth (special case)
+
+The official Figma MCP server at `https://mcp.figma.com/mcp` does **not**
+support Dynamic Client Registration through the standard MCP flow.
+Instead you register an OAuth client via Figma's REST API using a
+Personal Access Token, then pass the resulting credentials through the
+`oauth` block. Figma also requires the redirect URI to use a **fixed
+port** — the port you register is reused on every `login`, so you must
+pin it with `oauth.callbackPort`.
+
+1. **Create a Figma Personal Access Token.**
+   Follow
+   <https://developers.figma.com/docs/rest-api/personal-access-tokens/>
+   to generate a PAT and export it as `FIGMA_PERSONAL_ACCESS_TOKEN`. It
+   is only used to register the MCP client in the next step.
+
+2. **Register the MCP client via Figma's API.**
+   The redirect URI must use `127.0.0.1` on a fixed port — **the port
+   matters**, it is reused on every `login`. This example uses `19876`:
+
+   ```bash
+   curl -X POST https://api.figma.com/v1/oauth/mcp/register \
+     -H "Content-Type: application/json" \
+     -H "X-Figma-Token: $FIGMA_PERSONAL_ACCESS_TOKEN" \
+     -d '{
+       "client_name": "Claude Code (figma)",
+       "redirect_uris": ["http://127.0.0.1:19876/mcp-compress-router/oauth-callback"],
+       "grant_types": ["authorization_code", "refresh_token"],
+       "response_types": ["code"],
+       "token_endpoint_auth_method": "none"
+     }'
+   ```
+
+   Save the `client_id` and `client_secret` from the response (also note
+   the `scope` is `mcp:connect`):
+
+   ```json
+   {
+     "client_id": "CLIENTID",
+     "client_secret": "CLIENTSECRET",
+     "client_name": "Claude Code (figma)",
+     "redirect_uris": ["http://127.0.0.1:19876/mcp-compress-router/oauth-callback"],
+     "token_endpoint_auth_method": "none",
+     "scope": "mcp:connect"
+   }
+   ```
+
+3. **Add the Figma MCP server by URL.**
+
+   ```bash
+   npx mcp-compress-router@latest add --transport http figma https://mcp.figma.com/mcp
+   ```
+
+4. **Set `oauth` credentials in `mcp.json`.**
+   Put the client ID and secret from step 2 in the server entry, using
+   the `mcp:connect` scope and the **same fixed port** you registered as
+   `callbackPort`:
+
+   ```jsonc
+   "figma": {
+     "type": "http",
+     "url": "https://mcp.figma.com/mcp",
+     "oauth": {
+       "clientId": "${FIGMA_CLIENT_ID}",
+       "clientSecret": "${FIGMA_CLIENT_SECRET}",
+       "scope": "mcp:connect",
+       "callbackPort": 19876
+     }
+   }
+   ```
+
+   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@latest login figma
+   ```
+
+   Your browser opens to authorize. After you approve, tokens are stored
+   in `credentials.json` and the router can call Figma MCP tools.
+
 Other OAuth commands:
 
 ```bash
-npx mcp-compress-router logout my-http  # remove stored credentials
+npx mcp-compress-router@latest logout my-http  # remove stored credentials
 ```
 
 For headless or CI environments, override the browser with the
@@ -441,7 +582,7 @@ URL is appended as a single final argument (no shell):
 
 ```bash
 MCP_COMPRESS_ROUTER_BROWSER="node /path/to/headless-browser.js" \
-  npx mcp-compress-router login my-http
+  npx mcp-compress-router@latest login my-http
 ```
 
 The default login timeout is 120 seconds; override it with
@@ -454,7 +595,7 @@ token instead of OAuth, use the `headers` field. You can set it via the
 CLI or directly in `mcp.json`:
 
 ```bash
-npx mcp-compress-router add my-http \
+npx mcp-compress-router@latest add my-http \
   --header "Authorization: Bearer mytoken" \
   --header "X-Custom: value" \
   https://example.com/mcp
@@ -500,77 +641,43 @@ Shell environment variables always take precedence over `.env` values.
 
 Once your downstream servers are configured, connect your agent to the
 router the same way you would connect any other MCP server — by
-pointing it at `npx mcp-compress-router`. The examples below assume the
+pointing it at `npx mcp-compress-router@latest`. The examples below assume the
 default [config location](#config-file-location); pass `-c <path>` if
 you use a custom one.
 
 ### Opencode
 
-Add the router to your `opencode.json` under `mcp`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "compress-router": {
-      "type": "local",
-      "command": ["npx", "-y", "mcp-compress-router"],
-      "enabled": true
-    }
-  }
-}
+```sh
+opencode mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
 ```
 
 ### Claude Code
 
-Add this to a project-level `.mcp.json` in your workspace root, or to
-your user-level config (applies to every project):
-
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-- **Linux:** `~/.config/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "compress-router": {
-      "command": "npx",
-      "args": ["-y", "mcp-compress-router"]
-    }
-  }
-}
+```sh
+claude mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
 ```
 
 ### Codex
 
-Add a `[mcp_servers.compress-router]` table to your Codex config (note
-the snake_case key). The config path is `~/.codex/config.toml` on
-macOS/Linux, or `%USERPROFILE%\.codex\config.toml` on Windows; you can
-also scope it to a single project via `.codex/config.toml` in trusted
-projects.
-
-```toml
-[mcp_servers.compress-router]
-command = "npx"
-args = ["-y", "mcp-compress-router"]
-enabled = true
+```sh
+codex mcp add mcp-compress-router -- npx -y mcp-compress-router@latest
 ```
 
-### GitHub Copilot
+### GitHub Copilot (VS Code)
 
 Add this to `.vscode/mcp.json` in your workspace (project-level, applies
 only to that workspace), or to your **user-level** MCP settings which
-apply across every workspace: open the Command Palette →
-`Preferences: Open User Settings (JSON)` and add the same `servers`
+apply across every workspace: open the Command Palette (`Cmd+Shift+P`) →
+`MCP: Open User Configuration` and add the same `servers`
 block under the `mcp` key. Project-level and user-level entries are
 merged, with project-level taking precedence.
 
 ```json
 {
   "servers": {
-    "compress-router": {
+    "mcp-compress-router": {
       "command": "npx",
-      "args": ["-y", "mcp-compress-router"]
+      "args": ["-y", "mcp-compress-router@latest"]
     }
   }
 }
@@ -600,3 +707,11 @@ token catalog, regardless of how many downstream servers you have.
 
 For the full configuration and environment variable reference, see
 [configuration.md](docs/configuration.md).
+
+## Acknowledgements
+
+- [mcp2cli](https://github.com/knowsuchagency/mcp2cli) — a very similar
+  idea of how MCP can be compressed, but to a CLI.
+- [mcp-compressor](https://github.com/atlassian-labs/mcp-compressor) —
+  also a very similar idea; the "two tools" approach was borrowed from
+  this project, though it only compresses a single MCP server.

package/build/cli/add-command.js

@@ -1,5 +1,5 @@
 import { ensureConfigDir, readConfigFile, writeConfigFile, readCredentials, writeCredentials, } from './config-io.js';
-import { validateGlobPattern } from '../utils/index.js';
+import { isCompressionLevel, validateGlobPattern, VALID_COMPRESSION_LEVELS, } from '../utils/index.js';
 /**
  * Validates every glob pattern in an optional tool list, throwing with
  * the field name and offending pattern on the first invalid entry.
@@ -61,6 +61,9 @@ function buildServerEntry(opts) {
     if (opts.disabledTools && opts.disabledTools.length > 0) {
         entry.disabledTools = opts.disabledTools;
     }
+    if (opts.compressionLevel) {
+        entry.compressionLevel = opts.compressionLevel;
+    }
     // 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) {
@@ -92,6 +95,10 @@ export async function handleAdd(configPath, opts) {
     }
     validateToolListPatterns('allowedTools', opts.allowedTools);
     validateToolListPatterns('disabledTools', opts.disabledTools);
+    if (opts.compressionLevel !== undefined && !isCompressionLevel(opts.compressionLevel)) {
+        throw new Error(`Invalid "--compression-level" value "${opts.compressionLevel}": ` +
+            `must be one of ${VALID_COMPRESSION_LEVELS.join(', ')}.`);
+    }
     await ensureConfigDir(configPath);
     const servers = await readConfigFile(configPath);
     if (opts.name in servers) {

package/build/cli/get-command.js

@@ -24,6 +24,12 @@ export async function handleGet(configPath, name) {
     if (entry.description) {
         lines.push(`Description: ${entry.description}`);
     }
+    if (entry.compressionLevel) {
+        lines.push(`compressionLevel: ${entry.compressionLevel}`);
+    }
+    else {
+        lines.push('compressionLevel: high (default)');
+    }
     if (entry.command) {
         lines.push(`Command: ${entry.command}`);
     }

package/build/cli/list-command.js

@@ -55,6 +55,16 @@ function summarizeTools(server) {
     }
     return 'all';
 }
+/**
+ * Renders the `Compression` cell: the explicit `compressionLevel`, or
+ * `high` when the field is absent (the default per PRD §"Solution").
+ *
+ * @param server - Typed downstream server config.
+ * @returns The resolved compression level string.
+ */
+function summarizeCompression(server) {
+    return server.compressionLevel ?? 'high';
+}
 /**
  * Renders the list header and server rows as a fixed-width table. The
  * final (Auth) column is left unpadded so lines never carry trailing
@@ -74,13 +84,14 @@ function formatList(configPath, rows) {
     const commandWidth = Math.max('CommandOrUrl'.length, ...rows.map((r) => r.commandOrUrl.length));
     const enabledWidth = Math.max('Enabled'.length, ...rows.map((r) => r.enabled.length));
     const toolsWidth = Math.max('Tools'.length, ...rows.map((r) => r.tools.length));
+    const compressionWidth = Math.max('Compression'.length, ...rows.map((r) => r.compression.length));
     const pad = (val, width) => val.padEnd(width);
-    const columns = (name, type, command, enabled, tools, auth) => `${pad(name, nameWidth)}  ${pad(type, typeWidth)}  ${pad(command, commandWidth)}  ${pad(enabled, enabledWidth)}  ${pad(tools, toolsWidth)}  ${auth}`;
+    const columns = (name, type, command, enabled, tools, compression, auth) => `${pad(name, nameWidth)}  ${pad(type, typeWidth)}  ${pad(command, commandWidth)}  ${pad(enabled, enabledWidth)}  ${pad(tools, toolsWidth)}  ${pad(compression, compressionWidth)}  ${auth}`;
     return [
         header,
         '',
-        columns('Name', 'Type', 'CommandOrUrl', 'Enabled', 'Tools', 'Auth'),
-        ...rows.map((r) => columns(r.name, r.type, r.commandOrUrl, r.enabled, r.tools, r.auth)),
+        columns('Name', 'Type', 'CommandOrUrl', 'Enabled', 'Tools', 'Compression', 'Auth'),
+        ...rows.map((r) => columns(r.name, r.type, r.commandOrUrl, r.enabled, r.tools, r.compression, r.auth)),
     ].join('\n');
 }
 /**
@@ -107,6 +118,7 @@ export async function handleList(configPath) {
             enabled: entry.enabled,
             allowedTools: entry.allowedTools,
             disabledTools: entry.disabledTools,
+            compressionLevel: entry.compressionLevel,
         };
         return {
             name,
@@ -114,6 +126,7 @@ export async function handleList(configPath) {
             commandOrUrl: buildCommandOrUrl(typed),
             enabled: summarizeEnabled(typed),
             tools: summarizeTools(typed),
+            compression: summarizeCompression(typed),
             auth: computeAuthStatus(typed, credentials[name]),
         };
     });

package/build/cli/register-commands.js

@@ -84,6 +84,7 @@ function buildAddOptions(name, commandOrUrl, rest, options) {
         allowedTools: options.allowedTools && options.allowedTools.length > 0 ? options.allowedTools : undefined,
         disabledTools: options.disabledTools && options.disabledTools.length > 0 ? options.disabledTools : undefined,
         port: options.port,
+        compressionLevel: options.compressionLevel || undefined,
     };
 }
 function registerAddCommand(program) {
@@ -99,6 +100,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('--compression-level <level>', 'tool listing compression level (max, high, medium, low; default high)')
         .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);

package/build/cli/router-runner.js

@@ -38,7 +38,9 @@ async function startRouterServer(catalog, clients, logger) {
     const invokeFn = (server, tool, args) => invokeDownstreamTool(clients, server, tool, args, logger);
     router.registerTool('invoke_tool', {
         title: 'Invoke Tool',
-        description: 'Invoke a specific tool on a connected MCP server. First use get_tool_schema to retrieve the required parameters.',
+        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();
@@ -78,12 +80,14 @@ export async function runRouter(configPath, verbose) {
         })),
     });
     const selectionByServer = new Map();
+    const compressionLevelByServer = new Map();
     for (const server of servers) {
         selectionByServer.set(server.name, {
             allowedTools: server.allowedTools,
             disabledTools: server.disabledTools,
         });
+        compressionLevelByServer.set(server.name, server.compressionLevel);
     }
-    const catalog = buildCatalog(discovered, selectionByServer, logger);
+    const catalog = buildCatalog(discovered, selectionByServer, logger, compressionLevelByServer);
     await startRouterServer(catalog, clients, logger);
 }

package/build/services/catalog.js

@@ -14,9 +14,12 @@ import { filterTools } from '../utils/index.js';
  *   server name is absent from the map, all its tools are exposed.
  * @param logger - Optional logger for unmatched-pattern warnings. When
  *   omitted, no warnings are emitted (backward compatible).
+ * @param compressionLevelByServer - Optional per-server compression level
+ *   map. When a server name is absent or the entry is `undefined`, the
+ *   level resolves to `high` (the default).
  * @returns An immutable ToolCatalog containing only exposed tools.
  */
-export function buildCatalog(discovered, selectionByServer = new Map(), logger) {
+export function buildCatalog(discovered, selectionByServer = new Map(), logger, compressionLevelByServer = new Map()) {
     const toolMap = new Map();
     const filteredToolNames = new Set();
     const servers = discovered.map((ds) => {
@@ -37,6 +40,7 @@ export function buildCatalog(discovered, selectionByServer = new Map(), logger)
             name: ds.name,
             description: ds.description,
             tools: exposed,
+            compressionLevel: compressionLevelByServer.get(ds.name) ?? 'high',
         };
     });
     return { servers, toolMap, filteredToolNames };

package/build/services/config.js

@@ -1,7 +1,7 @@
 import * as path from 'node:path';
 import * as os from 'node:os';
 import * as fs from 'node:fs/promises';
-import { expandEnvField, parseJsonc, validateGlobPattern } from '../utils/index.js';
+import { expandEnvField, isCompressionLevel, parseJsonc, validateGlobPattern, VALID_COMPRESSION_LEVELS, } from '../utils/index.js';
 /** Recognized MCP transport types. */
 const VALID_TYPES = new Set(['stdio', 'http', 'streamable-http']);
 /** Per-application directory name used inside the user data folder. */
@@ -243,6 +243,28 @@ function validateEnabled(name, server) {
     }
     return server.enabled;
 }
+/**
+ * Validates the optional `compressionLevel` field on a server entry.
+ *
+ * Accepts `undefined` (absent — resolves to `high` downstream) and the
+ * four valid level strings. Any other value (invalid string, number,
+ * boolean, null) is a hard error at config load time, matching the
+ * existing fail-fast pattern for `type` and `enabled`.
+ *
+ * @param name - Server name (for error messages).
+ * @param value - The raw `compressionLevel` value from the server entry.
+ * @returns The validated level, or undefined when the field is absent.
+ * @throws If the value is present but not one of max, high, medium, low.
+ */
+function validateCompressionLevel(name, value) {
+    if (value === undefined)
+        return undefined;
+    if (!isCompressionLevel(value)) {
+        throw new Error(`Server "${name}" has invalid "compressionLevel" value "${String(value)}". ` +
+            `Must be one of: ${VALID_COMPRESSION_LEVELS.join(', ')}`);
+    }
+    return value;
+}
 /**
  * Validates an optional tool-name glob list (`allowedTools` or
  * `disabledTools`).
@@ -310,7 +332,18 @@ function parseServerEntry(name, entry, names) {
     const enabled = validateEnabled(name, server);
     const allowedTools = validateToolList(name, 'allowedTools', server.allowedTools);
     const disabledTools = validateToolList(name, 'disabledTools', server.disabledTools);
-    return { name, type, ...fields, description, oauth, enabled, allowedTools, disabledTools };
+    const compressionLevel = validateCompressionLevel(name, server.compressionLevel);
+    return {
+        name,
+        type,
+        ...fields,
+        description,
+        oauth,
+        enabled,
+        allowedTools,
+        disabledTools,
+        compressionLevel,
+    };
 }
 /**
  * Loads and validates the MCP configuration file.

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

@@ -55,5 +55,7 @@ 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' + compact;
+    return ('Get the JSON schema for one or more tools from a connected MCP server. ' +
+        'You MUST call this for a tool before you can invoke it with invoke_tool.\n\n' +
+        compact);
 }

package/build/utils/argument-names.js

@@ -0,0 +1,21 @@
+/**
+ * Extracts ordered argument names from a tool's `inputSchema`.
+ *
+ * Reads `inputSchema.properties` keys in definition order. Returns an
+ * empty array when the schema is undefined, has no `properties` key,
+ * or has a non-object `properties` value (including null). No failure
+ * modes — malformed input always yields an empty array.
+ *
+ * @param inputSchema - The JSON Schema object from a tool descriptor.
+ * @returns Ordered argument names (possibly empty).
+ */
+export function extractArgumentNames(inputSchema) {
+    if (inputSchema === undefined) {
+        return [];
+    }
+    const properties = inputSchema.properties;
+    if (properties === undefined || properties === null || typeof properties !== 'object') {
+        return [];
+    }
+    return Object.keys(properties);
+}

package/build/utils/compression-level.js

@@ -0,0 +1,24 @@
+/**
+ * Valid `compressionLevel` values, in the order used for error messages
+ * and documentation.
+ */
+export const VALID_COMPRESSION_LEVELS = [
+    'max',
+    'high',
+    'medium',
+    'low',
+];
+/**
+ * Type guard confirming a value is one of the four valid
+ * {@link CompressionLevel} strings (`max`, `high`, `medium`, `low`).
+ *
+ * Used by both the Config Loader (startup validation) and the `add` CLI
+ * command (flag validation) so both check against a single source of
+ * truth.
+ *
+ * @param value - Any value read from config or a CLI flag.
+ * @returns True when `value` is a string and one of the four valid levels.
+ */
+export function isCompressionLevel(value) {
+    return (typeof value === 'string' && VALID_COMPRESSION_LEVELS.includes(value));
+}

package/build/utils/description-truncator.js

@@ -0,0 +1,29 @@
+/**
+ * Truncates a tool description to the first sentence (text up to the
+ * first `.`), capped at 10 words. When the first sentence exceeds 10
+ * words, only the first 10 are kept and `...` (three ASCII dots) is
+ * appended. When the description is absent or empty, returns an empty
+ * string. No failure modes — malformed input always yields an empty
+ * string.
+ *
+ * Used by the catalog text renderer at the `medium` compression level.
+ * This is distinct from the character-based `truncateDescription` in
+ * `src/cli/tools-command.ts`, which serves the CLI table layout.
+ *
+ * @param description - The raw tool description, or undefined.
+ * @returns The truncated first-sentence snippet (possibly empty).
+ */
+export function truncateToFirstSentence(description) {
+    if (description === undefined || description.length === 0) {
+        return '';
+    }
+    const firstSentence = description.split('.')[0].trim();
+    const words = firstSentence.length === 0 ? [] : firstSentence.split(/\s+/);
+    if (words.length === 0) {
+        return '';
+    }
+    if (words.length <= 10) {
+        return words.join(' ');
+    }
+    return `${words.slice(0, 10).join(' ')}...`;
+}

package/build/utils/index.js

@@ -6,5 +6,6 @@ export { validateGlobPattern } from './validate-glob.js';
 export { expandEnvField } from './expand-env.js';
 export { Logger } from './logger.js';
 export { parseJsonc } from './parse-jsonc.js';
+export { VALID_COMPRESSION_LEVELS, isCompressionLevel } from './compression-level.js';
 /** @public */
 export { openBrowser } from './open-browser.js';

package/build/utils/text-format.js

@@ -1,33 +1,72 @@
+import { extractArgumentNames } from './argument-names.js';
+import { truncateToFirstSentence } from './description-truncator.js';
 /**
  * Renders the compact catalog as Markdown text suitable for inclusion
  * in the `get_tool_schema` tool description.
  *
- * Format:
- *   ## {server name}
- *   {description (optional)}
+ * Each server's tools are rendered according to that server's
+ * `compressionLevel`:
  *
- *   Available tools:
- *   {tool1}, {tool2}, ...
+ * - `max` — tool names only, comma-separated on a single line.
+ * - `high` (default) — `toolName(arg1, arg2)`, one tool per line.
+ * - `medium` — `toolName(arg1, arg2): first sentence...`, one tool per
+ *   line (the snippet is omitted when the description is absent).
+ * - `low` — `<tool>toolName(arg1, arg2): full description</tool>`,
+ *   one tool per line (description omitted when absent).
  *
- * When a server has no tools, only the header (and optional
- * description) is rendered.
+ * Argument names are extracted from each tool's `inputSchema.properties`
+ * keys in definition order. 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 blocks = [];
-    for (const server of servers) {
-        const lines = [`## ${server.name}`];
-        if (server.description) {
-            lines.push(server.description);
+    return servers.map((server) => renderServerBlock(server)).join('\n\n');
+}
+/**
+ * Renders a single server section: header, optional description, and
+ * the tool listing formatted for that server's compression level.
+ *
+ * @param server - The catalog server to render.
+ * @returns The server block text.
+ */
+function renderServerBlock(server) {
+    const lines = [`## ${server.name}`];
+    if (server.description) {
+        lines.push(server.description);
+    }
+    if (server.tools.length > 0) {
+        lines.push('', 'Available tools:');
+        if (server.compressionLevel === 'max') {
+            lines.push(server.tools.map((tool) => tool.name).join(', '));
         }
-        if (server.tools.length > 0) {
-            lines.push('');
-            lines.push('Available tools:');
-            lines.push(server.tools.map((t) => t.name).join(', '));
+        else {
+            for (const tool of server.tools) {
+                lines.push(renderToolLine(tool, server.compressionLevel));
+            }
         }
-        blocks.push(lines.join('\n'));
     }
-    return blocks.join('\n\n');
+    return lines.join('\n');
+}
+/**
+ * Renders a single tool line at the `high`, `medium`, or `low` level.
+ *
+ * @param tool - The tool descriptor.
+ * @param level - The compression level (never `max`).
+ * @returns The formatted tool line.
+ */
+function renderToolLine(tool, level) {
+    const args = extractArgumentNames(tool.inputSchema);
+    const signature = `${tool.name}(${args.join(', ')})`;
+    if (level === 'low') {
+        return tool.description
+            ? `<tool>${signature}: ${tool.description}</tool>`
+            : `<tool>${signature}</tool>`;
+    }
+    if (level === 'medium') {
+        const snippet = truncateToFirstSentence(tool.description);
+        return snippet ? `${signature}: ${snippet}` : signature;
+    }
+    return signature;
 }

package/package.json

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