LuminariSoftwares/tool-guardian

Tool Guardian

你的 MCP 服务器，只需约 300 个 token 而非约 28,000 个 —— 并且工具结果不再淹没上下文窗口。

为什么 ·
两种运行方式 ·
安装 ·
测量它 ·
输出阶梯 ·
DSH 捆绑包 ·
更新日志

一个 MCP 服务器，它位于你其他 MCP 服务器的前面，只暴露三个通用工具而非数十个特定工具——按需发现其余工具——这样工具定义就不会在模型读到第一个字之前就吃掉你的上下文窗口。

Context Guardian 的配套工具：Context Guardian 在窗口填满之前压缩对话；Tool Guardian 从一开始就防止工具填满窗口。 同一个问题的两个部分。

| | 没有 Tool Guardian | 有它 |
|---|---|---|
| 在 32K 模型上运行 7 个 MCP 服务器 | 每次请求 28,689 个 token 的 schema（占窗口的 87.6%） | 约 300 个 token；仅在模型请求时才获取 schema |
| 一个 50 KB 的 shell 结果 | 51,165 个字符进入对话 | 7,833 个字符，完整原文已归档，一次调用即可获取 |
| DSH 首次请求（实测） | 46 个工具，37,154 个字符的 schema | 22 个工具，18,503 个字符 |
| 后端启动失败 | 模型默默绕过的空工具列表 | 带有真实错误的 UNKNOWN |

为什么存在这个项目

MCP 工具定义会在每一次请求中重新发送，无论模型是否使用它们。几个服务器通常就会达到数万个 token——往往占据小型本地模型窗口的大部分——而且是在第一条用户消息之前。在一个真实配置中，七个 MCP 服务器达到了 28,689 个 token，占 32K 窗口的 87.6%，作为其他一切之下的固定底线。

如今你有两种方式应对，而两者都有代价：

| 方法 | 代价 |
|---|---|
| 加载更少的 MCP 服务器 | 你完全失去了该能力 |
| 忍受它 | 在你输入之前，三分之二的窗口就没了 |
Tool Guardian 是第三种选择，而且不花这两种代价。它代理你所有的服务器，只向模型展示三个工具，外加一份服务器名称的单行目录（约 300 个 token）。工具的完整 schema 只有在模型请求时才会被获取：

list_capabilities(server?)      每个工具一行——名称和用途
describe_tool(server, tool)     某一个工具的完整参数 schema
call_tool(server, tool, args)   调用它，返回结果

和搜索索引的思路一样：廉价目录始终可见，细节按需获取。

模型要求（切换前请先读这里）

整个设计都建立在一个行为之上：模型必须在需要工具时主动调用 list_capabilities（然后调用 call_tool）。能力强的/前沿模型能可靠地做到这一点。较小的本地模型往往做不到——面对任务时，它们会去用内置工具（Bash/Read/shell）或写脚本，从不打开目录，因此那些隐藏的工具根本不会被触及。

这一点在 2026 年针对一个真实的工作室技术栈做过直接测量：gpt-oss:20b 和 qwen3-30b-a3b 在普通任务上都绕过了路由器——即使每个结果里都有 NEXT STEP 提示，而且还有一个专门的路由子代理在引导它们。它们要么把工具名当成 shell 命令，要么用脚本绕过去。token 计算完全成立；只是模型不肯驱动它。

所以：--selftest 能证明节省以及你的后端能启动——它不能证明你的模型会使用路由器。在正式采用前，用你实际的模型测试发现→调用流程。 如果它不能可靠地调用这三个工具，那么与其把所有东西都路由到一个模型从不打开的目录后面，不如暴露一小部分精选的、可见的服务器。这里的好处是真实的，但它是给那些会主动询问的模型的好处。

两种运行方式

它是一个仓库和一个 Python 路由器。选择与你的 harness 匹配的前门——两者都持续支持。

| | MCP 服务器（任何 MCP 客户端） | 原生 DSH bundle |
|---|---|---|
| 适用于 | Claude Code、Claude Desktop、OpenClaude、Cursor，任何通过 stdio 使用 MCP 的客户端 | DeepSeek Harness |
| 安装 | pip install tool-guardian | dsh plugin --profile  add dsh-tool-guardian |
| 将 MCP schema 隐藏在 3 个路由器工具之后 | 是 | 是，原生注册 |
| 结果上的输出阶梯 | call_tool 的结果 | 每个工具的结果（bash、grep、web_fetch……） |
| 带 token 价格的工具组 | list_groups_with_costs | 外加 activate_group，而且 DSH 自带的内置工具也可以被分组和隐藏 |
| 能注意到某个 shell 调用在做路由器工具的活 | — | 记录、提醒或拒绝 |
| 配置方式 | tool-guardian.json + TOOL_GUARDIAN_ 环境变量 | tool-guardian patch 行或 DSH 设置；相同的环境变量优先 |

