ooples/token-optimizer-mcp

Token Optimizer MCP – what it is

@ooples/token-optimizer-mcp is an npm package that plugs into a Large‑Language‑Model (LLM) workflow and tries to reduce the number of tokens the model has to read. It does this by:

1. Blocking expensive reads – when an agent asks to Read a large file the plugin refuses the request and returns a diff that only contains the changes since the last read.
2. Caching results in a per‑project knowledge graph – findings that an agent has already derived are stored and automatically re‑used, avoiding the need to re‑derive them.
3. Measuring the actual cost – the tool records a before/after token count for each request (the “MCP” – measured cost‑per‑request) and shows a live dashboard of savings per‑agent and per‑operation.
4. Attributing traffic – the dashboard groups savings by client (Claude, Gemini, etc.) and by the type of operation (read, grep, edit, …).

The core idea is that most LLM agents waste a lot of context on data they have already seen. By turning those reads into cheap diffs and by remembering previous reasoning, the optimizer can lower the token bill while keeping the same output quality.

---

How it works

• Block engine – the default mode works entirely locally. It compresses the request payload, replaces removed blocks with a tiny marker that points to a file on disk, and never sends the original bytes to the model.
• Proxy mode – an optional proxy can be placed in front of a model (e.g., Claude Code). It behaves like the block engine but also spills large blocks to a temporary file and sends a marker (<<ccr:hash,kind,size>>). The model can later retrieve the block if needed, paying a small extra token cost for the retrieval turn.
• Preset mode – the block engine with a configurable threshold (spillWholeBlockBelow) that decides when to spill a block to a file.
• Telemetry – opt‑in only. Two environment variables control local aggregation (TOKEN_OPTIMIZER_TELEMETRY=1) and optional upload (TOKEN_OPTIMIZER_BEACON=1). All uploads are anonymised, contain only numbers/flags, and can be disabled with DO_NOT_TRACK=1.

---

Benchmarks & results (as reported in the README)

The repository ships a benchmark harness that compares the optimizer against the “HeadRoom” compressor used by some LLM providers. Key take‑aways:

Workload	Token reduction (ours)	Token reduction (HeadRoom)	Cost factor (ours)
agentic‑conversation	30.8 %	33.4 %	0.52 × (proxy)
agent‑loop	59.1 %	54.3 %	0.92 × (proxy)
rag‑conversation	83.2 %	0.1 %	0.99 × (proxy)
… (18 workloads total)

Across 18 real‑world payloads the optimizer removes on average 82 % of characters and 91 % of tokens when run in proxy mode, beating the competitor on every row when no spilled blocks are fetched back. When blocks are fetched, it still wins on 17 of 18 rows.

Session‑level tests show a 5–9 % reduction in total token cost for 10‑ and 20‑turn conversations, and an end‑to‑end task suite (16 tasks) shows a median cost factor of 0.926× with no loss in quality (mean score 0.994 vs 0.994).

---

Getting started

# install the package
npm i @ooples/token-optimizer-mcp

# run the built‑in doctor to see configuration
npx token-optimizer-mcp doctor

Typical usage is to add the optimizer as a plugin to the LLM client you are using (Claude, Gemini, etc.). The README points to a install_doctor script that prints which telemetry flags are active and how many events are queued.

---

License & commercial use

The code is released under the MIT license and explicitly permits commercial use. No hosted service or account is required – you run the optimizer locally in your own environment.

---

Who might benefit?

• Developers building autonomous agents that repeatedly read large codebases or logs.
• Teams that run long‑running LLM sessions (e.g., code‑assistants, data‑analysis bots) and want to keep token costs low.
• Anyone who wants a transparent, reproducible measurement of how many tokens are saved by caching and diff‑based reads.

---

Bottom line

Token Optimizer MCP is a real, open‑source tool that targets a concrete inefficiency in LLM‑driven agents: unnecessary re‑reading of unchanged data. By replacing full reads with tiny diffs, caching results in a knowledge graph, and providing a public cost dashboard, it can cut token bills by roughly 10 %–30 % on typical agent workloads while preserving output quality. The project is actively benchmarked, CI‑tested, and MIT‑licensed for unrestricted use.