ATR: Automation for Token Reduction

ATR：缩减 Token 的自动化工具

ATR 让 AI 在使用工具时消耗更少的 token。 消耗更少的 token，意味着费用更低，也能减少“已达到使用限额”的提示。

它适用于 Claude Code、Codex、Claude Desktop、Cursor、Windsurf、claude.ai 和 ChatGPT。它免费，并在你的电脑上运行。

问题所在

AI 使用工具（GitHub、浏览器、数据库、测试运行器）时，有两件事会浪费 token：

1. 每条消息都会发送所有工具的说明， 即使 AI 根本不会使用这些工具。十个 MCP 服务在你输入任何内容之前，就可能占用 10,000 多个 token。
2. 工具返回的结果很庞大。 GitHub issue 列表、网页或测试运行结果可能包含数万个 token，而这些内容全都会进入聊天记录。

ATR 的作用

ATR 位于 AI 应用和工具之间：

• 隐藏工具列表。 AI 只会看到几个精简的 ATR 工具，并在需要时搜索所需工具。
• 缩减结果。 在 AI 看到结果之前，ATR 会去除冗余内容，保留重要信息。测试运行失败时会保留失败项并删除通过的测试；网页会保留文本和链接并去掉页面布局。
• 不会丢失任何内容。 ATR 删除内容时，会保留完整结果，AI 可以随时请求查看其中任意部分。

  Your AI app (Claude Code, Codex, Claude Desktop, …)
          │  sees a few small ATR tools instead of every tool
          ▼
        ATR  ← finds the right tool, runs it, shrinks the result
          │
          ▼
  Your MCP servers (GitHub, Playwright, Postgres, Slack, …)

---

开始使用

你需要 Python 3.11 或更高版本。

pip install atr-mcp
atr setup

atr setup 会查找电脑上的 AI 应用，向你展示将进行的更改，并先征求你的同意。然后它会：

1. 将 MCP 服务移到 ATR 后方；并且
2. 将 ATR 添加到每个应用中。

重启应用即可完成。

命令	作用
atr setup --dry-run	显示计划，但不进行任何更改
atr setup --undo	将所有应用恢复到原来的状态
pip install --upgrade atr-mcp	更新 ATR

atr setup 更改的每个文件都会有一份备份（.atr-backup）。

只想试试看？

此演示会连接一个包含 50 个工具（GitHub、Slack、日志、数据库）的虚拟服务。任何数据都不会离开你的电脑。

claude mcp add atr -- atr serve --demo        # Claude Code
codex mcp add atr -- atr serve --demo         # Codex

让 AI “列出未关闭的 GitHub issue”，然后让它 “显示 ATR 统计信息”，即可查看它节省了多少 token。

---

节省效果

实测

我们让 AI Agent 分别在使用和不使用 ATR 的情况下执行相同的浏览器任务：打开 Hacker News，点击“new”，然后打开 GitHub issues 页面。每种配置运行 3 次，且每次回答都正确。

Agent	不使用 ATR	使用 ATR
Claude Code	每项任务 $0.237，13 轮	每项任务 $0.110，10 轮（便宜 54%）
Codex	84k token（按全价计算为 33k）	134k token（按全价计算为 18k）

Codex 的结果不一：使用 ATR 后，按全价计算的 token 数约减少了一半，但 token 总数更多。

单项结果

使用 python -m benchmarks.bench_atr 测量 AI 接收内容的 token 数：

结果	不使用 ATR	使用 ATR	节省比例
1,000 个 GitHub issue	429,203	879	99.8%
2,000 行服务器日志	61,072	208	99.7%
有锁文件更改的 git diff	22,294	207	99.1%
浏览器中的网页（Hacker News）	12,023	4,046	66%
每条消息中 50 个工具的说明	12,056	1,508	87.5%
pytest -v，303 个测试，3 个失败	6,685	675	90%
pip install，60 个包	5,977	697	88%

每种情况下，重要内容都会保留下来：错误、失败的测试、更改过的代码行、页面文本和链接。

ATR 何时有用，何时无用

• 效果最好： 你使用会返回大量结果的 MCP 服务，例如 GitHub、浏览器（Playwright）、数据库、日志或网页。
• 有些效果： 不使用 MCP 服务，仅在 Claude Code 或 Codex 中进行常规编码。这些应用已经会精简自己的命令，因此在我们的测试中，ATR 在这种情况下没有效果。
• 无法改善： 聊天记录和 AI 自己的回复。MCP 服务只能看到工具调用，无法看到对话内容。