flowchart LR
A["你的代理（Claude Code、DSH、任何 MCP 客户端）"] -->|"3 个工具，约 300 token"| B["Tool Guardian"]
B -->|"按需"| C["filesystem"]
B -->|"按需"| D["git"]
B -->|"按需"| E["n8n、数据库、..."]
B -. "大结果" .-> F[("archiveretrieve_spill")]
B -->|"整形后的结果"| A

它所在的位置

你的 CLI / agent（Claude Code、OpenClaude、任意 MCP 客户端）
-> Tool Guardian          （本项目 — 一个 MCP 服务器）
-> 你真正的 MCP 服务器（filesystem、git、n8n、数据库、...）

你把客户端指向一个 MCP 服务器——Tool Guardian——并把原本要交给客户端的同一份 mcpServers 配置交给 Tool Guardian。它会启动你的服务器、让它们保持热启动，并按需代理调用。

安装

pip install tool-guardian

纯标准库——无需安装其他任何东西。

配置

Tool Guardian 读取标准的 mcpServers 块（与 Claude Desktop / Claude Code 及大多数 MCP 客户端使用的结构相同）：

{
"mcpServers": {
"files": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
},
"git": {
"command": "uvx",
"args": ["mcp-server-git"],
"description": "git status / diff / commit / log"
}
}
}

可选的每服务器 "description" 会丰富模型所看到的目录。若没有，则会在启动时从该服务器自身的工具名称推导出提示。

配置按以下顺序搜索：--config PATH、$TOOL_GUARDIAN_CONFIG、./mcp.json、./.mcp.json、~/.tool-guardian/mcp.json。

环境与 .env

Tool Guardian 会自行加载 .env，并展开你后端参数中的变量，
这样密钥就不必由启动它的任何程序导出到环境中。

- .env 自动加载。 启动时它会按以下顺序查找 .env：显式路径、
$TOOL_GUARDIAN_ENV，然后进行向上搜索——从配置文件所在目录
（或当前工作目录）开始，向上最多遍历 5 层父目录，加载找到的第一个
.env。这样你的配置可以放在嵌套文件夹中，而 .env 位于项目根目录。
真实环境中已有的值优先于文件中的值；.env 缺失时不做任何操作，
绝不报错。

示例——配置嵌套在项目下，.env 位于根目录：

myproject/
├── .env                  未找到
2. myproject/config/.env        -> 未找到
3. myproject/.env               -> 找到  （在此停止）

- 变量展开。 ${VAR}、$VAR 和 %VAR% 会从环境中展开到每个
后端的 args 中；未知变量保持原样。
把密钥放在 .env 中，并在后端参数中引用它：

"args": ["-y", "mcp-remote", "https://app.openseo.so/mcp",
"--header", "Authorization: Bearer ${OPENSEO_API_KEY}"]

运行
将你的 MCP 客户端指向 Tool Guardian，作为一个单一的 stdio 服务器：

{
"mcpServers": {
"tool-guardian": {
"command": "tool-guardian",
"args": ["--config", "/path/to/your/mcp.json"]
}
}
}

你的服务器能做的所有事情仍然可以触达——模型只是分两步来发现它（list_capabilities → call_tool），而不是一开始就为全部内容付出代价。

看看它能省下什么

tool-guardian --selftest

启动你配置的服务器，打印目录，并报告三个路由工具所消耗的 token 与直接加载每个服务器工具相比的差异——例如 “路由工具消耗约 310 个 token，而其背后的完整集合约需 28,700 个 → 每次请求释放约 28,390 个。”*

它也让工具结果保持小巧（0.3.0）

定义是问题的一半；一份 40 KB 的构建日志是另一半。现在每个 call_tool 结果在模型看到之前都会经过一个确定性的输出阶梯：

| 结果 | 模型得到的内容 |
|---|---|
| 低于约 1.2k 字符，或来自 read 类工具 | 原样保留，逐字节不变 |
| 超过 300 字符的错误 | 头部 + 尾部摘要 |
| JSON 数组 / CSV ≥ 10k | 键、首尾项、计数 |
| shell 风格输出 ≥ 8k | 头部、均匀间隔的采样（带行号）、尾部——[exit code: …] 始终保留 |
| 统一 diff | 每一处变更，加上紧邻的上下文 |
| 其他任何 ≥ 1.2k 的内容 | 无损清理：去除 ANSI、折叠连续空行、统计重复行 |

