@atlassian/mcp-compressor (TypeScript) (中文(简体) )

一个TypeScript MCP代理,可以包一个或多个MCP服务器并减少被LLMs所暴露的符号脚印.

如何运作

mcp-compressor连接了上游的MCP服务器(通过stdio,HTTP,或SSE),并用压缩接口来替换其完整的工具目录. 它没有单独揭露每个工具,而是提供:

• get_tool_schema(tool_name) ——按需返回特定工具的全部计划
• invoke_tool(tool_name, tool_input) - 称为上游工具
• list_tools() - 列出可用的工具名称( 仅在 max 压缩)

这极大地降低了LLM上下文窗口中工具描述的符号成本,同时保留了完整的工具功能.

压缩级别

三种模式

安装

npm install @atlassian/mcp-compressor

# Optional: for bash mode
npm install just-bash

STIO MCP 代理服务器

最简单的使用mcp-compressor的方法是作为CLI,它包装了另一个MCP服务器并暴露出一个压缩的代理于stdio上.

压缩模式( 默认)

# 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 模式

CLI模式为每个后端服务器生成 shell 脚本,因此LLM(或用户)可以直接从bash中引用工具. MCP代理披露了描述可用指令的每个服务器帮助工具.

# 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

工具输出以 CLI 模式返回 。 过 --toonify 选择使用 TOON 转换 JSON, CSV 和 YAML 的结果.

Bash 模式

Bash 模式将所有后端工具登记为自定义命令, 并装入沙盒中的正版贝壳, 然后曝光单个工具 bash MCP工具外加每个服务器的帮助工具. LLM可以与标准Unix公用事业(包括管道和成分)一起运行MCP工具.

bun cli --just-bash --server-name atlassian -- https://mcp.atlassian.com/v1/mcp

然后LLM看到:

• bash 在沙箱外壳中执行命令
• atlassian_help - 列出可用的地图集子命令

示例命令 LLM 可以通过 bash 工具运行 :

atlassian search-issues --jql "project=PROJ" | jq '.issues[].key'
atlassian get-page --page-id 12345 | grep "summary"
echo "hello" | grep hello

奥奥特

对于远程的OAuth后端,CLI会自动处理授权流——它打开了浏览器,完成了代码交换,并持续了未来会话的令牌.

# Clear cached OAuth state
bun cli clear-oauth https://mcp.atlassian.com/v1/mcp

进程内使用( CompressorClient)

对于 TypeScript 应用程序和代理框架, CompressorClient 为所有模式提供单一的统一接口——不需要子进程.

压缩模式

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 模式

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 模式

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 实例的巴什模式

如果您的申请已经存在 Bash 实例(例如,使用自己的自定义命令),可以注入:

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()

服务器配置格式

CompressorClient 接受用于 servers 选项 :

// 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"}}}',
});

逃生舱

// 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-core迁移暴露了一个高级本地客户端,用于程序内想要开始压缩 MCP 代理会话的应用程序,而不会生成 mcp-compressor CLI作为stdio子进程.

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();
}

套接字根现在暴露出 Rust后背 CompressorClient 作为迁移干线上的主要SDK表面.

Just Bash 模式允许语言主机将后端 MCP 工具注册为 Just Bash 命令 :

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();
}

连接的代理也可以写入 shell, Python, 或TypeScript 客户端, 这些客户端称为活的 Rust 代理 :

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();
}

发展

设置

cd typescript
bun install

图标

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

包装烟雾试验

从干净的临时项目构建和测试 npm 包 :

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进行同件包烟试验,并上传被包装的柏油丸为文物.

工具链

出版

要从源头发布,请确保您有主动的Artifactory 证书,然后运行:

bun run build
npm version <PUBLISH_VERSION> --no-git-tag-version
npm publish

发表于 @atlassian/mcp-compressor (原始内容存档于2013-10-12) (英语). atlassian Artifactory npmJS.

npm install @atlassian/mcp-compressor

子路径导出

@atlassian/mcp-compressor 运送一小批仅需要轻质部件的次路径出口给消费者。 从这些子路径导入可以避免加载 fastmcp,MCP SDK,以及其余的运行时间,可以增加数百毫秒的冷入成本.

// heavy: pulls fastmcp + MCP SDK
import { CompressorRuntime } from "@atlassian/mcp-compressor";

// light: ~zero runtime deps
import { interpolateString } from "@atlassian/mcp-compressor/config";

仅摘要的CLI发现

主机拥有的 CLI 和 Just Bash 转换可以保留完整的指令表面 仅向模型发布简短的工具集描述:

const transformed = await transformToolsForCliMode(tools, {
  serverName: "records",
  helpMode: "summary",
  helpSummary: "Search, read and manage enterprise records.",
});

helpMode 默认为 "full" (现有的子命令目录). 与 "summary", (中文(简体) ), 模式可见 records_help 描述省略了目录. helpSummary 实值 可选调用者授权的能力文本,而不是推断或检查过的 能力保证。 缺失/空白摘要可追溯到通用的CLI描述. 两者 records --help 和电话 records_help 仍然返回完整的发现; records <subcommand> --help 并且所有的引用都是不变的。 同样的选择 可在 planToolsForJustBash 编号 : transformToolsForJustBash。 。 。 .

使用主机 buildHostTransformPlan 直接通过相同的选项。 使用 plan.helpDescription 用于模型可见描述和 plan.helpText 页:1 帮助工具的执行结果。 这样做 没有 使用缩短的描述作为 需求帮助响应。 艺术品、命令登记、认证和计划 不变。 Python/ TypeScript 代码生成变换不支持摘要 模式。 这独立于 MCP 代理 compressionLevel; 它不添加新内容 独立CLI旗或更改高层次 CompressorClient 会话模式.