mcptoon: Token-Efficient MCP CLI Client

Reducing MCP Token Overhead with mcptoon

mcptoon 是一款跨平台 CLI 用戶端，旨在最大限度地減少與 Model Context Protocol (MCP) 相關的 token 成本。透過將標準 JSON 回應替換為一種稱為 TOON (Token-Optimized Object Notation) 的專有緊湊表示法，mcptoon 聲稱可將工具發現成本降低高達 97%，並將工具結果的開銷降低 40-60%。

The Problem: JSON Syntax Bloat

標準的 MCP 功能對話通常在結構化語法而非實際數據上消耗大量 token。根據專案文件，連接到五個 MCP 伺服器來列出工具可能需要大約 10,000 個 JSON token。當代理 (agent) 調用多個工具時，結果會被封裝在冗長的 JSON 結構中 (例如，{"content":[{"type":"text","text":"..."}]} )，這在 AI 開始處理實際資訊之前，就可能消耗掉 128K 上下文窗口的 30-55% 。

The Solution: TOON (Token-Optimized Object Notation)

mcptoon 透過 stdio 或 HTTP 連接至 MCP 伺服器，並將 JSON 輸出轉換為 TOON。這種表示法使用特定的替換方式來減少字元與 token 數量：

JSON	TOON	Logic
`{"name":"search","count":3}`	`name:search	count:3`
`[1, 2, 3]`	`1 2 3`	Spaces replace brackets and commas
`true` / `false`	`T` / `F`	Single character replacement
`null`	`∅`	Single symbol replacement
`"line1\nline2"`	`line1↲line2`	Special symbol replaces escape sequences
`{"a":{"b":[1,2]}}`	`a:b:1_2`	Recursive compaction

Performance Comparison

Operation	JSON tokens	mcptoon tokens	Savings
Tool discovery (96 tools)	~2,000	~60	97%
Tool result (structured data)	~800	~350	56%
Tool result (raw HTML/text)	~1,000	~900	10%

Integration and Compatibility

mcptoon 是一款零第三方依賴的 CLI 工具，使用純 Python (3.10+) 編寫。它與任何能夠執行 shell 命令的 AI 代理 (agent) 相容性，包括 Claude Code、Cursor、Codex 和 OpenCode。

Deployment Examples

Claude Code: Users can write mcptoon commands in SKILL.md files and set MCPTOON_AGENT_TYPE=claude 以自動選擇 --toon 輸出格式。
Cursor: The tool can be added to .cursorrules。
Codex (OpenAI): Instructions can be added to AGENTS.md 或系統提示詞 (prompt) 中，以使用 mcptoon manifest --toon 來列出工具。

Key Features and Safety

Unified Configuration: MCP 伺服器是在 ~/.mcptoon/config.json 中統一配置的，這允許多個代理 (agent) 共享相同的工具集。
Safety Blocking: 該用戶端會攔截與危險模式 (例如，delete, drop, purge) 相符的操作，除非傳遞了 --destructive 標記 (flag) 。
Usage Tracking: 本地端對總調用次數、成功率與估計的 token 節省量進行追蹤，並儲存在 ~/.cache/mcptoon/usage.json 中。
Schema Caching: 包含一個具有 5 分鐘 TTL 的 schema cache，以進一步減少發現開銷。

Technical Community Critique

雖然專案強調 token 節省，但 Hacker News 社群的幾位開發者對 TOON 表示法的實際效能提出了疑慮：

Tokenization vs. Characters: 批評者認為作者可能混淆了字元數與 token 數。例如，用戶指出 true/false 和 null 在現代 tokenizers 之中通常是單個 token，這意味著將 them 替換為 T/F 或 ∅ 並不會提供任何好處，甚至可能因為使用非-ASCII Unicode 符號而增加 token 數。
Information Loss: 一些用戶指出，--compact 模式會僅返回工具名稱，這會移除掉關鍵的描述與輸入 schema 模式，可能導致 LLM 幻覺 (hallucination) 或工具調用錯誤。
Alternative Approaches: 一些開發者建議，返回工具名稱及其參數 (例如， search_web(query) ) 應比僅列出名稱更有效，以防止參數幻覺 (hallucination) 。

"I think that some of these choices... show that the author has not investigated how tokenization works. Tokenization is not some black box, you can run tokenizers and check them."

Quick Start Guide

# Install
pip install mcptoon

# Initialize and add a server
mcptoon init
mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch

# List tools in TOON format
mcptoon manifest --toon

# Call a tool
mcptoon call fetch fetch '{"url":"https://example.com"}' --toon