Token Guardian MCP

Token Guardian 是一个本地只读 MCP 服务器，用于发现 Claude Code 和 Codex 的 token 浪费，而不会降低任一客户端的智能水平。

它执行两项任务：

• 报告哪些代理、模型和会话处理的 token 最多。

• 针对特定任务推荐最便宜的安全模型和努力级别。

它还包含一个用于测试提示优先路由的 route-task 命令（干运行模式），在 MCP 注册到任何地方之前即可使用。

严格安全边界

Token Guardian 无法更改模型设置、努力级别、上下文限制、压缩、MCP 注册或正在运行的会话。它没有模型凭据，也不进行付费 API 调用。

usage 工具使用 --offline 和 --no-cost 参数调用 ccusage。Codex 标题是通过 sqlite3 -readonly 读取的可选元数据。每个 MCP 工具都被标记为只读、非破坏性、幂等且封闭世界。

Related MCP server: token-pilot

工具

token_guardian_usage_snapshot

读取一到三十天的本地使用情况，并返回：

• 按代理和模型统计的总量

• 缓存读取、输出和前沿模型占比

• 最大的会话

• 完全重复的 Codex 工作标题

• 有证据支持的快速改进点

处理的 token 是工作负载诊断指标。它们不等同于订阅计量，尤其是在缓存输入占主导地位时。

token_guardian_recommend_route

接受客户端、任务、风险和当前上下文大小。它返回模型、努力级别、原因以及可选的前沿验证器。

该策略在失败时采取保守措施。安全、架构、生产、破坏性、高风险、关键或模糊的工作仍由前沿模型处理。廉价模型处理有边界的机械性工作。平衡模型处理常规编码和调试，必要时进行前沿审查。

测试提示优先路由

构建项目，然后从任意文件夹运行路由器：

node ./dist/route-cli.js --client codex --prompt "Implement a bounded TypeScript parser with tests." --cwd .

工作文件夹不必是仓库。路由器主要使用提示。它会检查当前文件夹中最多 256 个名称以获取可选的项目标记，但不会打开文件内容或扫描子文件夹。

该命令仅打印推荐和会话范围的启动命令。它不会运行该命令、更改配置、注册 MCP 或触及活动会话。诸如 yeah, test that 之类的模糊延续提示会保留在前沿路由上，因为它们的真实上下文缺失。

本地要求

• Node.js 24 或更新版本

• ccusage 在 PATH 中

• sqlite3 在 PATH 中（用于可选的 Codex 线程标题）

构建和测试

npm install
npm test
npm run typecheck
npm run build

运行构建好的 stdio 服务器：

node dist/index.js

在不注册到活动客户端的情况下检查它：

npx @modelcontextprotocol/inspector node dist/index.js

注册状态

此首次构建特意未注册到 Claude、Codex 或共享的 Kitsune 网关。注册以及任何客户端重启是在独立服务器被接受后的单独更改。

许可证

MIT。参见 LICENSE。