activeing123/mcptoon

📦 mcptoon – Zero‑Config Token Optimization & Unified Governance for MCP Tools & Skills

What it is

• A tiny (363 KB) pure‑Python CLI that sits between your local AI agents (Claude, Cursor, Gemini, etc.) and the Model Context Protocol (MCP) tools/skills you have installed.
• It keeps the full tool/skill schemas off the LLM’s context window and supplies a compact name‑only index instead, cutting the amount of text the model has to process by >99 %.
• Works with 103+ desktop and CLI agents out‑of‑the‑box and requires no external dependencies – just pip install mcptoon.

Core capabilities

Category	What you get
Token & context optimisation	• Name‑only index (72 k → 581 tokens for 255 tools) • Lossless compression with reversible retrieval (retrieve) • Session‑level deduplication of identical outputs • Real‑world token accounting via mcptoon bench
Universal tool management	• Search 17 000+ registered MCP servers (search) • Uniform CLI driver (call) for any MCP tool • On‑demand schema inspection (inspect) • Self‑healing diagnostics (doctor)
Skills governance	• Single‑source sync across many agents (Claude, Cursor, etc.) • Offline BM25‑based skill router (<5 ms, zero model cost) • Version‑gate to avoid drift, tombstone removal for dead skills
Docs routing	• Automatic markdown tree indexing • Chapter‑level feeding (only the needed part) • Zero‑model BM25 matching, saving ~40 k tokens per lookup
Engineering discipline	• 0 external dependencies (standard library only) • XDG‑compliant config isolation • Fully local, air‑gap ready, no telemetry

How it works

1. Compact catalogue – Only the tool/skill names (and a tiny pointer) are kept in the LLM context. The full JSON schema lives on disk and is fetched lazily with mcptoon inspect.
2. On‑demand retrieval – When an agent calls a tool, mcptoon pulls the schema, runs the tool, and returns the result. Optional --toon flag re‑encodes results in a smaller “TOON” format (≈5 % size reduction on mixed data).
3. Universal gateway – mcptoon serve exposes a single MCP endpoint that forwards calls to any registered server, so every agent can use the same backend without individual configuration.

Quick start

pip install mcptoon               # zero‑dep, 2 s install
mcptoon quickstart                # auto‑detect MCP servers, inject /mcptoon skill into all agents
mcptoon manifest                  # view the compact tool catalog (581 tokens for 255 tools)
mcptoon call demo echo_message '{"message":"hi"}'

You can also interact directly from an agent by asking it to load the /mcptoon skill – no terminal commands needed.

Typical use cases

• Power users who run many MCP tools and see their token budget eaten by tool descriptions.
• Teams that want a single source of truth for tools/skills across dozens of agents without editing each agent’s JSON.
• CI / automation pipelines that need a stable, scriptable interface (mcptoon call …) and optional HTTP proxy (mcptoon serve).
• Air‑gapped environments where installing extra runtimes (Node, Docker) is impossible – mcptoon is pure Python stdlib.

Limitations / gotchas

• The token‑saving only applies when the agent can invoke mcptoon (either via the injected skill or by calling the mcptoon serve MCP endpoint). Agents that hard‑code tool schemas into their prompts will not benefit unless re‑configured.
• Result compression (--toon) is shape‑dependent; some payloads shrink only a few percent, others up to ~50 %.
• mcptoon does not ship any tools itself – you must discover or install them from external MCP registries.

License

• Apache 2.0 (see LICENSE).

Where to learn more

• Official website: https://mcptoon.github.io/
• Token‑tax calculator: https://mcptoon.github.io/tools/token-tax/
• Developer docs: DEVELOPERS.md in the repo.

---

All statements are taken directly from the repository’s README; no additional features have been inferred.