tokenleaf 0.6.3

FinOps + GreenOps MCP server — compress LLM prompts losslessly, save money and CO₂.

TokenLeaf

FinOps + GreenOps for LLM users. Compress your prompts losslessly before they hit the LLM, save money and reduce CO₂ emissions — without changing the meaning of what you ask.

Typical savings on debugging prompts with duplicated code, JSON dumps, or repetitive logs: 25–45 %. Savings on short conversational messages: ~0 %. What you save depends entirely on what you paste.

---

The four pillars

TokenLeaf is more than a single MCP tool. It's four cooperating pieces:

1. analyze_and_compress_prompt — seven lossless strategies (stack-trace collapse, code-block dedup, JSON minify, HTML/XML, Markdown tables, log collapse, whitespace) applied in a safe order.
2. preprocess_document / preprocess_directory — turn PDFs, DOCX, PPTX, XLSX, EPUB, HTML, RTF into compressed markdown before they're uploaded into a prompt. PDF savings are routinely 70–90 % vs. multimodal page-tokenization.
3. Output governor — calculate_esg_impact + a policy injector that nudges the LLM toward terser responses on simple questions.
4. Transparent proxy — tokenleaf proxy runs an Anthropic-API-compatible server on localhost that compresses every outgoing role=user message before forwarding to api.anthropic.com. Works with Cursor and any SDK that respects ANTHROPIC_BASE_URL.

Code blocks (``` and inline backticks) are never modified beyond whitespace cleanup. The compressed prompt is always semantically equivalent to the original for the LLM.

---

Install

pip install tokenleaf
tokenleaf init

tokenleaf init walks you through:

1. Saving your activation key (purchased at https://tokenleaf.app)
2. Validating it against the TokenLeaf backend
3. Detecting installed MCP hosts (Claude Desktop, Cursor)
4. Wiring TokenLeaf into each host's config (with backup + diff confirmation)

Restart your MCP host and you're done.

---

How it integrates with each host

TokenLeaf intercepts in two complementary ways. Different hosts get different paths:

Host / Tool	How TokenLeaf intercepts	Reliability
Claude Desktop	MCP tool invocation via LEAF_INSTRUCTIONS.md in your Claude profile	~95 % on long prompts
Cursor	MCP tools and transparent proxy via ANTHROPIC_BASE_URL	100 % via proxy
Anthropic SDK / scripts	Transparent proxy via ANTHROPIC_BASE_URL	100 %
Claude Code	MCP tools (proxy planned for v0.7)	~95 %

Soft transparency on Claude Desktop

Paste the contents of LEAF_INSTRUCTIONS.md into your Claude Personal preferences or a project's Custom instructions. Claude will then invoke analyze_and_compress_prompt and preprocess_document on its own whenever the routine matches. No manual "compress this first" needed.

True transparency on Cursor / SDK

tokenleaf proxy --port 8788
# Then in another terminal:
export ANTHROPIC_BASE_URL=http://localhost:8788
cursor .

Every outgoing user message is compressed before it reaches Anthropic. System prompts and assistant turns are passed through unchanged.

---

Usage

In Claude Desktop or Cursor, just paste a long debugging prompt or upload a document. With LEAF_INSTRUCTIONS.md installed, you'll see a one-line note at the bottom of Claude's reply:

LEAF saved 8,432 → 4,891 tokens (42.0 % · $0.0106 · 1.42 g CO₂). Deduplicé 2 bloques de código idénticos; minimicé 1 bloque HTML/XML.

Inspect your cumulative savings any time:

tokenleaf summary
tokenleaf dashboard      # opens leaf-dashboard.html in your browser

---

CLI

tokenleaf init          # interactive first-time setup
tokenleaf doctor        # diagnose license, hosts, ledger
tokenleaf serve         # run the MCP server (stdio)
tokenleaf install       # add TokenLeaf to all detected hosts
tokenleaf uninstall     # remove TokenLeaf from a host's config
tokenleaf summary       # cumulative savings ledger as JSON
tokenleaf dashboard     # open the local savings dashboard
tokenleaf proxy         # run the transparent Anthropic-API proxy
tokenleaf convert       # convert a document/folder to compressed markdown
tokenleaf handshake     # force a fresh license handshake
tokenleaf config        # print resolved settings (secrets masked)

---

Privacy

• Prompt content never leaves your machine. All compression and document conversion happen locally.
• The local ledger stores only sizes, costs, and SHA-256 hashes — never prompt text.
• The license-validation handshake sends only your activation key and a stable machine fingerprint. No prompt data is transmitted.
• The optional heartbeat (fired once per UTC day per machine, only when TOKENLEAF_LICENSE_KEY is set) carries only your license_id, machine fingerprint, timestamp, and lifetime aggregate totals. No per-event detail, no domain breakdown, no prompt content. The exact request body is built by src/tokenleaf/telemetry/heartbeat.py and a privacy-canary test in tests/test_telemetry.py fails CI if any prompt-content-shaped field name appears.
• Personal-use mode (no license key + TOKENLEAF_ALLOW_OFFLINE=true, the default) makes zero network calls. You can use the full feature set offline; only paid tier requires a key.

---

Requirements

• Python ≥ 3.11
• An MCP-compatible host (Claude Desktop, Cursor, Claude Code, or any client supporting MCP)
• A TokenLeaf subscription — start at https://tokenleaf.app

---

License

Proprietary. See the LICENSE file. Use requires an active subscription.