mcptoon 0.7.8 — per-tool compression policy

mcptoon 0.7.8

Per-tool compression policy — the MuleSoft answer, client-side

One format no longer fits every tool. An image generator returning base64 must
never be squeezed; a chatty search tool might deserve forced TOON. Policies give
each server:tool its own answer:

mcptoon policy set <server> <tool> raw      # never compress (images, base64)
mcptoon policy set <server> * toon          # server-wide default format
mcptoon policy clear <server> <tool>        # back to default

• Applies to explicit mcptoon call runs and to the mcptoon serve bridge
• Explicit format flags (--json, --toon, ...) always win over policies
• Stored in ~/.mcptoon/compression.json (MCPTOON_COMPRESSION_FILE redirects it)

Demo now pushes adoption, not just applause

mcptoon demo next-steps list mcptoon sync (write the config into the agents
you already run) before the star ask — the trial→adoption move.

Also in this release

• skills/mcptoon/SKILL.md at the repo root — install with
  npx skills add activeing123/mcptoon for any agent that reads skills
• The README documents the industry convergence with sources: Anthropic's
  advanced tool use (TST −85% tool-definition tokens, PTC −37%) and MuleSoft's
  MCP gateway adopting TOON — mcptoon is the result-side complement
• publish-mcp.yml waits for PyPI to list the released version before pushing
  the registry record (no more manual retries after a release)

Full suite: 790 passed, 1 skipped. Zero third-party dependencies. Python ≥ 3.10.

v0.7.7 — version metadata fix

v0.7.7 — version metadata fix

Hotfix for v0.7.6: that wheel's metadata said 0.7.6 while
mcptoon --version printed 0.7.5 — the hardcoded __version__ in
src/mcptoon/__init__.py was missed by the release bump. Caught by the
post-release smoke test (fresh venv, official PyPI index), which is now
part of the written release checklist.

• __version__, pyproject.toml and server.json all say 0.7.7.
• tests/test_registry_sync.py pins mcptoon.__version__ against
  pyproject, so the next bump updates all of them or fails CI.

No other changes. See v0.7.6 for the 2026-07-28 GA server bridge and the
official Claude Code plugin.

v0.7.6 — MCP 2026-07-28 GA server bridge + Claude Code plugin

v0.7.6 — MCP 2026-07-28 GA server bridge + official Claude Code plugin

Two firsts in one release:

The bridge now speaks the GA spec on the server side

mcptoon serve is stateless-first, per the MCP 2026-07-28 GA revision:

• No initialize handshake required. A modern client can call
  tools/list without ever sending initialize. Legacy handshake clients
  keep working unchanged, and requested versions inside the support list
  are echoed back instead of a hardcoded date.
• Self-describing requests. _meta with
  io.modelcontextprotocol/protocolVersion (and the pre-GA draft key) is
  honored on every request; unsupported versions are rejected with
  -32022 (UnsupportedProtocolVersionError).
• server/discover advertises protocolVersions, capabilities
  (with the GA extensions field) and serverInfo — no config load, safe
  to probe up front.
• SEP-2549 CacheableResult. tools/list, prompts/list,
  resources/list and resources/read carry ttlMs + cacheScope
  (defaults: 300000 ms / public; override with MCPTOON_LIST_TTL_MS /
  MCPTOON_LIST_CACHE_SCOPE), so clients can cache tool catalogs across
  reconnects and keep upstream prompt caches warm.
• resultType: "complete" on every ordinary result.

To our knowledge this makes mcptoon the first zero-dependency
MCP-compression bridge with a complete 2026-07-28 server-side surface
(enterprise gateway competitors currently stop at 2025-06-18).

Install it inside Claude Code in one line

/plugin marketplace add activeing123/mcptoon

The plugin package (claude-code-plugin/) contains no business logic —
it installs, wires and teaches:

• SessionStart hook auto-installs the CLI on the very first session
  (zero-dependency 128KB wheel, seconds) and only reports status after
  that. It never raises; a broken environment cannot break your session.
  Native Windows command variant included.
• .mcp.json wires the mcptoon serve bridge into the session, so
  tool discovery arrives pre-compressed.
• skills/mcptoon/SKILL.md teaches the agent when and how to use the
  CLI (manifest / inspect / search / call --auto / doctor), and
  forbids it from quoting savings numbers it did not observe.
• /mcptoon-setup for guided setup and repair.

The CLI stays what it always was — pip install mcptoon keeps working
for every other agent (Codex, Cursor, OpenCode, ...); the plugin is one
more door to the same engine.

Quality

• 769 tests passed (+10 plugin guards, +19 bridge tests), 1 skipped,
  Windows in the CI matrix, ruff clean, zero third-party dependencies
  (stdlib only), 128KB wheel.

v0.7.5 - the numbers are now reproducible

What's fixed

The command the README told you to run to verify our numbers never existed.
mcptoon manifest --compact --tokens was quoted in eight places as the
reproduction path. --tokens was never implemented, and unknown options were
dropped silently — so it printed a listing and no count, and looked fine.

