🗜️ MCP压缩代理

通过基于LLM的智能描述压缩从多个MCP服务器聚合工具

](https://www.npmjs.com/package/mcp-compression-proxy) ](https://www.npmjs.com/package/mcp-compression-proxy) ](https://www.npmjs.com/package/mcp-compression-proxy) ![License: MIT](https://opensource.org/licenses/MIT) ](https://nodejs.org/) ![MCP](https://modelcontextprotocol.io/)

![CI](https://github.com/kdpa-llc/mcp-compression-proxy/actions/workflows/test.yml) ![codecov](https://codecov.io/gh/kdpa-llc/mcp-compression-proxy) ![CodeQL](https://github.com/kdpa-llc/mcp-compression-proxy/actions/workflows/codeql.yml)

](https://github.com/kdpa-llc/mcp-compression-proxy/stargazers) ](https://github.com/kdpa-llc/mcp-compression-proxy/network/members) ](https://github.com/kdpa-llc/mcp-compression-proxy/issues) ](https://github.com/kdpa-llc/mcp-compression-proxy/commits/main) ![PRs Welcome](CONTRIBUTING.md)

快速开始 • 特性 • 配置 • 常见问题解答 • 贡献

______________________________________________________________________

______________________________________________________________________

什么是MCP压缩代理？

A. 模型上下文协议（MCP）服务器 这解决了两个常见问题：

多服务器聚合：通过单个连接从多个MCP服务器访问工具
上下文优化：使用基于LLM的智能描述压缩将令牌消耗减少50-80%

MCP压缩代理没有单独连接到多个MCP服务器，也没有在冗长的工具描述上消耗数千个令牌，而是聚合了所有工具并智能地压缩了它们的描述——在删除冗余的同时保留了关键信息。

非常适合：

拥有许多MCP服务器（文件系统、GitHub、数据库等）的用户
使用有限上下文窗口的AI代理
任何希望在最大限度地提高工具可用性的同时最大限度地降低代币成本的人

✨ 特性

🔗 多服务器聚合 -通过一个连接从多个MCP服务器访问工具
🤖 基于LLM的压缩 -智能描述压缩（令牌减少50-80%）
💾 永久存储 -压缩的描述已保存到磁盘，并在重新启动时恢复
🎭 基于会话的扩展 -每个对话的独立扩展状态
⚡ 并行初始化 -所有服务器并行连接，具有可配置的超时
🎯 选择性扩张 -压缩所有工具，只扩展您需要的工具
📦 零配置 -使用合理的默认值即可开箱即用
🔥 标准MCP -兼容任何MCP客户端（Claude Desktop、Cline等）

🚀 快速开始

先决条件

Node.js 18+ 安装在您的系统上
一 MCP兼容客户端 （克劳德桌面、克莱恩、Continue.dev等）

1.安装

选项A：从npm安装 （推荐给大多数用户）：

npm install -g mcp-compression-proxy

选项B：从源代码安装 （用于开发或最新功能）：

git clone https://github.com/kdpa-llc/mcp-compression-proxy.git
cd mcp-compression-proxy
npm install
npm run build

2.配置MCP客户端

添加到MCP客户端配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

如果通过npm安装：

{
  "mcpServers": {
    "compression-proxy": {
      "command": "mcp-compression-proxy",
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

如果从源代码安装：

{
  "mcpServers": {
    "compression-proxy": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-compression-proxy/dist/index.js"
      ],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

3.配置服务器

创建一个JSON配置文件来定义要聚合哪些MCP服务器：

选项1：用户级配置 （建议个人使用）

地点： ~/.mcp-compression-proxy/servers.json

选项2：项目级配置 （推荐用于团队项目）

地点： ./servers.json （在mcp压缩代理目录中）

配置示例：

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled": true
    },
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "enabled": true
    }
  ]
}

注：无需重建！只需编辑JSON文件并重新启动MCP客户端。

从TypeScript配置迁移（如果升级）

如果您从使用TypeScript配置的早期版本升级：

# Migrate to user-level config
npm run migrate-config

# Or migrate to project-level config
npm run migrate-config ./servers.json

迁移脚本将：

读取您的TypeScript配置
将其转换为JSON格式
保存到指定位置
如果配置已存在，则发出警告（防止意外覆盖）

4.重新启动MCP客户端

重新启动MCP客户端（例如Claude Desktop）以加载新配置。代理将自动连接到所有配置的MCP服务器，并使其工具可用。

🎯 用法

工具命名

代理工具 从您配置的MCP服务器使用以下格式 serverName__toolName:

filesystem__read_file
filesystem__write_file
github__create_issue

管理工具 （内置）没有前缀，如下所示。

管理工具

工具	说明
`create_session`	创建新会话以进行独立工具扩展
`set_session`	设置活动会话
`delete_session`	删除会话
`clear_compressed_tools_cache`	清除所有缓存的压缩工具描述
`get_uncompressed_tools`	获取需要压缩（批处理）的工具
`cache_compressed_tools`	将压缩的描述保存到缓存（批处理）
`expand_tool`	展开工具以显示完整描述（特定于会话）
`collapse_tool`	将工具折叠回压缩描述
`stats`	返回覆盖率、缓存运行状况、会话和每服务器工具计数的JSON摘要

使用 stats 来自您的客户（例如。， mcp-compression-proxy__stats)对覆盖范围进行健全性检查。可选输入： serverName 将范围扩展到一个后端 detailLevel (summary 或 full，默认值 summary).响应包括覆盖率%、估计的令牌节省、缓存状态、活动会话和每服务器工具计数（尊重您的排除模式）。 | stats |返回覆盖率、缓存运行状况、会话和每服务器工具计数的JSON摘要|

工作流示例

1.压缩前

当你第一次向你的人工智能助手询问可用的工具时：

User: What tools do you have?

AI: I have access to these tools:
- filesystem__read_file: Reads the complete contents of a file at the
  specified path. The file must exist and be readable. Returns the file
  contents as text. Supports absolute and relative paths. Maximum file
  size is 10MB. Will throw an error if the file doesn't exist...
  [~200 tokens for one tool]

2.启用压缩（一次性设置）

让你的AI助手压缩描述：

User: Use the mcp-compression-proxy tools to compress tool descriptions and save model context

AI: I'll compress the tool descriptions:
1. Getting all tools via get_uncompressed_tools...
2. Compressing descriptions intelligently...
3. Saving compressed versions via cache_compressed_tools...

Done! Tool descriptions are now compressed and saved to cache.

3.压缩后

同一请求现在使用的令牌要少得多：

User: What tools do you have?

AI: I have access to these tools:
- filesystem__read_file: Read file contents (text, max 10MB)
- filesystem__write_file: Write/overwrite file
- github__create_issue: Create GitHub issue
  [~30 tokens for one tool]

结果：工具列表代币减少约70%！

4.持久存储

压缩的描述会自动保存到磁盘 ~/.mcp-compression-proxy/cache.json 并在服务器重启时加载。重启后无需重新压缩！

如有需要，清除缓存：

# If installed via npm
mcp-compression-proxy --clear-cache

# If installed from source
node dist/index.js --clear-cache

💡 小贴士：设置后，只需告诉您的AI： *“压缩工具描述以保存上下文”* 它会处理剩下的！

🔧 配置

服务器配置

在以下位置创建或编辑JSON配置文件：

~/.mcp-compression-proxy/servers.json （用户级别），或
./servers.json （项目级）

{
  "mcpServers": [
    {
      "name": "my-server",
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "enabled": true
    }
  ]
}

配置架构

根级别：

字段	类型	必填	描述
`mcpServers`	数组	✅	服务器配置数组
`excludeTools`	string\[\]	❌	要从工具列表中完全排除的工具名称模式（支持通配符）
`noCompressTools`	string\[\]	❌	永不压缩的工具名称模式-描述传递不变（支持通配符）
`defaultTimeout`	编号	❌	所有服务器的默认超时时间（秒）（默认值：30）。可以按服务器覆盖。

服务器配置：

字段	类型	必填	描述
`name`	string	✅	唯一服务器标识符
`command`	string	✅	要执行的命令
`args`	string\[\]	❌	命令参数
`env`	对象	❌	环境变量
`enabled`	boolean	❌	启用/禁用服务器（默认值：true）
`timeout`	编号	❌	服务器特定超时（秒）（覆盖 `defaultTimeout`)

