mcptoon: トークン効率的な MCP CLI クライアント

mcptoon による MCP トークンオーバーヘッドの削減

mcptoon は、Model Context Protocol (MCP) に関連するトークンコストを最小限に抑えるために設計されたクロスプラットフォームの CLI クライアントです。標準的な JSON レスポンスを TOON (Token-Optimized Object Notation) と呼ばれる独自のコンパクトな表記法に置き換えることで、mcptoon はツール・ディスカバリ（ツールの検出）コストを最大 97% 削減し、ツールの結果のオーバーヘッドを 40-60% 削減できると主張しています。

問題点: JSON 構文の肥大化

標準的な MCP 対応の会話では、実際のデータよりも構造的な構文に多大なトークンが消費されることがよくあります。プロジェクトのドキュメントによると、5 つの MCP サーバーに接続してツールをリストアップするには、JSON のために約 10,000 トークンを消費する可能性があります。エージェントが複数のツールを呼び出す際、結果は冗長な JSON 構造（例: {"content":[{"type":"text","text":"..."}]}）でラップされており、AI が実際の情報を処理し始める前に、128K コンテキスト・ウィンドウの 30-55% を消費してしまうことがあります。

解決策: TOON (Token-Optimized Object Notation)

mcptoon は stdio または HTTP を介して MCP サーバーに接続し、JSON 出力を TOON に変換します。この表記法は、特定の置換を行うことで文字数とトークン数を削減します。

JSON	TOON	ロジック
{"name":"search","count":3}	`name:search	count:3`
[1, 2, 3]	1 2 3	スペースがブラケットとカンマを置換
true / false	T / F	単一文字への置換
null	∅	単一記号への置換
"line1\nline2"	line1↲line2	特殊記号がエスケープシーケンスを置換
{"a":{"b":[1,2]}}	a:b:1_2	再帰的な圧縮

パフォーマンス比較

操作	JSON トークン数	mcptoon トークン数	節約額
ツール・ディスカバリ (96 ツール)	~2,000	~60	97%
ツール結果 (構造化データ)	~800	~350	56%
ツール結果 (生 HTML/テキスト)	~1,000	~900	10%

統合と互換性

mcptoon は、サードパーティの依存関係がゼロの CLI ツールであり、純粋な Python (3.10+) で書かれています。Claude Code、Cursor、Codex、OpenCode など、シェルコマンドを実行できるあらゆる AI エージェントと互換性があります。

デプロイメント例

• Claude Code: ユーザーは SKILL.md ファイルに mcptoon コマンドを記述し、MCPTOON_AGENT_TYPE=claude を設定することで、自動的に --toon 出力形式を選択できます。
• Cursor: このツールは .cursorrules に追加できます。
• Codex (OpenAI): AGENTS.md に指示を追加するか、システムプロンプトに mcptoon manifest --toon を使用してツールをリストアップするように指示を追加できます。

主要な機能と安全性

• 統合設定: MCP サーバーは ~/.mcptoon/config.json に一度設定すれば、複数のエージェントが同じツールセットを共有できます。
• 安全性ブロック: クライアントは、--destructive フラグが渡されない限り、危険なパターン（例: delete, drop, purge）に一致する操作をブロックします。
• 使用状況の追跡: 合計呼び出し回数、成功率、および推定トークン節約額のローカル・トラッキングは、~/.cache/mcptoon/usage.json に保存されます。 | スキーマ・キャッシュ: スキーマ・キャッシュ（TTL 5 分）を備えており、ディスカバリ・オーバーヘッドをさらに削減します。

技術コミュニティによる批判

プロジェクトがトークン節約を強調する一方で、Hacker News コミュニティの複数の開発者は、TOON 表記法の実際の効力について懸念を提起しています。

• トークン化 vs. 文字数: 批判的な意見を持つ人々は、著者が文字数とトークン数を混同している可能性があると主張しています。例えば、ユーザーは、現代のトークナイザーは true/false や null はしばしば単一のトークンとして扱うため、 T/F や ∅ が提供するメリット-なし、あるいは、非 ASCII Unicode 記号の使用によるトークン数が増加する可能性があると指摘しています。
• 情報損失: 一部のユーザーは、 --compact モード（ツール名のみを返す）は、重要な記述や入力スキーマを削除してしまうため、LLM のハルシネーション（幻覚）や誤ったツール呼び出しにつながる可能性があると指摘しています。
• 代替アプローチ: 一部の開発者は、ツール名のみをリストアップするよりも、引数を含めたツール名（例: search_web(query)）を返す方が、引数ハルシネーションを防ぐために効果的であると提案しています。

"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."

クイックスタート・ガイド

# 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