Toon Context MCP

🚀 TOON-MCP：令牌優化對象表示法

TOON-MCP 是一個模型上下文協議（MCP）服務器，它能自動將冗長的 JSON 結構轉換為令牌優化對象表示法（TOON），在人工智能輔助開發工作流中，最多可減少**60%**的令牌消耗。

🚀 快速開始

TOON-MCP 能有效優化 JSON 結構，降低 AI 輔助開發中的令牌消耗。下面為你介紹如何快速使用該項目。

✨ 主要特性

• 智能壓縮：自動檢測模式並對 JSON 進行智能優化。
• 令牌監控：即時跟蹤對話令牌使用情況，並提供優化建議。
• MCP 集成：可與 Claude 及其他 MCP 客戶端無縫集成。
• 無損轉換：在 JSON 和 TOON 之間實現完美的往返轉換。
• 自動優化：主動轉換工具輸出，以實現最高效率。
• 預提交鉤子：掃描代碼中的 JSON 並建議進行 TOON 轉換。
• 上下文管理：監控並優化跨對話的令牌使用情況。

📦 安裝指南

前提條件

• 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"
    }
  }
}

💻 使用示例

基礎用法

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

🔧 技術細節

項目結構

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 掃描鉤子

性能表現

不同數據類型的典型令牌節省情況：

• API 響應：節省 40 - 60%
• 數據庫結果：節省 50 - 65%
• 配置文件：節省 35 - 50%
• 對象數組：節省 55 - 70%

架構圖

graph TB
    subgraph "TOON-MCP 服務器"
        A[MCP 服務器] --> B[TOON 轉換器]
        A --> C[模式檢測器]
        A --> D[令牌監控器]
    end

    subgraph "Claude 代碼集成"
        E[預提交鉤子] --> F[自動轉換器]
        F --> G[示例生成器]
    end

    subgraph "上下文管理器"
        H[令牌監控器] --> I[工具優化器]
        I --> J[MCP 集成]
    end

    K[Claude / MCP 客戶端] --> A
    A --> K

路線圖

• [x] 核心 TOON 轉換器
• [x] MCP 服務器實現
• [x] 模式檢測
• [x] Claude 代碼集成
• [x] 上下文管理器
• [x] 完整文檔
• [ ] 移植到 TypeScript/JavaScript
• [ ] VSCode 擴展
• [ ] 瀏覽器擴展
• [ ] 性能基準測試
• [ ] 社區模板

使用場景

1. 大型代碼庫分析：壓縮文件列表和搜索結果。
2. API 集成：優化對話中 API 響應的存儲。
3. 數據庫查詢：在共享查詢結果時減少令牌使用。
4. 配置管理：以緊湊格式存儲配置。
5. 文檔編寫：在不增加令牌開銷的情況下包含示例。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🔗 鏈接

• 文檔：請查看 /docs 目錄
• 問題反饋：GitHub Issues
• 討論區：GitHub Discussions

🌟 為何選擇 TOON？

在人工智能輔助開發中，令牌限制可能會制約你的工作流程。TOON 可以幫助你：

• 在對話中容納更多上下文
• 通過減少令牌使用降低 API 成本
• 通過更小的有效負載縮短響應時間
• 在令牌限制內處理更大的數據集

為人工智能開發社區用心打造

減少令牌消耗，提高工作效率