环境变量扩展

使用 ${VAR_NAME} 引用环境变量的语法：

{
  "mcpServers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}",
        "GITHUB_ORG": "${MY_GITHUB_ORG}"
      }
    }
  ]
}

变量在运行时从shell环境中展开。

服务器初始化和超时

代理初始化中所有配置的MCP服务器并行在准备好之前。每个服务器连接都有一个超时，以防止无限期挂起：

默认超时：30秒（如果未指定）
全局超时：设置 defaultTimeout 在config中更改所有服务器的默认值
每台服务器超时：设置 timeout 在单个服务器上覆盖默认值

{
  "defaultTimeout": 60,
  "mcpServers": [
    {
      "name": "fast-server",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      "name": "slow-server",
      "command": "python",
      "args": ["slow_mcp_server.py"],
      "timeout": 120
    }
  ]
}

行为：

所有服务器并行初始化（不是顺序初始化）
如果服务器超过其超时时间，则标记为失败，但不会阻止其他服务器
只有在所有服务器都已连接或超时后，代理报告才准备就绪
这可确保在MCP客户端查询之前加载所有可用工具

为什么这很重要： 如果没有适当的超时处理，单个挂起的服务器可能会使整个代理没有响应。

工具过滤模式

排除工具 -从工具列表中完全删除工具：