没有任何东西会被静默丢弃。 在任何有损步骤之前，完整原文都会被归档，结果会用一行说明这一点，模型可以调用 retrieve_spill(id, grep=…) 将其读回。如果归档无法写入，则改为返回原文。相同输入，相同输出，始终如一——因此提供商的提示缓存能持续命中。TOOL_GUARDIAN_LADDER=0 可将其关闭。

list_groups_with_costs 会以上下文 token 为单位为每个工具组定价，并且每次路由调用都会被记录（参数值从不记录）到 ~/.tool-guardian/calls.jsonl，这样你就能衡量你的模型是否真的在使用路由器。

原生 DeepSeek Harness（DSH）捆绑包

同一个仓库也是一个可安装的 DSH 捆绑包，dsh-tool-guardian。Python 路由器保持不变——该捆绑包是通向它的桥梁，而非重写，并且上面的 MCP 服务器继续可用。

dsh plugin --profile  add dsh-tool-guardian        # 或指向某个检出目录的路径（先在其中运行 pnpm install）
dsh --profile  --dump-config                        # 显示一个 "# == dsh-tool-guardian" 层
在 DSH 内部，它 (1) 原生地注册路由器工具，因此除非你激活它们的组（activeGroups，或 activate_group 工具，该工具会先报出 token 成本），否则你的 MCP 后端的 schema 永远不会进入请求；(2) 通过 tools/post-execute 对每一个工具的结果运行输出阶梯——bash、grep、web_fetch，所有工具——因此不要在旁边挂载 dsh-trim；(3) 察觉那些做了路由器工具工作的 shell 调用，并记录、提醒（默认）或拒绝它们（bypass.mode）。在配置文件的 cordis.patch.yml 中通过覆盖 tool-guardian 行来配置它，或通过 DSH 设置命名空间 tool-guardian 来配置；现有的 TOOL_GUARDIAN_ 环境变量优先于两者。Python 的查找顺序是 $TOOL_GUARDIAN_PYTHON，然后是包旁边的 .venv，然后是 PATH 上的 python/python3（3.9+，仅标准库）。

结果塑形设计遵循 dsh-trim（shuistama，MIT）：先 next()，失败时放行，在任何有损操作之前先归档。

设计说明（真正重要的部分）

- 失败是响亮的，这是有意为之。 路由器是单点故障：没有路由器时，一个坏掉的服务器只让你损失那一个服务器；在路由器后面，它可能让你损失所有服务器。因此，无法访问的后端会被报告为 UNKNOWN 并附上其真实错误，绝不会报告为空工具列表。一个请求服务器却得到 [] 的模型会断定该能力不存在，并悄悄地绕过它——这正是要避免的失败。
- 为模型而构建，而不仅仅为机器。 它接受工具的 args 为对象或 JSON 字符串，为模型实际发送的近似错误取别名（query/name → server），并在每个结果末尾附上要调用的具体 NEXT STEP——因为一个收到目录却没有指令的模型往往会停在那里，而不是完成任务。
- 目录会列出你的服务器名称。 三个未命名的通用工具让模型没有理由相信任何能力存在，于是它就会即兴发挥。在工具描述中命名服务器只花费几个 token，却是模型会打开的目录与它会忽略的三个工具之间的区别。

它尚不*做的事

- 仅支持 stdio 服务器。 HTTP/SSE 服务器（"url" 条目）会被报告为 UNSUPPORTED——请直接加载它，而不是通过这里。
- 它不会合并或重命名工具；它忠实地代理它们。call_tool(server, tool, args) 原样到达真正的工具。

开发

pip install -r requirements-dev.txt
pytest

致谢

- dsh-trim（shuistama，MIT）——结果塑形监听器的形态：先调用 next()，失败时放行，在任何有损操作之前先归档。Tool Guardian 的阶梯是一个独立的 Python 实现；不包含任何 dsh-trim 代码。
- DeepSeek Harness——DSH 侧所构建于其上的 bundle 格式以及 tools/pre-execute / tools/post-execute 接缝。
- 模型上下文协议 —— mcpServers 配置结构是他们的，原样使用，因此你现有的配置可以正常工作。

许可证

MIT —— 参见 LICENSE。