Toon Context MCP

🚀 TOON-MCP: Token-Optimized Object Notation

TOON-MCPは、冗長なJSON構造を自動的にToken-Optimized Object Notation (TOON) に変換するModel Context Protocolサーバーです。これにより、AI支援開発ワークフローにおけるトークン消費を最大**60%**削減することができます。

🚀 クイックスタート

TOON-MCPは、Model Context Protocolサーバーで、AI支援開発ワークフローにおけるトークン消費を大幅に削減することができます。以下に、このサーバーの主な機能と使い方を紹介します。

✨ 主な機能

• スマート圧縮：自動パターン検出とインテリジェントなJSON最適化
• トークン監視：会話のトークン使用量をリアルタイムで追跡し、最適化の推奨事項を提供
• MCP統合：Claudeや他のMCPクライアントとのシームレスな統合
• 損失のない変換：JSONとTOONの間で完全な往復変換が可能
• 自動最適化：ツールの出力を能動的に変換し、最大限の効率を実現
• コミット前フック：コードをJSONについてスキャンし、TOONへの変換を提案
• コンテキスト管理：会話全体でトークン使用量を監視し最適化

📊 簡単な例

元のJSON (142トークン):

{
  "id": 12345,
  "name": "John Doe",
  "email": "john@example.com",
  "type": "user",
  "status": "active",
  "metadata": {
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

TOON形式 (68トークン、52%削減):

{"_toon":"1.0","d":{"i":12345,"n":"John Doe","eml":"john@example.com","t":"user","s":"active","meta":{"ca":"2025-01-01T00:00:00Z","ua":"2025-01-15T10:30:00Z"}}}

📦 インストール

前提条件

• Python 3.10以上
• pipパッケージマネージャー

クイックインストール

# リポジトリをクローンする
git clone https://github.com/aj-geddes/toon-context-mcp.git
cd toon-context-mcp

# TOON-MCPをインストールする
cd mcp-server-toon
pip install -e .

Dockerインストール

TOON-MCPは、簡単なデプロイと分離のためにDockerコンテナで実行することができます。

# リポジトリをクローンする
git clone https://github.com/aj-geddes/toon-context-mcp.git
cd toon-context-mcp/mcp-server-toon

# Dockerイメージをビルドする
docker build -t toon-mcp-server:latest .

# Dockerで実行する
docker run -i toon-mcp-server:latest

# またはDocker Composeを使用する
docker-compose up -d

注意：Dockerイメージは、最適なパフォーマンスのためにDebianベースのPython (python:3.10-slim) を使用しており、Alpineではありません。

Dockerを使用したMCP統合の場合は、Claude Desktopの設定を更新して、コンテナ化されたサーバーを使用するようにします。

{
  "mcpServers": {
    "toon": {
      "command": "docker",
      "args": ["run", "-i", "toon-mcp-server:latest"]
    }
  }
}

MCP設定

Claude Desktopの設定 (~/.config/Claude/claude_desktop_config.json) に追加します。

{
  "mcpServers": {
    "toon": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/toon-context-mcp/mcp-server-toon"
    }
  }
}

🎯 プロジェクト構造

toon-context-mcp/
├── mcp-server-toon/          # フェーズ1: コアMCPサーバー
│   ├── src/
│   │   ├── toon_converter.py  # コアTOONロジック
│   │   ├── server.py          # MCPサーバー
│   │   └── patterns.py        # パターン検出
│   ├── tests/
│   │   └── test_conversions.py
│   ├── pyproject.toml
│   └── README.md
├── claude-code-integration/   # フェーズ2: Claudeコード統合
│   ├── auto_converter.py      # 自動変換システム
│   └── example_generator.py   # TOON例生成器
├── context-manager/           # フェーズ3: コンテキストマネージャー
│   ├── token_monitor.py       # トークン使用量監視
│   ├── tool_output_optimizer.py # 能動的な変換
│   └── mcp_integration.py     # MCP統合ヘルパー
├── docs/                      # 完全なJekyllドキュメント
│   ├── index.md
│   ├── guides/
│   │   ├── setup.md
│   │   ├── user-guide.md
│   │   └── troubleshooting.md
│   └── api/
│       └── reference.md
└── .git/hooks/
    └── pre-commit              # JSONスキャンフック

💻 使用例

基本的な使用法

from src.toon_converter import convert_json_to_toon, convert_toon_to_json

# TOONに変換する
toon_format = convert_json_to_toon(your_json_data)

# 元のJSONに戻す
original = convert_toon_to_json(toon_format)

MCPツール

Claudeで以下のツールを使用できます。

• convert_to_toon - JSONをTOON形式に変換する
• convert_to_json - TOONを元のJSONに戻す
• analyze_patterns - 最適化パターンを検出する
• get_compression_strategy - 最適な圧縮戦略を取得する
• calculate_savings - トークン節約量を計算する
• batch_convert - 複数のJSONオブジェクトを変換する

トークン監視

from context_manager.token_monitor import TokenMonitor

monitor = TokenMonitor(warn_threshold=50000)

# メッセージを分析する
monitor.analyze_message(message_content, role='user')

# メトリクスを取得する
metrics = monitor.get_metrics()
print(f"合計トークン数: {metrics.total_tokens:,}")
print(f"潜在的な節約量: {metrics.savings_percent:.1f}%")

ツール出力の最適化

from context_manager.tool_output_optimizer import ToolOutputOptimizer

optimizer = ToolOutputOptimizer(auto_optimize=True, min_savings=15.0)

# ツールの出力を自動的に最適化する
optimized, metadata = optimizer.optimize_tool_output("api_call", tool_output)

📚 ドキュメント

完全なドキュメントは /docs にあります。

• セットアップガイド - インストールと設定
• ユーザーガイド - 使用パターンと例
• トラブルシューティング - 一般的な問題と解決策
• APIリファレンス - 完全なAPIドキュメント

ドキュメントをローカルで表示する

cd docs
# Jekyllをインストールする (まだインストールされていない場合)
gem install bundler jekyll

# Gemfileを作成する
cat > Gemfile << 'EOF'
source "https://rubygems.org"
gem "jekyll", "~> 4.3"
gem "minima", "~> 2.5"
gem "jekyll-seo-tag"
gem "jekyll-sitemap"
gem "jekyll-feed"
EOF

# インストールしてサーブする
bundle install
bundle exec jekyll serve

# http://localhost:4000を開く

🧪 テスト

cd mcp-server-toon
pytest tests/ -v

🎨 フェーズ別の機能

フェーズ1: コアMCPサーバー ✅

• スマート圧縮機能を備えたTOON変換器
• パターン検出システム
• 6つのツールを備えたMCPサーバー
• 包括的なテストスイート
• パッケージ構成設定

フェーズ2: Claudeコード統合 ✅

• JSONスキャン用のコミット前フック
• コード/ドキュメントの自動変換システム
• TOON例生成器
• 複数の言語サポート

フェーズ3: コンテキストマネージャー ✅

• トークン使用量監視
• 能動的なツール出力変換
• MCPサーバー統合ヘルパー
• 最適化推奨事項

📈 パフォーマンス

データタイプ別の典型的なトークン節約量は以下の通りです。

• APIレスポンス：40 - 60%の節約
• データベース結果：50 - 65%の節約
• 設定ファイル：35 - 50%の節約
• オブジェクト配列：55 - 70%の節約

🤝 コントリビューション

コントリビューションを歓迎します！以下の手順に従ってください。

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. テストを実行する: pytest tests/ -v
4. プルリクエストを送信する

📄 ライセンス

MITライセンス - 詳細は LICENSE ファイルを参照してください。

🔗 リンク

• ドキュメント: /docs ディレクトリを参照
• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions

🌟 TOONのメリット

AI支援開発では、トークン制限がワークフローを制約することがあります。TOONは以下のことを支援します。

• 会話により多くのコンテキストを収める
• 少ないトークンでAPIコストを削減する
• 小さなペイロードで応答時間を改善する
• トークン制限内でより大きなデータセットを扱う

📊 アーキテクチャ

graph TB
    subgraph "TOON-MCP Server"
        A[MCP Server] --> B[TOON Converter]
        A --> C[Pattern Detector]
        A --> D[Token Monitor]
    end

    subgraph "Claude Code Integration"
        E[Pre-commit Hook] --> F[Auto-Converter]
        F --> G[Example Generator]
    end

    subgraph "Context Manager"
        H[Token Monitor] --> I[Tool Optimizer]
        I --> J[MCP Integration]
    end

    K[Claude / MCP Client] --> A
    A --> K

🎯 ロードマップ

• [x] コアTOON変換器
• [x] MCPサーバーの実装
• [x] パターン検出
• [x] Claudeコード統合
• [x] コンテキストマネージャー
• [x] 完全なドキュメント
• [ ] TypeScript/JavaScriptポート
• [ ] VSCode拡張機能
• [ ] ブラウザ拡張機能
• [ ] パフォーマンスベンチマーク
• [ ] コミュニティテンプレート

💡 使用例

1. 大規模コードベース分析：ファイルリストと検索結果を圧縮する
2. API統合：会話内でAPIレスポンスの保存を最適化する
3. データベースクエリ：クエリ結果を共有する際のトークン使用量を削減する
4. 設定管理：設定をコンパクトな形式で保存する
5. ドキュメント：トークンのオーバーヘッドなしで例を含める

AI開発コミュニティのために愛を込めて作成されました

トークンを削減し、生産性を向上させましょう。