ooples/token-optimizer-mcp

Measure token savings per AI coding agent, optimize context, and share a live local knowledge graph across 16 CLI clients.

Token Optimizer MCP – 是什麼

Token Optimizer MCP 是一個開源的 Node.js 插件，位於大型語言模型（LLM）客戶端（Claude Code、Codex、Gemini 等）與本地檔案系統之間。它會監控每一項 MCP（Model‑Client‑Protocol）操作——讀取、搜尋、編輯、寫入等——並試圖 避免傳送模型已經『付過費』的 token。它透過以下方式達成此目標：

阻止重複的讀取 – 如果檔案已在目前會話中讀取過，該插件會拒絕原始的 Read 請求，並回傳一個差異（diff），讓模型能使用而無需額外消耗 token。
記住結論 – 會話結束後，工具會建立輕量級的專案知識圖譜（包含檔案、符號、發現、決策、死胡同等）。當下一次會話觸及相同程式碼時，圖譜可直接提供結論，節省數千個 token。
衡量節省效果 – 每項操作都會記錄前（原本會傳送的數量）與實際（真正傳送的數量）的 token 數，讓你可以清楚看到避開了多少上下文。
按客戶端歸因成本 – 儀表板會為每個 LLM 客戶端（Claude Code、Codex、Gemini……）顯示獨立的資料列，讓你知道哪個代理最受益。

所有資料都留在開發者的機器上；沒有遙測資料、沒有主機服務，且程式碼採 MIT 授權，可於商業環境中使用。

核心概念

概念	作用
MCP 強制執行	插件會攔截高成本的呼叫（`Read`、`Grep`、`Glob`、`Edit`、`Write`、`cat`、`head` 等），拒絕它們（回傳快取的差異）或允許通過，僅當內容確實為新內容時。
專案級知識圖譜	節點 = 檔案、符號、任務、發現；邊 = `derived_from`、`contains`、`supersedes` 等。圖譜會自動從工具輸出與可選的模型「收割」呼叫中填入。
零回合拒絕	當讀取被拒絕時，拒絕回應中已包含答案（差異），因此模型無需第二回合——token 成本從一回合降至零。
儀表板	一個本地網頁介面（`http://localhost:3100`），顯示淨節省 token 數、各客戶端會計、圖譜健康狀態，以及知識圖譜的 3D 探索器。
無遙測	所有日誌皆本地儲存，不包含提示、檔案內容或路徑，並可透過環境變數進行輪替或停用。

快速入門（來自 README）

# 安裝 MCP 伺服器與你的 LLM 客戶端插件（範例：Claude Code）
/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

插件啟用後，在任何會話中執行審計命令：

token_audit   # 列出最大 token 成本操作的排名清單

要在本機執行儀表板：

npm install          # 安裝開發相依性
npm run build        # 編譯 UI
npm run dashboard    # 開啟 http://localhost:3100

你在儀表板上可以看到的內容（來自 README 的範例）

43 491 個淨驗證 MCP 傳輸 token 節省（總減少量減去有意擴展量）。
486 074 740 個歷史 token 被隔離 – 原始檔案掃描資料，從未進入模型上下文。
各客戶端的資料列，如 Codex、Claude Code、Gemini，顯示節省的 token 數與實際回傳的 token 數。
圖譜統計資料 – 例如：2 648 個節點、6 527 條邊、跨 11 個專案的 58 個發現。
健康面板 – 插件執行次數、失敗次數、逾時次數、各客戶端的延遲百分位數。
「圖譜取代潛力」與「因果研究」區塊，追蹤提供快取發現是否確實防止了後續的讀取。

常見使用情境

情境	Token Optimizer 如何協助
重複讀取檔案 – 調試會話不斷開啟同一個大型原始碼檔案。	插件拒絕第二次讀取，並回傳極小的差異，節省數千個 token。
重新推導結論 – CI 執行完畢後，你開啟新終端並詢問模型某個特定錯誤的原因。	知識圖譜已儲存先前的推理（例如：「時鐘偏移導致 401 錯誤」），因此模型可直接回答，無需重新計算。
多客戶端專案 – 團隊對某些任務使用 Claude Code，對其他任務使用 Gemini。	token 會計按客戶端分開，讓你能看出哪個模型帶來最佳成本效益。
預算追蹤成本 – 你需要向財務團隊報告 LLM 使用情況。	前後 token 數會被持久化，並可匯出為 markdown 或 JSON。

局限與注意事項（如 README 所述）

無自動 RAG – 系統不會取得原始文件；僅重用已推導出的「判決」。
模型驅動的收割為可選 – 若無憑證（TOKEN_OPTIMIZER_HARVEST_ENDPOINT），語意收割步驟將被停用，僅建立「結構性」圖譜。
零回合拒絕需模型主動請求檔案 – 若模型從未請求檔案，優化器無法介入。
基於圖譜的節省會獨立衡量 – 圖譜取代的潛在節省會顯示，但尚未計入已驗證的標題，直到足夠的處理/保留樣本存在。
僅支援 16 個官方 MCP 客戶端 – README 列出 16 個客戶端；使用不受支援的客戶端將無法獲得相同會計功能。
僅限本機 – 所有資料都留在機器上；無雲端服務可跨開發者分享圖譜。

哪些人可能需要這個工具？

開發 AI 協助程式碼助理的工程師，希望降低 token 費用。
運行自架 LLM 的團隊（例如 Claude、Gemini），需要一種方式審計 token 使用，且不需將資料傳送到外部。
研究 token 經濟學的學者 – 內建的前後測量與對照實驗提供可重現的資料集。
有嚴格資料隱私政策的公司 – 此工具完全離線運作，並遵守 MIT 授權，適用於商業用途。

總結

Token Optimizer MCP 是一個 實用、以隱私為先的 LLM 驅動開發工作流程優化器。透過拒絕重複讀取、將推導結論快取至輕量知識圖譜，並針對每個客戶端公開透明的節省指標，讓你將更多上下文預算留給新的推理，而非重複支付模型已執行的工作。