activeing123/mcptoon

📦 mcptoon – MCP 工具与技能的无配置令牌优化与统一治理

它是什么

• 一个极小的（363 KB）纯 Python CLI，位于你的本地 AI 代理（Claude、Cursor、Gemini 等）与已安装的Model Context Protocol（MCP）工具/技能之间。
• 它将完整的工具/技能模式排除在 LLM 的上下文窗口之外，仅提供紧凑的名称索引，从而将模型需要处理的文本量减少超过 99%。
• 开箱即用支持 103+ 桌面和 CLI 代理，且无需外部依赖——只需 pip install mcptoon。

核心能力

类别	你的收获
令牌与上下文优化	• 仅名称索引（255 个工具从 72k → 581 个令牌） • 可逆检索（retrieve）实现无损压缩 • 会话级去重相同输出 • 通过 mcptoon bench 进行真实令牌核算
通用工具管理	• 搜索 17,000+ 个已注册 MCP 服务器（search） • 任何 MCP 工具的统一 CLI 驱动（call） • 按需模式检查（inspect） • 自愈诊断（doctor）
技能治理	• 跨多个代理（Claude、Cursor 等）的单源同步 • 离线 BM25 技能路由器（<5 毫秒，零模型成本） • 版本门控防漂移，墓碑删除失效技能
文档路由	• 自动 markdown 树索引 • 章节级喂送（仅必要部分） • 零模型 BM25 匹配（每次查找节省约 40k 令牌）
工程纪律	• 外部依赖为零（仅标准库） • XDG 兼容配置隔离 • 完全本地，支持气隙环境，无遥测

工作原理

1. 紧凑目录 – 仅将工具/技能名称（以及一个微小指针）保留在 LLM 上下文中。完整的 JSON 模式存储在磁盘上，并通过 mcptoon inspect 懒加载。
2. 按需检索 – 当代理调用工具时，mcptoon 拉取模式、运行工具并返回结果。可选的 --toon 标志将结果重新编码为更小的 "TOON" 格式（混合数据可减少约 5% 大小）。
3. 通用网关 – mcptoon serve 暴露一个 MCP 端点，该端点将调用转发到任何已注册的服务器，因此每个代理都可以使用相同的后端而无需单独配置。

快速开始

pip install mcptoon               # 零依赖，2 秒安装
mcptoon quickstart                # 自动检测 MCP 服务器，将 /mcptoon 技能注入所有代理
mcptoon manifest                  # 查看紧凑的工具目录（255 个工具 581 个令牌）
mcptoon call demo echo_message '{"message":"hi"}'

你也可以直接从代理中交互，要求它加载 /mcptoon 技能——无需终端命令。

典型用例

• 高级用户 – 运行许多 MCP 工具，并看到令牌预算被工具描述消耗。
• 团队 – 希望在数十个代理中为工具/技能建立单一事实来源，而无需编辑每个代理的 JSON。
• CI / 自动化流水线 – 需要稳定、可脚本化接口（mcptoon call …）和可选 HTTP 代理（mcptoon serve）。
• 气隙环境 – 无法安装额外运行时（Node、Docker）的环境——mcptoon 是纯 Python 标准库。

限制 / 注意点

• 令牌节省仅在代理能够调用 mcptoon（通过注入的技能或通过调用 mcptoon serve MCP 端点）时适用。将工具模式硬编码到提示中的代理将无法受益，除非重新配置。
• 结果压缩（--toon）取决于形状；某些负载仅缩小几个百分点，其他可达 ~50%。
• mcptoon 本身不提供任何工具——你必须从外部 MCP 注册表发现或安装它们。

许可证

• Apache 2.0（参见 LICENSE）。

了解更多

• 官方网站：https://mcptoon.github.io/
• 令牌税计算器：https://mcptoon.github.io/tools/token-tax/
• 开发者文档：仓库中的 DEVELOPERS.md。

---

所有陈述均直接来自仓库的 README；未推断任何额外功能。