使用 excludeTools 字段，使用通配符模式过滤掉不需要的工具（不区分大小写）：

{
  "mcpServers": [...],
  "excludeTools": [
    "github__delete_*",     // Exclude all GitHub delete tools
    "*__experimental*",     // Exclude all experimental tools
    "filesystem__write_*",  // Exclude filesystem write tools
    "set_*"                 // Exclude management tools starting with set_
  ]
}

无压缩工具 -保留工具，但不要压缩它们的描述：

使用 noCompressTools 字段绕过特定工具的压缩（描述不变）：

{
  "mcpServers": [...],
  "noCompressTools": [
    "filesystem__*",        // Never compress filesystem tool descriptions
    "*__help",              // Never compress help commands
    "github__search_*"      // Never compress GitHub search tools
  ]
}

模式示例：

"serverName__*" -来自特定服务器的所有工具
"*__toolPattern*" -从任何服务器匹配模式的工具
"exact_tool_name" -工具名称完全匹配

使用案例：

excludeTools：删除危险工具、不需要的功能或与工作流程无关的工具
无压缩工具：保留复杂工具的详细描述，因为压缩可能会丢失重要信息

配置聚合

加载并组合两个配置文件：

加载用户配置(~/.mcp-compression-proxy/servers.json)
加载项目配置(./servers.json)
从两个配置中聚合服务器
从两个配置中聚合排除和noCompress模式
将排除模式应用于筛选工具
应用noCompress模式以绕过压缩

这允许：

用户配置中的个人默认值
项目配置中的团队/项目特定服务器
使用排除模式进行细粒度工具过滤
具有noCompress模式的选择性压缩旁路

环境变量

对于压缩代理 （在MCP客户端配置中设置）：

LOG_LEVEL -日志记录级别（调试、信息、警告、错误）。违约： info

对于MCP服务器 （设置在 servers.json 使用 ${VAR_NAME} 语法）：

GITHUB_TOKEN -GitHub个人访问令牌（如果使用GitHub MCP服务器）
配置的MCP服务器所需的任何其他环境变量

看环境变量扩展有关在服务器配置中使用变量的详细信息。

命令行选项

--clear-cache -清除持久压缩缓存并退出

# If installed via npm
mcp-compression-proxy --clear-cache

# If installed from source
node dist/index.js --clear-cache

调试

1.启用调试日志记录 在MCP客户端配置中：