• scripts/bench_tokens.py is now the real thing: it measures the tool lists
  cached on your machine with tiktoken (cl100k_base and o200k_base) across raw
  JSON, --slim and --compact. From this release's test box (4 servers, 39 tools):
  raw 4,285 → --slim 340 (92.1% smaller) → --compact 156 (96.4% smaller).
• Unknown long options now warn on stderr instead of vanishing.
• Every "reproduce it yourself" line points at the script.
• mcptoon --version works (it used to print "Unknown command: --version").

Stale savings figures in shipped text. --slim was described as saving 93% in
the CLI help, in output.py, in the mcptoon demo hint and in the Codex
integration doc; measured it is 88.5%. --compact was described as "~20 tokens
for 96 tools"; measured it is ~2.3 tokens per tool (581 for 255).
docs/tiktoken-benchmarks.md lost a row that measured a listing truncated at 30
entries, and its older 39,964 baseline is now labelled as a separate sample against
the canonical 71,929 → 581.

README links were dead on PyPI. All 15 relative links and images resolved
against the PyPI project page (/project/mcptoon/DEVELOPERS.md/) and 404'd. They
are absolute now, with a test to keep them that way.

The English README embedded Chinese-language assets. New
assets/token-savings-en.svg and assets/demo-en.gif — the latter rendered from a
real pip install mcptoon + mcptoon demo transcript captured on a clean
virtualenv (scripts/make_demo_gif.py keeps the transcript, so only the pacing is
synthetic). assets/benchmark.svg was still charting 90,804 → 117 and is now
regenerated from assets/benchmark_tiktoken.json.

Flaky test fixed. The HTTP auth suite failed about 1 run in 5 on Windows with
Winsock 10053: the server answers 401 before reading the body, and the stack aborts
the connection while the client is still uploading. The helper now retries that
transport abort — bare, or wrapped in URLError — with a short backoff. 15
consecutive green runs of the suite verified.

---

694 passed, 1 skipped, 19 subtests · zero runtime dependencies · Python 3.10–3.13 on
Linux, macOS and Windows.

pip install -U mcptoon && mcptoon demo

v0.7.4 — the demo works, the numbers are honest

What's fixed

The demo works again — everywhere. mcptoon demo spawned npx -y @modelcontextprotocol/server-fetch, a package that no longer exists on the npm registry (E404). The server died instantly and the real error was swallowed. It now runs the official server-everything reference server: a fresh pip install mcptoon && mcptoon demo measures your own setup in ~60 seconds, no API key, no network fetch.

Silent servers can no longer freeze the client. _stdio_request() read responses with a blocking readline() that had no deadline — one dead config entry could hang doctor, manifest, discover or --auto forever. A background response pump now routes every JSON-RPC reply to a per-id queue with a deadline: silence surfaces as RESPONSE_TIMEOUT instead of a lifetime hang, and late replies go to a lost-and-found instead of poisoning the next request.

manifest --compact shows the whole tool index. For a multi-server manifest it fell through to json.dumps(...)[:200] and emitted a headless JSON fragment with ~9 tool names — an agent using --compact for discovery silently saw a fraction of its tools. It now prints the full server: tool1, tool2 · … name index, which is what the docs always claimed.

What's honest

The "255 tools → 123 tokens (−99.8%)" figure was a 30-item truncation artifact in our own benchmark harness. The full name index of the same 255-tool config measures 581 tokens:

71,929 tokens of raw JSON discovery → 581 tokens of name index = −99.2% (tiktoken cl100k_base)

Every README, article, SVG, benchmark JSON, server.json and the demo table now carry the measured figure. Reproduce it on your own machine:

mcptoon manifest --compact --tokens

Install

pip install mcptoon

Zero dependencies (pure stdlib), ~250 KB, Windows / macOS / Linux, Apache-2.0, 681 tests.

v0.7.3 — HTTP serve security hardening

Security patch from the 2026-09-02 red-team code audit. No new features - pure hardening of mcptoon serve HTTP mode.

Security fixes

• Loopback-by-default: bare --http / --listen :8080 binds 127.0.0.1 (was 0.0.0.0)
• Non-loopback bind requires --auth - refused outright otherwise (exit 2); the LAN-exposed + unauthenticated combination can no longer be constructed
• Bare --auth auto-generates a secure token (printed once, Jupyter-style)
• Auth on GET too, before body parsing - /health /status no longer skip the token check
• Origin/Host browser guard - CSRF + DNS-rebinding protection on every request (curl/agents unaffected); allowlist via MCPTOON_ALLOWED_HOSTS
• Content-Type gate - browser form-post carriers (text/plain, multipart) rejected with 415
• prompts/get runs the injection scanner on SKILL.md bodies (previously unscanned)

Scanner hardening

• _check_poisoning: full-text scan (5000-char truncation bypass closed), NFKC fold (fullwidth homoglyphs), zero-width char strip + density signal, Chinese indicator list

Tests: 660 passed (+30 new security tests). Upgrade: pip install -U mcptoon