---

ATR 的工具

AI 会使用这些工具。你无需亲自调用。

用于你的 MCP 服务

工具	功能
atr_find_tools	搜索你所有服务的工具，并返回少数适合当前任务的工具
atr_read	运行只读工具，并精简结果
atr_call	运行会更改内容的工具（你的应用可以先征求你的同意）
atr_query	读取被截断结果的更多内容，例如某一页、某个字段或某次搜索

用于编码

工具	替代操作
atr_repo_map	逐个打开文件来了解项目
atr_search_code	翻阅数页搜索结果
atr_read_file	读取整个文件以查看某个函数。若 AI 两次读取同一部分，它还会提示“未更改”
atr_diff	查看充斥着 lockfiles 的完整 git diff
atr_run	查看数千行测试或构建输出
atr_stats	显示 ATR 节省了多少 token

---

安全

• **绝不会读取、搜索或显示机密信息，**包括 .env 文件、私钥、云凭据，以及类似 api_keys.json 这样的文件。这也适用于 ATR 后面的工具和 atr_diff。
• **读取和更改是分开的。**只读工具通过 atr_read 运行。任何会更改内容的操作都通过 atr_call 运行，因此你的应用可以在运行前征求你的同意。atr_run（shell 命令）始终会征求同意。
• **文件仅限于允许的文件夹。**文件工具只能访问设置中列出的文件夹。

---

在 claude.ai 或 ChatGPT 中使用 ATR

这些应用只能连接互联网中的服务，因此 ATR 需要一个公开链接。

pip install "atr-mcp[http]"
atr serve --http                               # prints a link with a secret in it
tailscale funnel --bg 8789                     # a permanent public https link (or: cloudflared tunnel --url http://127.0.0.1:8789)

添加 https://<your-link>/mcp/<secret> 作为连接器：

• **claude.ai：**Settings → Connectors → Add custom connector（无需登录）
• **ChatGPT：**Settings → Apps & Connectors → developer mode → create a connector（无需登录）

**请妥善保管此链接。**任何拥有此链接的人都可以使用你的工具。除非使用 --read-files 和 --allow-run 开启，否则通过互联网无法读取文件或运行 shell 命令。若要更改密钥，请删除 ~/.atr/http_token。

---

设置

atr setup 会为你写入这些内容。你也可以自行编辑 ~/.atr/config.json：

{
  "servers": {                          // the MCP servers ATR runs for you
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
  },
  "budget": 1500,                       // most tokens one result may use
  "level": 2,                           // 1 = keep almost everything, 3 = shrink hard
  "pin": ["github__create_issue"],      // tools to always show (skips the search step)
  "read_only": ["github__list_*"],      // tools that only read, if a server doesn't say so itself
  "read_roots": ["~"]                   // folders the file tools may open
}

---

更多信息

完全不使用 MCP？atr compress 可以在你将文件或剪贴板内容粘贴到任意聊天中之前，先将其精简：

atr compress dump.json --copy
pbpaste | atr compress --copy

手动设置：atr init 会写入设置文件，atr snippet 会打印需要添加到应用 MCP 配置中的条目。

**macOS 上出现“No module named 'atr'”：**运行 chflags nohidden .venv*/lib/python*/site-packages/*.pth，或使用 atr snippet 输出的条目。

限制：

• 需要登录（OAuth）的在线服务暂时无法接入 ATR，因此 atr setup 会将它们保留在你的应用中。
• ATR 会降低每条消息的成本，但不会更改你方案的限额。

---

面向开发者

git clone https://github.com/JacobBhatt12/atr && cd atr
pip install -e ".[dev]"
python -m pytest atr/tests -c /dev/null       # 44 tests
python -m benchmarks.bench_atr                # the savings table above

文件	内容
atr/server.py	你的应用所连接的 MCP 服务
atr/remote.py	通过互联网提供相同服务的版本（atr serve --http）
atr/downstream.py	与 ATR 后面的 MCP 服务通信
atr/compress.py	精简结果
atr/stash.py	为 atr_query 保存完整结果
atr/router.py	工具搜索
atr/code.py	编码工具
atr/setup.py	atr setup

**接下来：**记住重复的工具调用，避免重复发送相同结果；支持在线服务登录；并提供一个小型本地模型，在截断长文本会导致语义丢失时对其进行摘要。

许可证：MIT