用途
mcptoon 面向需要在多个 AI 智能体（编码助手、桌面应用、CLI 工具）中使用 MCP 工具与智能体技能的用户。它解决的核心问题是：每个 MCP 智能体在开始工作前都会把每个工具、每个技能的完整描述加载进上下文窗口，并在每一轮对话中重复发送，占用大量 token。mcptoon 将这些描述保留在磁盘上，只向智能体提供紧凑视图，从而降低上下文开销，并让本机的工具与技能在所有智能体之间共享，无需逐个编辑各智能体的 JSON 配置。
主要能力
工具 schema 按需加载
默认的 mcptoon manifest 将完整 schema 压缩为名称索引。示例数据：255 个工具的 schema 合计 71,929 token，压缩后为 581 token，减少 99.2%。当需要某个工具时，用 mcptoon inspect 获取其真实参数，再用 call 执行。也提供 --slim（名称加参数类型，示例 8,282 token，减少 88.5%）和 --full（完整 schema）。
技能管理
用一条常驻指针（39 token）加一次查找（501 token）替代加载全部 SKILL.md。示例数据：926,232 token 的 SKILL.md 文本变为 39 常驻 + 501 每次查找，减少 99.9%。视图以链接形式呈现（Windows 上为 junction，无需管理员权限），源处一处编辑即可全局生效，不存在第二份副本漂移。
调用结果压缩
mcptoon call 默认输出 JSON，默认不压缩；添加 --toon 可将结果重新编码为标准 TOON。混合结果样本实测缩小 5.7%，按结果形态范围在 1.8% 至 48.6% 之间（列表型记录几乎不缩小，单条记录约减半）。
统一配置与安装
安装一次，机器上每个 AI 都能获得全部工具和技能。新添加的工具和技能立即可用，无需重启智能体，也无需逐个编辑 JSON。安装后 mcptoon 会自动向各智能体注入其官方技能 /mcptoon，用户不必记忆终端命令，直接在 Cursor、Claude Code、Windsurf、DSH 等中提问即可。
工具发现与安装
mcptoon 自身不捆绑工具和目录，而是实时查询上游注册表。mcptoon install --search github 可查找并安装任意 MCP 服务器；mcptoon discover 可扫描本机已有服务器。搜索结果带有 ✓（注册表已验证）、类型标签（npm / pypi / hosted / remote）和调用次数，数据来自两个上游，实时查询、从不存储，只在用户自己的 ~/.mcptoon/config.json 中写入一行指针。远程服务器所需 token 从环境变量读取，${NAME} 在请求时解析，配置和日志中保留模板，轮换变量后下次调用即用新值，无需重装；变量缺失或为空会明确报错并点名该变量。
技能搜索与安装
mcptoon skills search <query> 查询开放技能索引（skills.sh），按用途查找技能，再用 skills add <git-url> 安装。
起始包
内置四个起始包：essentials、web-research、code-review、docs，各自捆绑若干工具和现成提示词。mcptoon install --packs 列出，mcptoon install --pack essentials 安装其一。其中两个研究类起始包无需 API key。
与智能体集成
mcptoon 通过两种方式触达智能体：CLI 方式（智能体自身能运行 shell，直接执行 mcptoon call / search / skills resolve，零配置）和 serve 方式（客户端无法运行 shell 时，以 mcptoon serve 作为单个 MCP 服务器挂载，只需一条配置）。quickstart 两者都会注册。README 列出 103 个客户端（42 个 CLI、61 个 serve）。
回滚与可逆性
安装会注册网关。默认 quickstart 会把已有服务器路由到网关并移除其直接条目（否则同一工具会同时以直接和网关两种方式出现，反而更贵）。这是明确列出并需确认的步骤，且可撤销：mcptoon restore 移除网关条目并把服务器恢复原状，之后新增的配置不受影响。mcptoon off 是更轻的开关，只移除网关条目，保留服务器原样。两者均可用 --dry 预览；mcptoon uninstall --dry 会先打印完整的移除计划。mcptoon sync --self 可重新注册自身，mcptoon status 可随时查看状态，并同时打印网关与精简 schema 两组数据。
使用方式
安装：
pip install mcptoon
mcptoon quickstart
在遵循 PEP 668 的 Linux 发行版（Debian/Ubuntu 23.04+）及 macOS Homebrew Python 上，直接 pip install 到系统 Python 会被拒绝并报 externally-managed-environment 错误，建议使用 pipx 或 venv；pip install --break-system-packages mcptoon 也可行，但会写入系统 Python。Windows 上 pip install mcptoon 可直接使用。
常用命令示例：
mcptoon install --search github
mcptoon skills search "make a PDF"
mcptoon inspect
mcptoon call
mcptoon serve
mcptoon bench
mcptoon status
mcptoon restore
mcptoon off
输出格式：默认 JSON，--toon 输出更小的结果（形态相关，混合样本约 5.7%），--format mcp 导出标准 MCP JSON。mcptoon serve 支持 stdio 或 HTTP、连接池、按智能体的密钥。
适用场景
- 本机安装了多个 AI 智能体（Claude Desktop、Claude Code、Codex、Cursor、Windsurf、Cline、VS Code Copilot、Gemini CLI、Qwen Code、Zed、Crush、opencode 等），希望工具与技能一次安装、处处共用。
- 本地配置了成百上千个 MCP 工具或技能，担心上下文被工具描述淹没。
- 需要脚本化接入自有智能体、CI 或应用，使用稳定 JSON 输出或 mcptoon serve 的 MCP 端点。
- 希望在不改动各智能体配置的前提下按需使用工具，并在需要时快速回滚。
限制与说明
- 官方未说明工具的收费情况，暂未提供相关信息。
- 工具自身不捆绑任何工具目录，搜索结果来自上游注册表，需用户自行判断第三方包的来源与安全性（README 提示带 ✓ 表示注册表已验证，交予凭据前应先阅读源码）。
- README 同时声明：其节省数字由自身测量得出；而“把全部工具 schema 加载进上下文成本高昂”这一判断也有其他来源佐证，但具体对比数值不得跨场景混用。
- 三个节省口径（工具发现、调用结果、技能目录）彼此独立，不能交叉比较。
- 可测量自有目录：mcptoon bench 报告的是用户自己的工具集合，而非固定的 255 工具样本。
- 具体各客户端支持情况以官方文档列出的 103 个客户端为准；未在资料中列出的客户端暂未提供说明。
