@atlassian/mcp-compressor 0.0.2

package/README.md

@@ -0,0 +1,393 @@
+# @atlassian/mcp-compressor (TypeScript)
+
+A TypeScript MCP proxy that wraps one or more MCP servers and reduces the token footprint exposed to LLMs.
+
+## How it works
+
+mcp-compressor connects to upstream MCP servers (via stdio, HTTP, or SSE) and replaces their full tool catalogs with a compressed interface. Instead of exposing every tool individually, it provides:
+
+- **`get_tool_schema(tool_name)`** — returns the full schema for a specific tool on demand
+- **`invoke_tool(tool_name, tool_input)`** — calls an upstream tool
+- **`list_tools()`** — lists available tool names (only at `max` compression)
+
+This dramatically reduces the token cost of tool descriptions in LLM context windows while preserving full tool functionality.
+
+### Compression levels
+
+| Level | What the LLM sees |
+|---|---|
+| `low` | Tool name, parameters, and full description |
+| `medium` (default) | Tool name, parameters, and first sentence of description |
+| `high` | Tool name and parameters only |
+| `max` | Tool names only (requires `list_tools` call to discover) |
+
+### Three modes
+
+| Mode | Tools exposed | How the LLM invokes tools |
+|---|---|---|
+| **Compressed** (default) | `get_tool_schema` + `invoke_tool` | Via MCP tool calls |
+| **CLI** | Per-server `_help` tools | Via bash CLI commands (bridge + generated scripts) |
+| **Bash** | Per-server `_help` tools + `bash` tool | Via a sandboxed [just-bash](https://www.npmjs.com/package/just-bash) shell |
+
+## Installation
+
+```bash
+npm install @atlassian/mcp-compressor
+
+# Optional: for bash mode
+npm install just-bash
+```
+
+## STDIO MCP proxy
+
+The simplest way to use mcp-compressor is as a CLI that wraps another MCP server and exposes a compressed proxy over stdio.
+
+### Compressed mode (default)
+
+```bash
+# Wrap a remote MCP server
+bun cli -- https://mcp.atlassian.com/v1/mcp
+
+# Wrap a local stdio server
+bun cli --server-name filesystem -- npx -y @modelcontextprotocol/server-filesystem .
+
+# With options
+bun cli -c high --server-name atlassian --toonify -- https://mcp.atlassian.com/v1/mcp
+
+# Multi-server via MCP config JSON
+bun cli -- '{"mcpServers":{"jira":{"url":"https://jira-mcp.example.com"},"confluence":{"command":"node","args":["confluence-server.js"]}}}'
+```
+
+### CLI mode
+
+CLI mode generates shell scripts for each backend server so the LLM (or user) can invoke tools directly from bash. The MCP proxy exposes per-server help tools that describe the available commands.
+
+```bash
+# Start CLI mode
+bun cli --cli-mode --server-name atlassian -- https://mcp.atlassian.com/v1/mcp
+
+# In another terminal, use the generated CLI:
+atlassian --help
+atlassian search-confluence --query oauth
+atlassian get-jira-issue --issue-url https://jira.example.com/browse/PROJ-123
+```
+
+TOON output formatting is automatically enabled in CLI mode.
+
+### Bash mode
+
+Bash mode registers all backend tools as custom commands in a sandboxed just-bash shell, then exposes a single `bash` MCP tool plus per-server help tools. The LLM can run MCP tools alongside standard Unix utilities, including pipes and composition.
+
+```bash
+bun cli --just-bash --server-name atlassian -- https://mcp.atlassian.com/v1/mcp
+```
+
+The LLM then sees:
+- `bash` — execute commands in the sandboxed shell
+- `atlassian_help` — lists available atlassian subcommands
+
+Example commands the LLM can run via the bash tool:
+```bash
+atlassian search-issues --jql "project=PROJ" | jq '.issues[].key'
+atlassian get-page --page-id 12345 | grep "summary"
+echo "hello" | grep hello
+```
+
+### OAuth
+
+For remote OAuth backends, the CLI handles the authorization flow automatically — it opens the browser, completes the code exchange, and persists tokens for future sessions.
+
+```bash
+# Clear cached OAuth state
+bun cli clear-oauth https://mcp.atlassian.com/v1/mcp
+```
+
+## In-process usage (CompressorClient)
+
+For TypeScript applications and agent frameworks, `CompressorClient` provides a single unified interface for all modes — no subprocess needed.
+
+### Compressed mode
+
+```typescript
+import { CompressorClient } from '@atlassian/mcp-compressor';
+
+const client = new CompressorClient({
+  servers: {
+    jira: { url: 'https://jira-mcp.example.com' },
+    confluence: { command: 'node', args: ['confluence-server.js'] },
+  },
+  compressionLevel: 'medium',
+});
+
+await client.connect();
+const tools = await client.getTools();
+// → { jira_get_tool_schema, jira_invoke_tool, confluence_get_tool_schema, confluence_invoke_tool }
+
+// Use with any AI SDK-compatible framework
+const schema = await tools.jira_get_tool_schema.execute({ tool_name: 'search_issues' });
+const result = await tools.jira_invoke_tool.execute({
+  tool_name: 'search_issues',
+  tool_input: { query: 'oauth' },
+});
+
+await client.close();
+```
+
+### CLI mode
+
+```typescript
+const client = new CompressorClient({
+  servers: { atlassian: { url: 'https://mcp.atlassian.com/v1/mcp' } },
+  mode: 'cli',
+});
+
+await client.connect();
+const tools = await client.getTools();
+// → { atlassian_help }
+// Side effect: HTTP bridge started, shell script generated
+
+// client.scripts has info about generated scripts
+for (const script of client.scripts) {
+  console.log(`Run '${script.cliName} --help' for usage`);
+}
+
+await client.close();
+```
+
+### Bash mode
+
+```typescript
+const client = new CompressorClient({
+  servers: {
+    jira: { url: 'https://jira-mcp.example.com' },
+    confluence: { command: 'node', args: ['confluence-server.js'] },
+  },
+  mode: 'bash',
+});
+
+await client.connect();
+const tools = await client.getTools();
+// → { bash, jira_help, confluence_help }
+
+// Execute commands via the bash tool
+const result = await tools.bash.execute({ command: 'jira search-issues --query oauth' });
+
+// Access the Bash instance directly
+const execResult = await client.bash!.exec('jira search-issues --query test | jq .issues');
+
+await client.close();
+```
+
+### Bash mode with a pre-existing Bash instance
+
+If your application already has a `Bash` instance (e.g. with its own custom commands), you can inject it:
+
+```typescript
+import { Bash } from 'just-bash';
+
+const existingBash = new Bash({ customCommands: [myCustomCommand] });
+
+const client = new CompressorClient({
+  servers: { atlassian: { url: 'https://mcp.atlassian.com/v1/mcp' } },
+  mode: 'bash',
+  bash: { bash: existingBash },
+});
+
+await client.connect();
+const tools = await client.getTools();
+// → { bash, atlassian_help }
+// MCP commands are registered into existingBash via registerCommand()
+```
+
+### Server configuration formats
+
+`CompressorClient` accepts several formats for the `servers` option:
+
+```typescript
+// Named servers map (recommended for multi-server)
+new CompressorClient({
+  servers: {
+    jira: { url: 'https://jira-mcp.example.com' },
+    filesystem: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
+  },
+});
+
+// Single BackendConfig
+new CompressorClient({
+  servers: { type: 'http', url: 'https://mcp.example.com' },
+});
+
+// URL string
+new CompressorClient({
+  servers: 'https://mcp.example.com',
+});
+
+// MCP config JSON string
+new CompressorClient({
+  servers: '{"mcpServers":{"jira":{"url":"https://jira-mcp.example.com"}}}',
+});
+```
+
+### Escape hatches
+
+```typescript
+// Access individual runtimes
+const jiraRuntime = client.getRuntime('jira');
+await jiraRuntime.invokeTool('search_issues', { query: 'bug' });
+
+// List all server names
+console.log(client.serverNames); // ['jira', 'confluence']
+
+// Access all runtimes
+for (const runtime of client.runtimes) {
+  console.log(runtime.serverName, await runtime.listToolNames());
+}
+```
+
+## Rust-backed native client
+
+The Rust-core migration exposes a high-level native client for applications that want to start compressed MCP proxy sessions in-process, without spawning the `mcp-compressor` CLI as a stdio subprocess.
+
+```ts
+import { CompressorClient } from "@atlassian/mcp-compressor";
+
+const client = new CompressorClient({
+  servers: {
+    atlassian: {
+      url: "https://mcp.atlassian.com/v1/mcp",
+      headers: {
+        Authorization: `Basic ${token}`,
+      },
+    },
+  },
+  compressionLevel: "medium",
+  includeTools: ["getConfluencePage", "updateConfluencePage"],
+  toonify: true,
+});
+
+const proxy = await client.connect();
+try {
+  console.log(proxy.tools.map((tool) => tool.name));
+  const output = await proxy.invoke("getAccessibleAtlassianResources", {}, { server: "atlassian" });
+  console.log(output);
+} finally {
+  await client.close();
+}
+```
+
+The package root now exposes the Rust-backed `CompressorClient` as the primary SDK surface on the migration trunk.
+
+Just Bash mode exposes typed provider metadata so language hosts can register backend MCP tools as Just Bash commands while Rust owns compression/proxy routing:
+
+```ts
+const proxy = await new CompressorClient({ servers, mode: "bash" }).connect();
+try {
+  for (const provider of proxy.justBashProviders) {
+    console.log(provider.providerName, provider.helpToolName);
+    for (const command of provider.tools) {
+      console.log(command.commandName, command.backendToolName, command.invokeToolName);
+    }
+  }
+} finally {
+  proxy.close();
+}
+```
+
+Connected proxies can also write shell, Python, or TypeScript clients that call the live Rust proxy:
+
+```ts
+const proxy = await client.connect();
+try {
+  proxy.writeClient("cli", "./bin", { name: "atlassian" });
+  proxy.writeClient("python", "./generated-py", { name: "atlassian" });
+  proxy.writeClient("typescript", "./generated-ts", { name: "atlassian" });
+} finally {
+  proxy.close();
+}
+```
+
+## Development
+
+### Setup
+
+```bash
+cd typescript
+bun install
+```
+
+### Commands
+
+```bash
+bun run test          # run tests with vitest
+bun run check         # lint + format + typecheck + test
+bun run lint          # lint with oxlint
+bun run format        # format with oxfmt
+bun run format:check  # check formatting
+bun run build         # compile to dist/
+bun cli               # run the CLI directly from source
+```
+
+### Packaging smoke test
+
+Build and test the npm package from a clean temporary project:
+
+```bash
+bun install
+bun run build
+bun run build:native
+bun pm pack --filename /tmp/mcp-compressor-ts-package.tgz
+mkdir -p /tmp/mcp-compressor-ts-package-test
+cd /tmp/mcp-compressor-ts-package-test
+bun init -y
+bun add --registry https://registry.npmjs.org /tmp/mcp-compressor-ts-package.tgz
+bun --eval 'import { CompressorClient, compressToolListing } from "@atlassian/mcp-compressor"; console.log(typeof CompressorClient, compressToolListing("high", [{ name: "echo", inputSchema: { type: "object", properties: {} } }]))'
+```
+
+CI runs the same package smoke test and uploads the packed tarball as an artifact.
+
+### Toolchain
+
+| Tool | Purpose |
+|---|---|
+| [Bun](https://bun.sh/) | Package manager and runtime |
+| [TypeScript](https://www.typescriptlang.org/) | Type checking |
+| [Vitest](https://vitest.dev/) | Test runner |
+| [oxlint](https://oxc.rs/docs/guide/usage/linter) | Linter |
+| [oxfmt](https://oxc.rs/docs/guide/usage/formatter) | Formatter |
+| [Commander](https://github.com/tj/commander.js) | CLI argument parsing |
+
+## Publishing
+
+To publish from source, ensure you have active credentials for Artifactory, then run:
+
+```bash
+bun run build
+npm version <PUBLISH_VERSION> --no-git-tag-version
+npm publish
+```
+
+Published as `@atlassian/mcp-compressor` via Atlassian Artifactory → npmJS.
+
+```bash
+npm install @atlassian/mcp-compressor
+```
+
+### Sub-path exports
+
+`@atlassian/mcp-compressor` ships a small set of sub-path exports for consumers that only need the lightweight pieces. Importing from these sub-paths avoids loading `fastmcp`, the MCP SDK, and the rest of the runtime, which can add hundreds of ms of cold-import cost.
+
+| Sub-path | Contents | When to use |
+|---|---|---|
+| `@atlassian/mcp-compressor` | Full runtime (`CompressorRuntime`, `CompressorServer`, `BackendClient`, `FastMCP`, ...) | Building / hosting a compressor proxy. |
+| `@atlassian/mcp-compressor/bash` | The just-bash transform helpers | Bash-tool transformation. |
+| `@atlassian/mcp-compressor/config` | `interpolateString`, `interpolateRecord`, `parseServerConfigJson` | Pure config parsing / `${ENV}` interpolation in tooling. |
+| `@atlassian/mcp-compressor/errors` | `InvalidConfigurationError` and friends | Error type checks without the runtime. |
+| `@atlassian/mcp-compressor/types` | `BackendConfig`, `CompressionLevel`, `CommonProxyOptions`, ... | Type-only consumers. |
+
+```ts
+// heavy: pulls fastmcp + MCP SDK
+import { CompressorRuntime } from "@atlassian/mcp-compressor";
+
+// light: ~zero runtime deps
+import { interpolateString } from "@atlassian/mcp-compressor/config";
+```

package/dist/adapters.d.ts

@@ -0,0 +1,17 @@
+export interface ExecutableTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    execute(input?: Record<string, unknown>): Promise<string>;
+}
+export interface AISDKToolFactory<TTool = unknown> {
+    (options: {
+        description?: string;
+        inputSchema: Record<string, unknown>;
+        execute: (input: Record<string, unknown>) => Promise<string>;
+    }): TTool;
+}
+export declare function toAISDKTools<TTool = unknown>(tools: Record<string, ExecutableTool>, options?: {
+    tool?: AISDKToolFactory<TTool>;
+}): Record<string, TTool | Omit<ExecutableTool, "name">>;
+export declare function toMastraTools(tools: Record<string, ExecutableTool>): Record<string, Omit<ExecutableTool, "name">>;

package/dist/adapters.js

@@ -0,0 +1,23 @@
+export function toAISDKTools(tools, options = {}) {
+    const result = {};
+    for (const [name, executable] of Object.entries(tools)) {
+        const definition = {
+            description: executable.description,
+            inputSchema: executable.inputSchema,
+            execute: (input) => executable.execute(input),
+        };
+        result[name] = options.tool ? options.tool(definition) : definition;
+    }
+    return result;
+}
+export function toMastraTools(tools) {
+    const result = {};
+    for (const [name, executable] of Object.entries(tools)) {
+        result[name] = {
+            description: executable.description,
+            inputSchema: executable.inputSchema,
+            execute: (input = {}) => executable.execute(input),
+        };
+    }
+    return result;
+}

package/dist/cli.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import type { BackendConfig } from "./types.js";
+export interface ParsedCliArgs {
+    backend: BackendConfig | string;
+    justBash: boolean;
+    cliMode: boolean;
+    cliPort: string | undefined;
+    compressionLevel: "low" | "medium" | "high" | "max" | undefined;
+    cwd: string | undefined;
+    env: Record<string, string>;
+    excludeTools: string[];
+    headers: Record<string, string>;
+    includeTools: string[];
+    logLevel: string;
+    serverName: string | undefined;
+    timeout: number;
+    toonify: boolean;
+}
+export declare function parseCliArgs(argv: string[]): ParsedCliArgs;

package/dist/cli.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { VERSION } from "./version.js";
+function parseBackendArg(backendArgs) {
+    if (backendArgs.length === 0) {
+        throw new Error("Expected a backend URL, MCP config JSON string, or stdio command.");
+    }
+    if (backendArgs.length === 1) {
+        return backendArgs[0];
+    }
+    return {
+        type: "stdio",
+        command: backendArgs[0],
+        args: backendArgs.slice(1),
+    };
+}
+function collect(value, previous) {
+    previous.push(value);
+    return previous;
+}
+function collectKeyValue(value, previous) {
+    const eqIndex = value.indexOf("=");
+    if (eqIndex === -1) {
+        throw new Error(`Invalid key=value format: '${value}'. Expected KEY=VALUE.`);
+    }
+    const key = value.slice(0, eqIndex);
+    let val = value.slice(eqIndex + 1);
+    // Support ${VAR_NAME} environment variable expansion
+    val = val.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "");
+    previous[key] = val;
+    return previous;
+}
+function buildProgram(options = {}) {
+    const program = new Command()
+        .name("mcp-compressor")
+        .description("Run the MCP Compressor proxy server.\n\n" +
+        "Connects to an MCP server (via stdio, HTTP, or SSE) and wraps it\n" +
+        "with a compressed tool interface.")
+        .allowUnknownOption(false)
+        .allowExcessArguments(true)
+        .version(VERSION, "-V, --version")
+        .argument("[command_or_url...]", "The backend to wrap: either a remote MCP URL, a stdio command plus\n" +
+        "arguments, or an MCP config JSON string with one or more servers.\n" +
+        "Example stdio usage: bun run dist/cli.js -- uvx mcp-server-fetch")
+        .option("--cwd <dir>", "The working directory to use when running stdio MCP servers.")
+        .option("-e, --env <VAR=VALUE>", "Environment variables to set when running stdio MCP servers, in the\n" +
+        "form VAR_NAME=VALUE. Can be used multiple times. Supports environment\n" +
+        "variable expansion with ${VAR_NAME} syntax.", collectKeyValue, {})
+        .option("-H, --header <NAME=VALUE>", "Headers to use for remote (HTTP/SSE) MCP server connections, in the\n" +
+        "form Header-Name=Header-Value. Can be used multiple times. Supports\n" +
+        "environment variable expansion with ${VAR_NAME} syntax.", collectKeyValue, {})
+        .option("-t, --timeout <seconds>", "The timeout in seconds for connecting to the MCP server and making requests.", "10")
+        .addOption(new Option("-c, --compression-level <level>", "The level of compression to apply to the tool descriptions of the wrapped MCP server.")
+        .choices(["low", "medium", "high", "max"])
+        .default("medium"))
+        .option("-n, --server-name <name>", "Optional custom name to prefix the wrapper tool names (get_tool_schema,\n" +
+        "invoke_tool, list_tools). The name will be sanitized to conform to MCP\n" +
+        "tool name specifications (only A-Z, a-z, 0-9, _, -, .).")
+        .option("-l, --log-level <level>", "The logging level.", "error")
+        .option("--toonify", "Convert JSON tool responses to TOON format automatically.")
+        .option("--cli-mode", "Start in CLI mode: expose a single help MCP tool, start a local HTTP\n" +
+        "bridge, and generate a shell script for interacting with the wrapped\n" +
+        "server via CLI. --toonify is automatically enabled in this mode.")
+        .option("--cli-port <port>", "Port for the local CLI bridge HTTP server (default: random free port).")
+        .option("--just-bash", "Start in just-bash mode: expose a single 'bash' MCP tool powered by\n" +
+        "just-bash, with all backend server tools available as custom commands.\n" +
+        "Requires the 'just-bash' package to be installed. --toonify is\n" +
+        "automatically enabled in this mode.")
+        .option("--include-tool <tool>", "Wrapped server tool name to expose. Can be used multiple times.\n" +
+        "If omitted, all tools are included.", collect, [])
+        .option("--exclude-tool <tool>", "Wrapped server tool name to hide. Can be used multiple times.", collect, []);
+    if (options.exitOverride) {
+        program.exitOverride();
+    }
+    return program;
+}
+function parseCliArgsWithOptions(argv, parseOptions = {}) {
+    const program = buildProgram(parseOptions);
+    program.parse(argv, { from: "user" });
+    const parsedOptions = program.opts();
+    const backend = parseBackendArg(program.args);
+    const justBash = parsedOptions.justBash ?? false;
+    const cliMode = parsedOptions.cliMode ?? false;
+    const toonify = (parsedOptions.toonify ?? false) || cliMode || justBash;
+    return {
+        backend,
+        justBash,
+        cliMode,
+        cliPort: parsedOptions.cliPort,
+        compressionLevel: parsedOptions.compressionLevel,
+        cwd: parsedOptions.cwd,
+        env: parsedOptions.env ?? {},
+        excludeTools: parsedOptions.excludeTool ?? [],
+        headers: parsedOptions.header ?? {},
+        includeTools: parsedOptions.includeTool ?? [],
+        logLevel: parsedOptions.logLevel,
+        serverName: parsedOptions.serverName,
+        timeout: Number.parseFloat(parsedOptions.timeout),
+        toonify,
+    };
+}
+export function parseCliArgs(argv) {
+    return parseCliArgsWithOptions(argv, { exitOverride: true });
+}
+function parseClearOAuthArgs(args) {
+    if (args[0] !== "clear-oauth") {
+        return null;
+    }
+    const clearProgram = new Command()
+        .name("mcp-compressor clear-oauth")
+        .exitOverride()
+        .allowExcessArguments(false)
+        .argument("[backend]", "backend URL or MCP config JSON string")
+        .option("--all", "also remove the encryption key");
+    clearProgram.parse(args.slice(1), { from: "user" });
+    const target = clearProgram.args[0];
+    const options = clearProgram.opts();
+    return { ...(target ? { target } : {}), all: options.all ?? false };
+}
+function candidateCoreBinaries() {
+    const candidates = [];
+    if (process.env.MCP_COMPRESSOR_BINARY) {
+        candidates.push(process.env.MCP_COMPRESSOR_BINARY);
+    }
+    candidates.push("mcp-compressor");
+    const here = dirname(fileURLToPath(import.meta.url));
+    candidates.push(join(here, "..", "..", "target", "debug", process.platform === "win32" ? "mcp-compressor.exe" : "mcp-compressor"));
+    candidates.push(join(process.cwd(), "..", "target", "debug", process.platform === "win32" ? "mcp-compressor.exe" : "mcp-compressor"));
+    return candidates;
+}
+function translateArgsForRust(args) {
+    const clearOAuth = parseClearOAuthArgs(args);
+    if (clearOAuth) {
+        return clearOAuth.target ? ["clear-oauth", clearOAuth.target] : ["clear-oauth"];
+    }
+    return args;
+}
+async function runRustCoreCli(args) {
+    for (const binary of candidateCoreBinaries()) {
+        if (binary !== "mcp-compressor" && !existsSync(binary)) {
+            continue;
+        }
+        const child = spawn(binary, translateArgsForRust(args), { stdio: "inherit" });
+        return await new Promise((resolve, reject) => {
+            child.on("error", (error) => {
+                if (error.code === "ENOENT") {
+                    resolve(127);
+                    return;
+                }
+                reject(error);
+            });
+            child.on("exit", (code, signal) => {
+                if (signal) {
+                    resolve(1);
+                    return;
+                }
+                resolve(code ?? 0);
+            });
+        });
+    }
+    console.error("mcp-compressor binary was not found. Build it with `cargo build -p mcp-compressor-core` or set MCP_COMPRESSOR_BINARY.");
+    return 127;
+}
+async function main() {
+    const exitCode = await runRustCoreCli(process.argv.slice(2));
+    process.exitCode = exitCode;
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? (error.stack ?? error.message) : String(error));
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+import type { BackendConfig, JsonConfigServerEntry, MCPConfigShape } from "./types.js";
+/**
+ * Interpolate environment variables in a single string using ${VAR_NAME} or $VAR_NAME syntax.
+ * If a referenced variable is not set, the placeholder is left as-is (matching Python behaviour).
+ */
+export declare function interpolateString(value: string): string;
+export declare function interpolateRecord(record: Record<string, string> | undefined): Record<string, string> | undefined;
+/**
+ * Interpolate environment variables in all string values of an MCP config object or JSON string.
+ *
+ * Accepts either a parsed `MCPConfigShape` object or a raw JSON string and returns an interpolated
+ * copy with `${VAR_NAME}` and `$VAR_NAME` placeholders replaced by their environment variable
+ * values. Unset variables are left as-is.
+ *
+ * @example
+ * ```ts
+ * const config = interpolateMCPConfig({
+ *   mcpServers: {
+ *     myServer: { url: "https://example.com", headers: { Authorization: "Bearer $MY_TOKEN" } },
+ *   },
+ * });
+ * ```
+ */
+export declare function interpolateMCPConfig(config: MCPConfigShape | string): MCPConfigShape;
+/**
+ * Parse an MCP config JSON string containing one or more servers.
+ *
+ * Returns an array of `{ backend, serverName }` entries — one per server in `mcpServers` — or
+ * `null` if the input is not a JSON object string.  Throws {@link InvalidConfigurationError} for
+ * malformed JSON or an empty `mcpServers` map.
+ */
+export declare function parseServerConfigJson(input: string): Array<{
+    backend: BackendConfig;
+    serverName: string;
+}> | null;
+export declare function normalizeConfigServer(entry: JsonConfigServerEntry): BackendConfig;