v0.7.2 — First-run delight

v0.7.2 — First-run delight 🎉

Three changes that make the first 60 seconds feel good.

quickstart now celebrates

mcptoon quickstart closes with a big-number payoff instead of a wall of text:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🎉  37 tools ready across 5 servers!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Now you can:
    mcptoon sync    # write this config into Claude Desktop,
                    # Cursor, Codex, Cline, Windsurf, VS Code
    mcptoon serve   # or expose ALL servers as ONE stdio server

demo speaks in before → after

mcptoon demo now leads with the one sentence everyone remembers:

  📊  SAME data, 99% fewer tokens:
      12,400  →        117   (SLIM)

and ends with a "Now you can" checklist instead of CLI soup.

One-line installers

No Python wrangling — the script detects Python, installs mcptoon (pipx →
pip --user → PEP 668 venv fallback), then hands off to quickstart:

curl -fsSL https://raw.githubusercontent.com/activeing123/mcptoon/main/install.sh | bash

irm https://raw.githubusercontent.com/activeing123/mcptoon/main/install.ps1 | iex

Official first-party plugin

plugin/mcptoon-skills — three SKILL.md files (connect / authoring / triage)
that teach any agent how to drive mcptoon. Install it and the skills appear
as MCP prompts through mcptoon serve. mcptoon eats its own Agent Plugins
dog food.

---

631 tests · 0 dependencies · Apache-2.0 · Changelog

v0.7.1 — Agent Plugins Spec 1.0.0 support

What's new

mcptoon now installs, validates and manages the new cross-vendor Agent Plugins standard (https://agent-plugins.org — backed by Amazon, Cursor, Microsoft, OpenAI and Vercel). The spec deliberately leaves installation, distribution and cross-agent sync undefined — mcptoon fills exactly that gap:

Install once — every agent can use it.

mcptoon plugin scan <dir>        # validate a plugin package (read-only)
mcptoon plugin install <dir>     # install into mcptoon + every synced agent
mcptoon plugin list              # what is installed
mcptoon plugin remove <name>     # remove everywhere (data dir is kept)

Highlights

• Strict spec validation — closed manifest schema, single-token commands, HTTPS-only non-loopback URLs, no credentials in headers, path-escape checks. Structural problems are fatal; a broken server entry skips only that entry (spec failure boundaries).
• The pivot: pre-expanded paths — mcptoon is the installer, so ${PLUGIN_ROOT} / ${PLUGIN_DATA} are expanded into absolute paths at merge time and written into every agent's native config. Agents need zero plugin-loader support — including agents that never adopted the standard.
• Namespaced, collision-free — plugin:server keys; removal prunes from mcptoon config AND every agent config it reached.
• Persistent data dir — ~/.mcptoon/plugins-data/<name>/ survives --force upgrades and removal (spec §PLUGIN_DATA).
• stdio cwd end to end + spec-required PLUGIN_ROOT/PLUGIN_DATA env injection at server start.

Quality

• 610 tests passing (+41), zero third-party dependencies, ruff clean
• 19-point acceptance livefire: scan → install → list → verify expanded absolute paths in a real Claude Desktop config → remove → verify everything cleaned

Full changelog: CHANGELOG.md · README (EN + zh-CN) now carries an Agent Plugins badge and section.

v0.6.1 — Latest MCP spec compatibility (2025-06-18)

What's new

structuredContent native parsing

When a new-spec MCP server (2025-06-18) returns structured output, mcptoon call now prefers it over text content automatically — no flags needed. Old-spec servers behave exactly as before.

--envelope flag

mcptoon call <server> <tool> --envelope returns the complete MCP tools/call result envelope as JSON: structuredContent, _meta, resultType, isError, content all intact. Works with --auto routing too.

Library API

• MCPClient.call_tool_full() — envelope-level access from Python
• MCPClientPool.call_full() — same, via the connection pool

Compatibility matrix

New-spec feature	mcptoon support
structuredContent (structured tool output)	parsed natively
_meta / resultType protocol fields	--envelope passthrough
New-SDK servers (@modelcontextprotocol/server-*)	zero config
Old-spec servers	full backward compatibility

Quality: 548 tests passing (+8), zero third-party dependencies, ruff clean.

Docs: README (EN + zh-CN) now carries a prominent MCP-spec badge and a full compatibility matrix.

mcptoon v0.6.0

What's New

Token Savings Dashboard (mcptoon stats)

• Full JSON vs Slim manifest token comparison
• Per-server breakdown with savings percentage
• Usage stats integration (calls, success rate)

Per-Tool Toggle (mcptoon toggle)

• Enable/disable individual tools across all servers
• Persistent state saved to ~/.mcptoon/toggles.json
• mcptoon toggle --list shows all disabled tools

Bug Fixes

• Improved git push privacy scan (60 files, zero leaks)
• PR #12910 Glama badge added for awesome-mcp-servers

Installation

pip install mcptoon
# or
uv tool install mcptoon

Links

• GitHub
• dev.to Article
• awesome-mcp-servers PR #12910