mcptoon

MCP 令牌优化、工具发现与上下文压缩——面向 MCP 工具和 Agent 技能的零配置 CLI

在本地安装 1,000 个技能和 1,000 个 MCP 工具，再也不必担心上下文过载。
一个零依赖的 MCP CLI 和 MCP 客户端，用于 MCP 令牌优化：通过精简名称索引实现工具发现，并进行上下文压缩，将工具上下文减少约 90%（255 个工具时减少 99.2%），同时让架构定义不占用上下文窗口——无需配置，支持 103+ 款桌面和命令行 Agent。

🌐 官方网站 · 🧮 30 秒令牌成本计算器 · 🇨🇳 中文文档 · 📖 开发者文档

_{对合成的 255 个工具样本持怀疑态度？这里展示了在真实机器上测得的 7 个真实公开 MCP 服务（209 个工具）→——640,606 → 905 个令牌（−99.86%）。也可以在自己的目录上运行 mcptoon bench。}

https://github.com/user-attachments/assets/0272d3a8-c74f-428d-8559-fbf804ce0685

① 💥 工具、技能和文档占满上下文——担心再添加更多内容？ 想加多少就加多少。工具架构从 72k → 581 个 token。 工具 −99.2% · 技能 −99.99% · 每个问题的文档从 40k→17k

② 🧩 有多个 Agent——JSON 配置和技能都很麻烦？ 它是一个原生 CLI：任何能运行 shell 命令的 Agent 都能使用全部功能——无需 MCP 服务，也无需配置。sync 也支持 GUI 客户端（103+）。 无需编辑 JSON，无需重启

③ 🔍 知道有 17,000 多个，但不知道哪一个适合？ 它会先发现你已有的服务（无需重新安装），再通过日常用语查找其余服务——找到后即可安装并调用。 mcptoon discover → search → call

_{此外还有：OpenAPI / GraphQL 透传 · OAuth · MCP 资源和提示词 · 已保存的连接 · 代码沙盒 — 查看所有命令。}

pip install mcptoon && mcptoon quickstart — 534KB、零依赖、零配置。

_{自动保持最新：有新版本时会通知你，并可通过一条命令 mcptoon upgrade 完成更新。}

🚀 快速开始（选择你的方式）

# Ask the built-in skill anytime:
"Load /mcptoon skill and check what MCP tools I currently have."
"Help me find an MCP tool that converts HTML to PDF and call it."
"The tool output was truncated, retrieve the full original copy."
"How many tokens did mcptoon save for me today?"
"Doctor self-check: are all my MCP servers connected properly?"

# 1. Install (zero dependencies, 534KB)
pip install mcptoon

# 2. One command: detect MCP servers & auto-configure agents
# (Also self-installs `/mcptoon` skill into all detected agents)
mcptoon quickstart

# 3. View compact tool catalog (-99.2% tokens)
mcptoon manifest

# 4. Route tasks to skills or doc chapters (<5ms)
mcptoon skills resolve "write git commit message"
mcptoon docs resolve "how does release gating work"

它真的能帮你节省资源吗？ 全新安装后，mcptoon 可能处于 direct 模式——已安装，但未接入 Agent，因此不会节省任何资源。请参阅 哪种模式最省？，或直接运行 mcptoon mode。

⚡ 核心功能一览

_{所有命令及其标志都列在全部命令中。}

为什么选择 mcptoon

每个 MCP Agent（Claude Code、Cursor、Codex、……）都会在开始工作前，将每个工具和每项技能的完整描述加载到上下文窗口中 — 并在每一轮重新发送。对于 255 个工具，这需要 71,929 个 token：在提出第一个问题之前，描述就占用了 128K 窗口的一半以上。

节省令牌的原理

mcptoon 将这些描述保存在磁盘上，而不是上下文中，并向 Agent 提供精简视图：

• 名称索引，而非完整架构。 选择工具只需知道它的名称——255 个工具只占 581 个令牌（−99.2%）。只有在实际调用工具时，才会按需通过 mcptoon inspect 获取完整架构。
• 技能也采用同样的方式。 一个常驻指针（39 个令牌）加一次查找（791 个令牌），取代完整加载每个 SKILL.md——1,572,330 → 39 + 791（−99.99%）。
• 结果也一样。 --toon 会将工具的结果重新编码为标准 TOON。 在混合结果样本中，测得体积缩小 5.7%；具体幅度因结果形状而异，范围为 1.8%-48.6%——记录列表几乎不会缩小，单条记录则会缩小一半。并非一律缩小 34%：请参阅 assets/benchmark_results.json。