{
  "mcpServers": {
    "compression-proxy": {
      "command": "mcp-compression-proxy",
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

2.查看日志 （适用于克劳德桌面）：

macOS: ~/Library/Logs/Claude/mcp*.log
视窗: %APPDATA%\Claude\Logs\mcp*.log

3.检查常见问题：

确保所有配置的MCP服务器均可访问且配置正确
验证环境变量是否正确展开
检查Node.js版本是否为18或更高

💡 最佳实践

压缩良好

保留:

核心功能
关键参数
关键约束
返回类型

去除:

详细解释
冗余短语
非关键示例
营销语言

示例

原版（42个代币）：

"Searches for files in the specified directory and its subdirectories using
glob patterns. Supports wildcards like *, **, and ?. Returns an array of
matching file paths. Case-sensitive by default."

压缩的 （12个代币）：

"Search files by glob pattern (*, **, ?), case-sensitive, returns paths"

❓ 常见问题解答

Q: What MCP clients are supported?

Any MCP-compatible client: Claude Desktop, Cline, Continue.dev, or custom agents.

Q: How much context does compression save?

Typically 50-80% reduction in token count for tool listings while preserving critical information.

Q: Do I need to restart after adding servers?

Yes, restart your MCP client to load the new configuration. No rebuild needed when using JSON configuration.

Q: Can I use multiple MCP servers?

Yes! That's the primary use case. Add as many as you need in your servers.json configuration file.

Q: Is compression permanent?

Compressed descriptions are persisted to disk at ~/.mcp-compression-proxy/cache.json and automatically restored on server restart. Session-based expansions are temporary and reset per session.

Q: Where is the compression cache stored?

Cache is stored at ~/.mcp-compression-proxy/cache.json. Use --clear-cache flag to clear it if needed.

Q: Works with local LLMs?

Yes! Works with any MCP-compatible setup, including local models.

Q: How do I add a new MCP server?

Edit your servers.json configuration file (in ~/.mcp-compression-proxy/ or project root), add your server config, and restart your MCP client. No rebuild needed.

更多： 看贡献.md, 安全.md, 测试/README.md

🧪 测试

全面的测试套件包括：

npm test                      # Run all tests
npm run test:unit             # Unit tests only
npm run test:integration      # Integration tests only
npm run test:e2e              # End-to-end tests only
npm run test:e2e:real-llm     # Real LLM integration tests (requires Ollama)
npm run test:coverage         # Generate coverage report

看测试/README.md 了解详情。

🤝 贡献

欢迎投稿！看贡献.md 作为指导方针。

快速启动：

分叉存储库
创建功能分支
进行更改和测试
使用提交约定式提交
打开拉取请求

注：本项目遵循行为准则.

🔗 补充项目

使用这些补充工具最大限度地提高您的MCP工作流程：

本地技能MCP

适用于任何MCP客户端的可移植、可重用的提示库

虽然MCP工具聚合器优化了您的工具描述，本地技能MCP 提供专家级提示说明，适用于任何兼容MCP的客户端。

完美组合：

MCP工具聚合器 -聚合和压缩工具描述（令牌减少50-80%）
本地技能MCP -提供延迟加载的专家技能（约50个令牌/技能）

它们共同实现了：

🎯 跨工具和提示优化上下文使用
🔄 适用于Claude、Cline、Continue.dev等的可移植工作流
⚡ 以最小的上下文消耗进行高效的AI交互
🚀 专业级AI代理能力

了解有关本地技能MCP的更多信息→

💖 支持这个项目

如果您发现MCP压缩代理有用，请考虑支持其开发！

](https://github.com/sponsors/moscaverd) ![Buy Me A Coffee](https://buymeacoffee.com/moscaverd) ![PayPal](https://paypal.me/moscaverd)

支持方式：

⭐ 标记此存储库
💰 通过上面的徽章赞助
🐛 报告错误并建议功能
📝 贡献代码或文档

📄 许可证

🙏 致谢

内置于模型上下文协议SDK

______________________________________________________________________

⬆ 返回页首

由以下材料制成❤️ 通过KDPA

MCP Compression Proxy

快速接入

详细介绍

🗜️ MCP压缩代理

📑 目录

什么是MCP压缩代理？

✨ 特性

🚀 快速开始

先决条件

1.安装

2.配置MCP客户端

3.配置服务器

从TypeScript配置迁移（如果升级）

4.重新启动MCP客户端

🎯 用法

工具命名

管理工具

工作流示例

1.压缩前

2.启用压缩（一次性设置）

3.压缩后

4.持久存储

🔧 配置

服务器配置

配置架构

环境变量扩展

服务器初始化和超时

工具过滤模式

配置聚合

环境变量

命令行选项

调试

💡 最佳实践

压缩良好

示例

❓ 常见问题解答

🧪 测试

🤝 贡献

🔗 补充项目

本地技能MCP

💖 支持这个项目

📄 许可证

🙏 致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP