# @atlassian/mcp-compressor 中文文档

规范地址：https://npmcn.com/package/%40atlassian/mcp-compressor/

版本：0\.40\.0
npm 元数据更新时间：2026-10-31T04:05:56.064Z
中文译文更新时间：2026-11-07T03:27:10.120Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlassian/mcp-compressor
原文对照：https://npmcn.com/package/%40atlassian/mcp-compressor/?lang=original
项目主页：https://github.com/atlassian-labs/mcp-compressor
源码仓库：https://github.com/atlassian-labs/mcp-compressor

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：153 MB，50 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-05-13T01:07:15.343Z
- 最新版本发布：2026-10-31T04:05:55.892Z
- 近 30 天下载量：2660（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：58（近 12 个月 58 个）

## 中文简介

TypeScript MCP 服务器包装器,用于减少 MCP 工具所消耗的令牌.

## 安装

```sh
npm install @atlassian/mcp-compressor
```

也可以使用：`pnpm add @atlassian/mcp-compressor`、`yarn add @atlassian/mcp-compressor`、`bun add @atlassian/mcp-compressor`

## README

# @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上下文窗口中工具描述的符号成本,同时保留了完整的工具功能.

### 压缩级别

| 职等 | LLM看到的东西 |
| --- | --- |
| `low` | 工具名称、参数和完整描述 |
| `medium` (默认) | 工具名称、参数和说明的第一句 |
| `high` | 只使用工具名称和参数 |
| `max` | 只使用工具名称( 需要 `list_tools` 请求发现) |

### 三种模式

| 模式 | 已曝光的工具 | LLM 如何引用工具 |
| --- | --- | --- |
| **压缩** (默认) | `get_tool_schema` + 键 `invoke_tool` | 通过 MCP 工具调用 |
| **国 际** | 服务器 `_help` 工具 | Via bash CLI 命令( 桥+生成脚本) |
| **巴许** | 服务器 `_help` 工具+ 设备 `bash` 工具 | 通过一个沙盒 [刚刚巴什](https://www.npmjs.com/package/just-bash) 外壳 |

## 安装

```bash
npm install @atlassian/mcp-compressor

# Optional: for bash mode
npm install just-bash
```

## STIO MCP 代理服务器

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

### 压缩模式( 默认)

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

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

```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
```

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

### Bash 模式

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

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

然后LLM看到:

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

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

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

### 奥奥特

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

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

## 进程内使用( CompressorClient)

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

### 压缩模式

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

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

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

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

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

### 服务器配置格式

`CompressorClient` 接受用于 `servers` 选项 :

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

### 逃生舱

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

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

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

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

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

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

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

## 发展

### 设置

```bash
cd typescript
bun install
```

### 图标

```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
```

### 包装烟雾试验

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

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

### 工具链

| 工具 | 目的 |
| --- | --- |
| [阿宝](https://bun.sh/) | 软件包管理器和运行时间 |
| [类型脚本](https://www.typescriptlang.org/) | 类型检查 |
| [维特](https://vitest.dev/) | 测试运行器 |
| [奥克林特](https://oxc.rs/docs/guide/usage/linter) | 线条 |
| [氧化剂](https://oxc.rs/docs/guide/usage/formatter) | 主题 |
| [指挥官](https://github.com/tj/commander.js) | CLI 参数解析 |

## 出版

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

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

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

```bash
npm install @atlassian/mcp-compressor
```

### 子路径导出

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

| 子路径 | 目录 | 何时使用 |
| --- | --- | --- |
| `@atlassian/mcp-compressor` | 全职(`CompressorRuntime`, (中文(简体) ), `CompressorServer`, (中文(简体) ), `BackendClient`, (中文(简体) ), `FastMCP`, (...) (中文(简体) ) | 建/ 托管压缩机代理. |
| `@atlassian/mcp-compressor/bash` | 刚刚巴什变换的帮助者 | 巴什工具转换. |
| `@atlassian/mcp-compressor/config` | `interpolateString`, (中文(简体) ), `interpolateRecord`, (中文(简体) ), `parseServerConfigJson` | 纯配置解析 / `${ENV}` 工具中的插值. |
| `@atlassian/mcp-compressor/errors` | `InvalidConfigurationError` 朋友们 | 没有运行时间就输入错误 . |
| `@atlassian/mcp-compressor/types` | `BackendConfig`, (中文(简体) ), `CompressionLevel`, (中文(简体) ), `CommonProxyOptions`,, , , , , , , , . | 只有型号的消费者. |

```ts
// 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 转换可以保留完整的指令表面 仅向模型发布简短的工具集描述:

```typescript
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` 会话模式.

## 常见问题

### @atlassian/mcp-compressor 是什么？

TypeScript MCP 服务器包装器,用于减少 MCP 工具所消耗的令牌\.

### 如何安装 @atlassian/mcp-compressor？

在项目目录运行 npm install @atlassian/mcp-compressor，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-compressor、atlassian-mcp-compressor，可以用 npx mcp-compressor 直接运行。

### @atlassian/mcp-compressor 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlassian/mcp-compressor 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @atlassian/mcp-compressor 可以商用吗？

@atlassian/mcp-compressor 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlassian/mcp-compressor 的下载量有多少？

根据 npm 官方下载统计，@atlassian/mcp-compressor 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,660 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlassian/mcp-compressor 还在维护吗？

最新版本 0\.40\.0 发布于 2026/10/31（7 天前）；至今共发布 58 个版本，其中过去 12 个月发布了 58 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。