不会丢失任何内容：完整架构和完整技能文本只需一条命令即可获取。它只节省上下文窗口。

mcptoon 是一个 534KB、零依赖的原生 CLI，可管理你电脑上的所有 MCP 工具和 Agent 技能，并在你无需编写任何配置的情况下与所有 Agent 共享它们。

这不只是我们在说

这些数据来自我们——但“将每个工具架构都加载到上下文中代价高昂”并非只有我们这样认为：

• Anthropic 的工程文章——工具架构大量涌入上下文窗口确实会带来成本；其中一个示例从 150,000 个令牌降至 2,000 个
• Firecrawl 的基准测试——完成同一任务，使用 CLI 花费 1,365 个令牌，使用 MCP 则花费 44,026 个（32 倍）
• Scalekit 的基准测试——CLI 的成本低 10–32 倍，可靠率为 100%，而 MCP 为 72%
• MCP-Zero（arXiv:2506.01056）——按需检索工具，无论工具数量多少，成本都近乎恒定

mcptoon 是你现在就能使用的方案：它支持任何能运行 shell 的 Agent，并会将一行连接配置写入它支持的主流 GUI 客户端。

两种使用方式

测量你自己的数据：pip install mcptoon && mcptoon bench——它会报告你自己的工具目录，而不是下方固定的 255 工具样本（该样本的测试方法见 docs/tiktoken-benchmarks.md）。

技能也采用同样的方式：1,572,330 个令牌的 SKILL.md 文本 → 常驻 39 个令牌 + 每次查找 791 个令牌（−99.99%）。使用 --toon 后，调用结果还能进一步缩小 约 6%（具体取决于结果形状）。

路径 1 · 我只使用 AI 工具

你有一个桌面 AI 助手——Claude、Codex、Cursor、Windsurf、Cline、VS Code Copilot，以及 另外 97 个（103 个的完整列表 →）。如今，添加工具或技能意味着要手动编辑该 Agent 的 JSON。mcptoon 省去了这一步：

1. 只需安装一次。

   pip install mcptoon && mcptoon quickstart
   

   quickstart 会查找你的 MCP 服务、写入配置，并在检测到的每个 Agent 中注册 mcptoon。 （跳过 quickstart 也没关系：你运行的第一条命令仍会自动修复——在每个 Agent 中安装 mcptoon 自带的技能，并为本机生成一次技能索引。）

2. 在一个地方添加工具和技能——就在这里，而不是分别在每个 Agent 中添加。

   mcptoon install --search github     # find and install any MCP server
   mcptoon skills search "make a PDF"  # find a skill by what it does
   

3. 通过任何 Agent 使用它们。 你的 Agent 会像运行其他命令一样运行 mcptoon——无需配置，也无需重启。请参阅兼容所有 AI Agent。

想快速上手？ 四个内置入门包——essentials、web-research、code-review、docs——只需一条命令即可搭建一套可用的工具集：

mcptoon install --pack essentials

路径 2 · 我使用 MCP / Agent 构建

mcptoon 是一个支持脚本化输出的普通 CLI，并且可按需提供 MCP 端点。

mcptoon manifest --format json      # machine-readable tool index
mcptoon call <server> <tool> '{}'   # call any tool, JSON or --toon output
mcptoon serve                       # expose every configured server behind one MCP endpoint

• 稳定的输出——默认使用 JSON；使用 --toon 可获得更小的结果（大小取决于结构，在混合样本中减少 5.7%）；使用 --format mcp 可导出标准 MCP JSON。
• mcptoon serve——支持 stdio 或 HTTP、连接池和按 Agent 设置密钥，适用于坚持使用代理的客户端。
• 零依赖——仅使用 Python 标准库，因此可部署到任何环境（CI、容器、隔离网络）。

完整参考：DEVELOPERS.md 和所有命令。

目录

• 为什么选择 mcptoon
• 节省 Token 的原理
• 不只是我们在说
• 两种使用方式
• 路径 1 · 我只使用 AI 工具
• 路径 2 · 我使用 MCP / Agent 构建
• 30 秒即可运行
• 它的功能
• 工具来源
• 三笔账单
• 安装
• 兼容所有 AI Agent — 103 个客户端（42 个 CLI · 61 个 serve）
• 为什么选择 CLI，而不是代理
• 哪种模式最省钱？
• 所有命令
• 信任与安全
• 致谢与参考
• 贡献
• 故障排除与常见问题
• 许可证

