JinDaGe - toon-context-mcp MCP Details

article

README

🚀 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 扩展
[ ] 浏览器扩展
[ ] 性能基准测试
[ ] 社区模板

使用场景

大型代码库分析：压缩文件列表和搜索结果。
API 集成：优化对话中 API 响应的存储。
数据库查询：在共享查询结果时减少令牌使用。
配置管理：以紧凑格式存储配置。
文档编写：在不增加令牌开销的情况下包含示例。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🔗 链接

文档：请查看 /docs 目录
问题反馈：GitHub Issues
讨论区：GitHub Discussions

🌟 为何选择 TOON？

在人工智能辅助开发中，令牌限制可能会制约你的工作流程。TOON 可以帮助你：

在对话中容纳更多上下文
通过减少令牌使用降低 API 成本
通过更小的有效负载缩短响应时间
在令牌限制内处理更大的数据集

为人工智能开发社区用心打造

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

toon-context-mcp