ATR: Automation for Token Reduction

ATR：トークン削減の自動化

ATRを使うと、AIがツールを使うときのトークン数を減らせます。 トークン数が減れば、料金が下がり、「使用制限に達しました」というメッセージも表示されにくくなります。

Claude Code、Codex、Claude Desktop、Cursor、Windsurf、claude.ai、ChatGPTで動作します。無料で、お使いのコンピューター上で実行できます。

問題点

AIがツール（GitHub、ブラウザー、データベース、テストランナーなど）を使うと、2つの点でトークンが無駄になります。

1. AIが一度も使わないツールも含め、すべてのツールの説明がメッセージごとに送信されます。 MCP サーバーが10個あると、何も入力する前から10,000トークン以上になることがあります。
2. ツールの結果は膨大です。 GitHubの課題一覧、ウェブページ、テストの実行結果は数万トークンに及ぶことがあり、そのすべてがチャットに送られます。

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課題を一覧表示して」 と頼み、続けて 「ATRの統計を表示して」 と頼むと、削減されたトークン数を確認できます。

---

削減量

実環境でのテスト

同じブラウザータスクを、ATRあり・なしでAIエージェントに実行させました。Hacker Newsを開き、「new」をクリックしてから、GitHubの課題ページを開くタスクです。各構成で3回実行し、すべての回答が正解でした。

エージェント	ATRなし	ATRあり
Claude Code	1タスクあたり$0.237、13ターン	1タスクあたり$0.110、10ターン（54%安）
Codex	84kトークン（通常料金の対象は33k）	134kトークン（通常料金の対象は18k）

Codexでは結果が分かれています。ATRを使うと通常料金の対象となるトークン数は約半分になりますが、総トークン数は増えます。

個別の結果

AIが受け取るトークン数を、python -m benchmarks.bench_atrで測定しました。

結果	ATRなし	ATRあり	削減率
GitHubの課題1,000件	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が役立つ場合と、そうでない場合

• 特に役立つ場合： GitHub、ブラウザー（Playwright）、データベース、ログ、ウェブページなど、大量の結果を返すMCP サーバーを使用している場合です。
• 少し役立つ場合： MCP サーバーを使わず、Claude CodeやCodexで通常のコーディングをする場合です。これらのアプリはコマンドをすでに短縮しているため、私たちのテストではATRを使っても変化はありませんでした。
• 役立たない場合： チャット履歴やAI自身の返信です。MCP サーバーに見えるのはツール呼び出しだけで、会話の内容は見えません。

---

ATR のツール

AI はこれらを使用します。自分で呼び出す必要はありません。

MCP サーバー向け

ツール	機能
atr_find_tools	すべてのサーバーのツールを検索し、タスクに合うものをいくつか返します
atr_read	読み取り専用のツールを実行し、結果を短くします
atr_call	何かを変更するツールを実行します（アプリから事前に確認できます）
atr_query	切り詰められた結果の続きを読み取ります。たとえば、1 ページ、1 フィールド、または検索結果を取得します

コーディング向け

ツール	代わりに使うもの
atr_repo_map	プロジェクトを把握するためにファイルを 1 つずつ開くこと
atr_search_code	大量の検索結果ページ
atr_read_file	1 つの関数を見るためにファイル全体を読むこと。同じ箇所を AI が 2 回読んだ場合は「変更なし」と表示します
atr_diff	ロックファイルだらけの git diff
atr_run	何千行にも及ぶテストやビルドの出力
atr_stats	ATR が節約したトークン数を表示します

---

安全性

• シークレットは読み取り、検索、表示されません。 .env ファイル、秘密鍵、クラウド認証情報、api_keys.json のような名前のファイルも対象です。ATR 経由で利用するツールや atr_diff にも適用されます。
• 読み取りと変更は別々です。 読み取り専用のツールは atr_read を通じて実行されます。何かを変更するツールは atr_call を通じて実行されるため、実行前にアプリから確認できます。atr_run（シェルコマンド）は必ず確認を求めます。
• ファイルにアクセスできるのは許可されたフォルダー内だけです。 ファイルツールが参照できるのは、設定に記載されたフォルダーのみです。

---

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 を指定して有効にしない限り、インターネット経由でのファイル読み取りとシェルコマンドの実行は無効です。シークレットを変更するには、~/.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