30 秒即可启动并运行

pip install mcptoon                          # pure stdlib, 534KB, zero dependencies

# One command: find your MCP servers, write your config, register the gateway
# in every agent you have, and show you what it found:
mcptoon quickstart

# See every tool available (names-only by default; 255 tools cost 581 tokens):
mcptoon manifest

# Call a tool (JSON output by default; add --toon to save more).
# `everything` is only present if you already had it; otherwise add the built-in
# zero-dependency demo server first (no Node, no network) and call that:
mcptoon add demo --stdio python -m mcptoon demo-server
mcptoon call demo echo_message '{"message":"hi"}'

quickstart 也让 mcptoon 变得可见：它会在每个 Agent 的配置中写入 mcptoon serve，将其注册为保留服务 mcptoon，这样你的 Agent 就能看到 mcptoon 本身。 已经同步过？请使用 mcptoon sync --self 重新注册（普通的 mcptoon sync 只会写入你的服务）；随时使用 mcptoon status 查看状态。

两种接入方式，而且不必二选一。 mcptoon 首先是一个 CLI：具备 shell 操作能力的 Agent 可以运行 mcptoon 命令，这是成本最低的方式——模式定义不会进入上下文。 quickstart 还会为每个支持 MCP 的 Agent 注册 mcptoon 自身的 MCP 入口（mcptoon serve），这样只能看到 MCP 服务的客户端也能使用你的工具。MCP 入口以 compact 模式运行：它不会将上游工具列表放入模型上下文，而是通过 mcptoon_manifest → inspect → call 来传递。mcptoon status 会显示这两种记录。

而且完全可逆。 安装会注册网关，默认情况下，quickstart 还会接管——通过网关转发你现有的服务，并移除它们的直接入口（如果不执行这一步，你的 Agent 会看到重复的工具，一份直接提供，一份经由网关提供，成本会更高，而不是更低）。这一步会明确列出并经你确认，而且可以撤销：mcptoon restore 会移除网关入口，并将你的服务原样放回原处。 之后添加到配置中的任何内容都会保持不变。mcptoon off 是更轻量的开关——它只会移除网关入口，保留你的服务原位。 使用 --dry 预览这两项操作，使用 mcptoon uninstall --dry 预览完整的移除计划（它会先准确列出将要移除的内容）。

还不想安装？可以先观看它运行（需要 Node）：

uvx mcptoon demo --quick

它会启动官方的“everything”参考服务，调用一个工具，并在屏幕上打印令牌用量计算结果——无需 API 密钥，无需你的任何服务，也不会向磁盘写入任何内容。

功能介绍

工具：按需获取模式定义

完整模式会压缩为名称索引。需要某个工具时，mcptoon inspect 会获取它的实际参数，然后由 call 执行。你只需为一次列表查询付费，而不是每一轮都付费。

技能：一个常驻指针

不再需要加载整个目录。只需保留一行指针（39 个令牌），一次查询即可返回最相关的技能（791 个令牌）。视图采用链接（Windows 上使用联接，无需管理员权限），因此只需在源位置编辑一次，所有位置都会立即生效，也不会因存在第二份副本而出现内容不一致。

安装一次，处处共享

只需安装一次 mcptoon，机器上的所有 AI 就能使用你的全部工具和技能。之后添加的内容会立即生效——无需重启 Agent，也无需为每个 Agent 单独配置 JSON。

按自己的方式添加工具

mcptoon install brave-search --npm @modelcontextprotocol/server-brave-search
mcptoon install my-tool --pip mcp-my-tool
mcptoon install remote-api --url https://example.com/mcp
mcptoon add my-server --stdio npx -y @any/mcp-package
mcptoon install --list                       # see what's installed
mcptoon install --remove brave-search        # uninstall one

每个服务只需一条命令，可使用 npm / pip / HTTP。也可以让 mcptoon 扫描你已有的服务： mcptoon discover。

需要令牌的远程服务会从环境变量中读取令牌，因此凭据绝不会写入磁盘：

mcptoon install remote-api --url https://example.com/mcp \
  --header 'Authorization: Bearer ${BAIZHI_TOKEN}'   # BAIZHI_TOKEN set in your environment

${NAME} 会在请求时解析，因此配置、生成的处理程序和每条日志都会保留模板——轮换变量后，下次调用就会使用新值，无需重新安装。变量缺失或为空时会明确报错并指出变量名，绝不会发送空标头。

