ooples/token-optimizer-mcp

Token Optimizer MCP – What it is

Token Optimizer MCP is an open‑source Node.js plugin that sits between a large‑language‑model (LLM) client (Claude Code, Codex, Gemini, etc.) and the local filesystem. It watches every MCP (Model‑Client‑Protocol) operation – reads, greps, edits, writes, etc. – and tries to avoid sending tokens that the model has already “paid for”. It does this by:

1. Blocking redundant reads – if a file has already been read in the current session, the plugin refuses the raw Read request and returns a diff that the model can use without spending extra tokens.
2. Remembering conclusions – after a session finishes, the tool builds a lightweight per‑project knowledge graph (files, symbols, findings, decisions, dead‑ends). When the next session touches the same code, the graph can supply the conclusion directly, saving thousands of tokens.
3. Measuring savings – every operation is logged with a before (what would have been sent) and actual (what was really sent) token count, so you can see exactly how much context was avoided.
4. Attributing cost per client – the dashboard shows separate rows for each LLM client (Claude Code, Codex, Gemini, …) so you know which agent benefits most.

All data stays on the developer’s machine; there is no telemetry, no hosted service, and the code is MIT‑licensed, so it can be used in commercial environments.

---

Core concepts

Concept	What it does
MCP enforcement	The plugin intercepts expensive calls (Read, Grep, Glob, Edit, Write, cat, head, etc.) and either denies them (returning a cached diff) or lets them pass when the content is truly new.
Per‑project knowledge graph	Nodes = files, symbols, tasks, findings; Edges = derived_from, contains, supersedes, etc. The graph is populated automatically from tool output and optional model‑based “harvest” calls.
Zero‑turn refusal	When a read is denied, the refusal already contains the answer (the diff), so the model does not need a second turn – token cost drops from one turn to zero.
Dashboard	A local web UI (http://localhost:3100) that shows net token savings, per‑client accounting, graph health, and a 3‑D explorer of the knowledge graph.
Telemetry‑free	All logs are written locally, contain no prompts, file contents, or paths, and can be rotated or disabled via environment variables.

---

Quick start (from the README)

# Install the MCP server and the plugin for your LLM client (example: Claude Code)
/plugin marketplace add ooples/token-optimizer-mcp
/plugin install token-optimizer@token-optimizer
/reload-plugins

After the plugin is active, run the audit command in any session:

token_audit   # prints a ranked list of the biggest token‑cost operations

To run the dashboard locally:

npm install          # install dev dependencies
npm run build        # compile the UI
npm run dashboard    # opens http://localhost:3100

---

What you can see on the dashboard (examples from the README)

• 43 491 net verified MCP transport tokens avoided (gross reduction minus intentional expansions).
• 486 074 740 historical tokens quarantined – raw file‑scan data that never entered model context.
• Per‑client rows for Codex, Claude Code, Gemini, showing both avoided tokens and any tokens that were returned.
• Graph statistics – e.g., 2 648 nodes, 6 527 edges, 58 findings across 11 projects.
• Health panel – number of hook runs, failures, timeouts, latency percentiles per client.
• “Graph‑substitution potential” and “causal study” sections that track whether delivering a cached finding actually prevented later reads.

---

Typical use cases

Situation	How Token Optimizer helps
Repeated file reads – a debugging session keeps opening the same large source file.	The plugin denies the second read and returns a tiny diff, saving thousands of tokens.
Re‑deriving conclusions – after a CI run you open a new terminal and ask the model why a particular bug occurs.	The knowledge graph already stores the earlier reasoning (e.g., “clock skew caused 401s”), so the model can answer without re‑computing.
Multi‑client projects – a team uses Claude Code for some tasks and Gemini for others.	Token accounting is split per client, letting you see which model gives the best cost‑benefit.
Cost‑tracking for budgeting – you need to report LLM usage to finance teams.	The before/after token counts are persisted and can be exported as markdown or JSON.

---

Limitations & gotchas (as described in the README)

• No automatic RAG – the system does not retrieve raw documents; it only re‑uses verdicts that were already derived.
• Model‑based harvest is optional – without a credential (TOKEN_OPTIMIZER_HARVEST_ENDPOINT) the semantic harvest step is disabled, so only the “structural” graph is built.
• Zero‑turn refusals require the model to request the file – if a model never asks for a file, the optimizer cannot intervene.
• Graph‑based savings are measured separately – potential savings from graph substitution are shown but not counted in the verified headline until enough treated/holdout samples exist.
• Only 16 officially supported MCP clients – the README lists 16 clients; using an unsupported client will not get the same accounting.
• Local only – all data stays on the machine; there is no cloud service to share graphs across developers.

---

Who might want this?

• Developers building AI‑assisted coding assistants who want to keep token bills low.
• Teams running self‑hosted LLMs (e.g., Claude, Gemini) and need a way to audit token usage without sending data elsewhere.
• Researchers studying token‑economics – the built‑in before/after measurements and control‑arm experiments provide a reproducible dataset.
• Companies with strict data‑privacy policies – the tool works entirely offline and respects the MIT licence for commercial use.

---

Bottom line

Token Optimizer MCP is a practical, privacy‑first optimizer for LLM‑driven development workflows. By refusing redundant reads, caching derived conclusions in a lightweight knowledge graph, and exposing transparent token‑saving metrics per client, it lets you keep more of your context budget for new reasoning instead of re‑paying for work the model already did.