工具从何而来 — 搜索 17,000+ 个工具，一条命令即可安装

在新设备上，首先要问的不是“如何节省 token”，而是“我到底想要哪些工具”。过去的做法是去 GitHub 搜索 mcpServers 片段，再手动将它们复制到 JSON 中。

mcptoon 不附带任何工具，也不捆绑目录。它会查询上游注册表，因此你可以准确搜索所需内容：

mcptoon install --search github     # search, list only — nothing installed
mcptoon install --search postgres
mcptoon install github              # search and install

结果带有 ✓（注册表已验证）、类型标签（npm / pypi / hosted / remote）和调用次数。数据来自两个上游来源，实时查询，绝不存储：

为什么不捆绑任何内容：内置列表需要发布新版本才能更新，还会把别人的源代码引入你的供应链。mcptoon 只存储一个指针——搜索会在你自己的 ~/.mcptoon/config.json 中写入一行；第三方源代码绝不会进入 mcptoon。

然后将工具分发给每个 Agent：

mcptoon sync          # push the new tools to every detected agent
mcptoon manifest      # see every tool (name index, the cheapest view)

**如何解读结果：**索引中既有官方的 @modelcontextprotocol/* 服务，也有个人发布的软件包。✓ 表示注册表已验证该条目——这提醒你在提供凭据前先阅读源代码。

技能部分：skills search <query> 会查询开放技能索引（skills.sh）——按技能用途查找，然后用 skills add <git-url> 安装。mcptoon 安装的是你指定的仓库——目录本身就是开放生态。

**入门包：**如果你不想逐个挑选工具，有四个内置包——essentials、web-research、code-review、docs——每个包都包含一些工具和现成的提示词。mcptoon install --packs 会列出这些包；mcptoon install --pack essentials 会安装其中一个。两个研究包都不需要 API 密钥。

三种账单，以及为什么不能混为一谈

mcptoon 会在三个不同环节节省 token。比较这些环节中的数字毫无意义。

下方数据来自三个规模不同的目录——一个 255 个工具的合成样本（固定的核心基准）、一台包含 1,109 个工具的机器，以及你自己的机器上实际拥有的工具。不要将一种数据的百分比与另一种数据的 token 数量进行比较；每张表都会注明测量所用的目录。

“能省多少？”有两种解读方式，它们回答的是不同问题。网关数据——完整架构与 Agent 在默认 compact 暴露模式下实际加载的内容之间的对比——体现的是安装 mcptoon 带来的收益，也是诚实的核心指标（它会随目录规模变化：工具越多，节省越大）。精简架构数据（工具相同，描述更简洁）是较小的次要指标（88.5%），体现的是 manifest --slim 带来的收益。mcptoon status 会基于一次测量并排显示这两项数据，因此它们永远不会相互偏离。

账单 1 · 工具发现（manifest）：默认减少 99.2%

不带任何标志运行 mcptoon manifest，使用的就是这一档。想要更多？使用 --slim（名称加参数类型，8,282 tokens，−88.5%）或 --full（完整架构）。

账单 2 · 调用结果（call）：可选，--toon 可节省约 6%

这笔账在工具返回结果之后才产生。mcptoon call 默认输出 JSON，默认不会节省任何内容。添加 --toon 即可缩减结果。

Bill 3 · 技能目录（skills）：1,572,330 → 39 个常驻 + 每次查找 791

mcptoon skills manifest                      # 39 tokens, resident
mcptoon skills resolve "make a PDF" --k 5    # 791 tokens, the 5 most relevant

一张表，三种方式，数据来自编写此 README 的机器：

固定的主要基准测试数据——使用 tiktoken cl100k_base 对 50 个服务中的 255 个工具进行的合成样本。它并非你的目录数据；运行 mcptoon status 查看你自己的数据：

使用 mcptoon bench 测量你自己的目录（它会报告你的工具数据，而非此固定样本）。上面精确的三格式表格也可以复现——无需克隆仓库：

mcptoon manifest                 # populate the schema cache
python -m mcptoon.bench_tokens   # the same JSON / --slim / --compact counts, your tools

方法和基准： docs/tiktoken-benchmarks.md。

安装

pip install mcptoon

Linux（Debian/Ubuntu 23.04+，以及任何遵循 PEP 668 的发行版）和 macOS 上的 Homebrew Python。 在这些环境中，直接使用 pip install 将软件安装到系统 Python 中会被拒绝，并显示 error: externally-managed-environment。这是发行版在保护系统，并非 mcptoon 有问题。请改用以下方式安装：

pipx install mcptoon     # 隔离 CLI；推荐
# 或安装到由你管理的虚拟环境中：
python3 -m venv ~/.mcptoon-venv && ~/.mcptoon-venv/bin/pip install mcptoon

pip install --break-system-packages mcptoon 也能使用，但会将软件写入系统 Python 中——建议优先使用 pipx 或虚拟环境。在 Windows 上，直接运行 pip install mcptoon 即可。

# Run without installing (needs Node)
uvx mcptoon demo --quick

# Isolated CLI install (avoids the PEP 668 error on Linux / Homebrew Python)
pipx install mcptoon

# From source (for development)
git clone https://github.com/activeing123/mcptoon.git
cd mcptoon
pip install -e . --no-build-isolation

# Claude Code plugin
/plugin marketplace add activeing123/mcptoon

Nix

由 numtide/llm-agents.nix 打包——机器人会跟进每次 PyPI 发布，因此 flake 不会因手动更新而落后于版本：

# Run straight from the flake, no install step
nix run github:numtide/llm-agents.nix#mcptoon -- --help

该插件和技能也通过 sudosubin/agents.nix 提供，路径分别为 pkgs.agent-plugins.github.activeing123.mcptoon.<plugin-name> 和 pkgs.agent-skills.github.activeing123.mcptoon.<skill-name>。

适用于所有 AI Agent

mcptoon 通过两种方式连接 Agent，下面的每个客户端都属于其中一种。 你无需选择——quickstart 会同时注册两种方式，每个宿主会采用自己支持的方式：

• CLI 方式——Agent 自行运行 mcptoon。 任何能使用 shell 的工具（CLI Agent，或带终端的编码 IDE）都无需配置：它会运行 mcptoon call、mcptoon search、mcptoon skills resolve。不会向其中写入任何内容。
• serve 方式——客户端无法运行 shell。 聊天应用或 GUI 会改为挂载 MCP，因此只需添加一项：将 mcptoon serve 作为单个 MCP 服务。只需一行，配置在一处。

覆盖整个市场。 共 103 个客户端，名单来自 awesome-mcp-clients，以及后来发布的编码 Agent 的厂商文档；开发者库（mcp-agent、mcp-client-go）不在其中，因为用户不会运行这些库。每个客户端都单独核实——我们会说明实际验证过的内容，而非假设。

CLI 方式——42 个客户端，无需配置（它们自行运行 mcptoon）：

AdaL · Aider · Amazon Q Developer · auggie · Autohand Code CLI · Claude Code · Claude Code Open · ClaudeMind · Cline · Codex · ContextKit · Continue · Copilot CLI · Copilot-MCP · Crush · Cursor · Dexto · Dolphin-MCP · Enola · Gemini CLI · Goose · JDBCX · Junie · KiloCode · Kiro · McPico · MCPOmni Connect · mistral-vibe · Nerve · Octomind · opencode · OpenHands · PraisonAI · Qwen Code · Roo Code · Slack MCP Client · SwarmClaw · Trae · VS Code GitHub Copilot · Warp · Windsurf · Zed

serve 方式——61 个客户端，只需添加一项 mcptoon serve（无法使用 shell，因此会挂载 MCP）：

5ire · Agent Bridge · Agent-cli · AgentOne · AIaW · Ano · AnythingLLM · Argo-LocalAI · askit-mcp · AstrBot · BoltAI · BrowseWiz · Canvas MCP Client · CarrotAI · Chainlit · ChatMCP · Cherry Studio · Claude Desktop · console-chat-gpt · DeepChat · DocsGPT · eechat · Enconvo · Fastchat MCP · FLUJO · Glue · HyperChat · kibitz · Klavis AI · LangBot · LibreChat · LobeHub · Lutra · MCP Chatbot · MCP CLI client · MCP Playground · MCP Simple Slackbot · MCP SuperAssistant · MCPCLIHost · MCPHost · Memex · MindPal · NextChat · OpenClaw · oterm · Qordinate · Runbear · SeekChat · Simple AI · Superinterface · Tambo · Taskade · Tester MCP Client · Tiles Notebook · Tome · Vercade · WhatsMCP · Witsy · y-cli · Yume · Zin-MCP-Client

核实状态——sync --self 会向我们根据各宿主自身文档核实过的 12 个宿主写入一行连接配置；其他宿主均可通过 CLI 或 mcptoon serve 连接，无需宿主专属文件，因此无需逐一核实。

mcptoon 会在各主机上写入什么

mcptoon 是一个命令行工具——它是一个管理器，不是常驻代理或服务，也不是客户端库。你的 Agent 不会直接与上游 MCP 服务通信：它要么运行 mcptoon 命令，要么通过 mcptoon 自带的 MCP 入口（mcptoon serve）访问。对于需要写入文件的主机，具体会写入以下内容：

# Agent needs GitHub access mid-task? It just runs:
mcptoon add github --url https://api.githubcopilot.com/mcp/
# Done. No JSON editing. No restart. No lost context.

另一种方式是运行 mcptoon serve：将所有已配置的服务置于一个 MCP 端点之后，并提供连接池和每个 Agent 独立的密钥，供坚持使用代理的客户端接入。你不必二选一——命令行仍是主要入口；主机支持桥接时，也可以同时接入桥接。

为什么选择命令行，而不是代理

MCP 的前提是，每种能力都是一个 Agent 必须配置才能访问的服务——这意味着每增加一个新工具，就要为每个 Agent 编辑格式各异的 JSON 配置、重启所有程序，并在每个 Agent 中重新支付完整的架构成本。

命令行是每个 Agent 都已具备的唯一通用接口。而且，即使 mcptoon 还未发挥任何作用，单看这种形式，其成本就能显著降低：

• Firecrawl：同一任务通过命令行耗费 1,365 个 token，通过 MCP 耗费 44,026 个 token——相差 32 倍
• Scalekit：命令行成本低 10–32 倍，可靠率为 100%；MCP 的可靠率为 72%

代理模式也同样可用——mcptoon serve 会将所有已配置的服务置于一个 MCP 端点之后——而 quickstart 会在接入命令行的同时配置该模式，因此你无需二选一。本节介绍的是 mcptoon 的设计核心，并非你必须切换到的一种模式。

哪种模式最省钱？

mcptoon 有三种方式可以将工具交给 Agent，它们的成本差异很大。只有一种最省钱，而且新安装后默认并不会处于这种模式。（以下 token 数量基于包含 255 个工具的样本；你的目录会有所不同——运行 mcptoon mode 可查看你的数据。）

CLI 最省钱，因为闲置时成本为零。 不使用工具的轮次不产生任何成本，使用工具的轮次也只需几百个 token。serve 次之——每轮只需支付少量固定成本。安装了 mcptoon 却没有将其接入 Agent 时，你付出的就是 direct 模式的成本；新安装后默认也处于此模式，这就是为什么在运行 mcptoon quickstart 之前，mcptoon 可能让人感觉毫无存在感。

本 README 中的“99%”指的是定义侧的节省——无需加载所有工具架构。CLI 和 serve 都能做到；direct 则不行。结果压缩是另一笔成本（上文的成本 2），而且绝不是安装 mcptoon 的理由。

运行 mcptoon mode，了解你当前使用的模式以及每种模式在你的目录上的成本；运行 mcptoon statusline，打印单行状态徽章。

所有命令

mcptoon quickstart              # one-shot start (discover + configure + register the gateway)
mcptoon discover                # scan this machine for MCP servers (--write to keep, --health to probe)
mcptoon import                  # import servers from Claude Desktop / Cursor / Cline / Windsurf
mcptoon init                    # create a sample config (--auto to discover and fill it)
mcptoon list                    # show configured servers
mcptoon manifest                # all tool names (compact by default; 255 tools = 581 tokens)
mcptoon manifest --sort alpha|usage|recent       # order the list (usage = your most-called first)
mcptoon manifest --top 3 --verbose              # cap to N tools per server; --verbose adds descriptions
mcptoon inspect <server> <tool> # inspect one tool's schema
mcptoon search <query>          # search tools across servers
mcptoon select "<task>"         # top 3 tools for a task (past ~40 tools, models pick wrong)
mcptoon select "<task>" --top 5 # ...or how many you want
mcptoon call <server> <tool> '{"args":"here"}'   # call a tool
mcptoon call <server> <tool> ... --transport sse|streamable  # HTTP transport preference (default auto)
mcptoon exec python "print(len(open('big.log').readlines()))"  # run code; only stdout enters context
mcptoon exec python --file analyze.py            # same, from a script file
mcptoon exec --langs                             # what this machine can actually run
mcptoon openapi list <spec>                      # any OpenAPI/Swagger REST API as commands
mcptoon openapi call <spec> <cmd> pet-id=2       # call one operation (params: name=value)
mcptoon openapi call <spec> <cmd> --base-url U   # override the server (prod vs staging)
mcptoon openapi call <spec> <cmd> --cache-ttl 0 --cache-key v2  # re-fetch the spec; keep versions apart
mcptoon graphql list <endpoint>                  # any GraphQL endpoint as commands
mcptoon graphql call <endpoint> <cmd> --fields "name id"  # one query/mutation
mcptoon auth login <name> --auth-url U --token-url U --client-id ID  # OAuth (PKCE)
mcptoon auth creds <name> --token-url U --client-id ID  # OAuth client credentials
mcptoon auth login <name> ... --register REG_URL --client-name mine  # DCR (RFC 7591) — no client-id needed
mcptoon openapi call <spec> <cmd> --auth oauth:<name>   # use a stored token
mcptoon resources list [server]                  # list a server's MCP resources
mcptoon resources read <server> <uri>            # read one resource by URI
mcptoon prompts list [server]                    # list a server's prompt templates
mcptoon prompts get <server> <name> a=1          # render a prompt with arguments
mcptoon complete <server> <ref>:<arg>=<prefix>   # ask the server to finish a value
mcptoon bake create <name> --openapi <spec>      # save a connection under a name
mcptoon bake create <name> --openapi <spec> --auth-header 'K: env:VAR'  # secret by reference only (env:/file:)
mcptoon bake run <name> <action> ...             # reuse a saved connection
mcptoon bake install <name> --bin ~/.local/bin   # write a launcher that only carries the bake name
mcptoon add <name> --stdio|--http <cmd|url>     # add any MCP server
mcptoon remove <name>           # remove a server
mcptoon install <name> --npm|--pip|--url <pkg>  # install + auto-generate handler
mcptoon install --search <kw>   # search the live registries (nothing installed)
mcptoon update                  # refresh each server's cached tool surface; report what moved
mcptoon upgrade                 # update mcptoon itself to the latest PyPI release
mcptoon plugin install <dir>    # install an Agent Plugins 1.0.0 plugin
mcptoon sync                    # sync native config to every detected agent
mcptoon health                  # health-check every MCP server
mcptoon serve                   # run as an MCP server (stdio/HTTP)
mcptoon skills list             # list the skill catalog (--usage adds hit counts)
mcptoon skills sync <src>       # distribute a skill catalog to every agent's folder
mcptoon skills resolve "<task>" # BM25 shortlist of skills (offline, no LLM)
mcptoon docs index <dir>        # index a Markdown tree so agents stop reading it whole
mcptoon docs resolve "<query>"  # best files for a query — returns paths (offline)
mcptoon docs list               # every indexed document, by slug
mcptoon docs doctor             # check the docs index against the disk
mcptoon kb index <path>         # index documents so you can search INSIDE them
mcptoon kb fetch <url>          # fetch a URL and index it (24h TTL cache)
mcptoon kb search "<query>"     # ranked passages, not whole files (porter + trigram, RRF)
mcptoon kb list                 # indexed sources with size and age
mcptoon kb stats                # chunks, DB size, trigram support
mcptoon session                 # what happened this session (catch up after a compaction)
mcptoon bench                   # prove the savings on this machine (tools + skills, one table)
mcptoon demo                    # one command, live demo on your machine
mcptoon demo-server             # the same proof with zero downloads (11 stdlib tools)
mcptoon doctor                  # self-check: Python, config, connectivity
mcptoon status                  # one screen: what's configured, gateway wired, tokens saved
mcptoon stats                   # token-savings dashboard (vs raw JSON)
mcptoon report                  # the whole savings account: tools + skills + cumulative
mcptoon savings                 # milestones you've crossed (1B? ~12,000 novels?)
mcptoon credit                  # one screen: your mode, what it really saves, one action
mcptoon mode                    # which delivery mode you're in (cli/serve/direct) and what each costs
mcptoon statusline              # one-line savings badge for a status bar or turn header
mcptoon usage                   # local call statistics
mcptoon activity                # who used mcptoon, when, on what (last 20 calls)
mcptoon footer-facts            # one line of savings for a chat footer (never blocks)
mcptoon retrieve <handle>       # get back the original behind any --smart handle
mcptoon config                  # show gateway settings (footer, welcome, lang)
mcptoon toggle <server> <tool>  # enable/disable a single tool (--list to show all)
mcptoon policy                  # per-tool compression policy (raw / toon / slim)
mcptoon completion ps           # shell completion (bash/zsh/fish/powershell)
mcptoon off                     # remove the gateway entry from your agents (reversible)
mcptoon restore                 # drop the gateway and put your servers back
mcptoon uninstall               # full cleanup — prints the plan first (--dry to preview)

完整参考文档见 DEVELOPERS.md。

格式系列：四个级别，默认使用紧凑格式

所有选项均可选；默认格式已经是最精简的级别。

为什么默认使用 compact？ 选择要使用哪个工具只需要名称（255 个工具共 581 个 token）；参数详情只在调用时才有用，因此按需获取即可。默认使用完整架构会把节省的 99.2% 全部抵消。

给 Agent 的规则：用 manifest 选择工具，调用前先用 inspect 查看。 在 41 个真实工具上进行的测量显示：仅凭名称猜测参数的 Agent，成功调用率约为 10%；而每轮只对实际会用到的 2–3 个工具运行一次 inspect 的 Agent，成功率可达 100%——与注入所有架构的效果相同，成本却低得多。

信任与安全

它只是一个 534KB 的原生 CLI——随时可以删除；留着它，你就再也不必为任何 Agent 配置工具或技能。 mcptoon 会接触你的 Agent 配置，因此它从设计之初就注重透明，也让你可以轻松弃用。

每次工具返回结果后、Agent 看到结果前，都会经过以下三道防护：

• 可撤销。 mcptoon restore 可撤销接管（移除网关并恢复你的服务）；mcptoon off 只会移除网关条目；mcptoon uninstall --dry 会先打印完整的卸载计划。除非你主动要求，否则绝不会删除你的服务。
• 无遥测。 不收集分析数据，不发送崩溃报告，也不会向外发送任何信息。
• 本地优先。 你的工具、技能和文件都会留在你的机器上。唯一会向外发送信息的是 install --search，它会向注册表请求目录列表，但绝不会发送你的数据。
• 不存储凭据。 API 密钥会直接从你的配置或环境传递。
• 无依赖。 仅使用 Python 标准库——供应链中没有需要审查的内容。 CI 会通过 scripts/check_zero_deps.py 强制执行这一要求。
• 无守护进程。 纯 CLI——没有常驻进程，也不监听端口。
• 格式不会破坏兼容性。 线缆协议始终是标准 JSON-RPC； compact/slim/toon 只影响 mcptoon 输出给 Agent 的内容。如果 --toon 解码失败， 就会回退到 JSON；传入一次 --full 即可恢复原生架构。不会被锁定。

一句话概括范围： mcptoon 是一个索引和配置管理器——它会指向每个工具各自的源，你可以按照自己的方式审查这些源。

致谢与参考

• TOON 标准 — v4.1（MIT），引用自 python-toon，并在 NOTICE 中注明
• ToonDeck — mcptoon 的图形控制台 （预 Alpha 版）：使用同一引擎，通过点击而非输入命令来操作

开发者： mcptoon 是由 @activeing123 维护的独立第三方项目。它与 Anthropic 没有任何关联。

贡献

git clone https://github.com/activeing123/mcptoon.git
cd mcptoon
pip install -e . --no-build-isolation
pip install pytest pytest-cov
python -m pytest tests/ -v   # 3013 passed, 2 skipped

三条硬性规则：零依赖（由 CI 强制执行）、新行为必须附带测试、Windows 是一等支持目标。初次参与？请从 CONTRIBUTING.md 和 DEVELOPERS.md 开始。

代码库：56 个模块，共 41,144 行 Python 代码，零第三方依赖。

支持

遇到错误？故障排除与常见问题 涵盖常见问题 （Server 'X' not configured、skills sync 的误删防护、未知 命令/选项的退出代码、保存进度为何显示为 99% 而非 100%，以及过时的技能 计数）。

mcptoon 是一个由个人维护的业余项目，对个人用户始终免费。如果它帮你降低了 上下文费用：

• 在 GitHub 上赞助 — 一次性赞助或按月赞助。
• 为仓库点星 — 其他开发者就是通过这种方式发现小工具的。

团队功能尚未开发。 将一份共享服务列表同步到每位队友的机器；记录各项内容何时被加载。目前没有定价方案，也没有等候名单页面——发邮件至 [email protected] 即可推动这项功能排到更前面。

许可证

Apache 2.0。请参阅 LICENSE 和 NOTICE。