STARWARCLOUD STARWAR.AI
返回市场
卡通上下文MCP服务器

卡通上下文MCP服务器

作者：aj-geddes2 星标更新：2025-11-18
安装使用来源：spider==github.com

项目介绍

TOON-MCP: Token-Optimized Object Notation

License: MIT Python 3.10+ MCP

TOON-MCP 是一个模型上下文协议服务器，它自动将冗长的 JSON 结构转换为 Token-Optimized Object Notation (TOON)，在AI辅助开发流程中最多可减少高达 60% 的令牌消耗。

🚀 特性

  • 智能压缩：自动模式检测和智能 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/          # 第一阶段：核心 MCP 服务器
│   ├── src/
│   │   ├── toon_converter.py  # 核心 TOON 逻辑
│   │   ├── server.py          # MCP 服务器
│   │   └── patterns.py        # 模式检测
│   ├── tests/
│   │   └── test_conversions.py
│   ├── pyproject.toml
│   └── README.md
├── claude-code-integration/   # 第二阶段：Claude 代码集成
│   ├── auto_converter.py      # 自动转换系统
│   └── example_generator.py   # TOON 示例生成器
├── context-manager/           # 第三阶段：上下文管理器
│   ├── 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：

在本地查看文档

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

🎨 按阶段特性

第一阶段：核心 MCP 服务器 ✅

  • 带有智能压缩的 TOON 转换器
  • 模式检测系统
  • 带有 6 个工具的 MCP 服务器
  • 综合测试套件
  • 包配置

第二阶段：Claude 代码集成 ✅

  • JSON 扫描的预提交钩子
  • 代码/文档的自动转换系统
  • TOON 示例生成器
  • 多语言支持

第三阶段：上下文管理器 ✅

  • 令牌使用监控
  • 主动工具输出转换
  • MCP 服务器集成助手
  • 优化建议

📈 性能

按数据类型典型令牌节省量：

  • API 响应：40-60% 节省
  • 数据库结果：50-65% 节省
  • 配置文件：35-50% 节省
  • 对象数组：55-70% 节省

🤝 贡献

欢迎贡献！请：

  1. 分叉仓库
  2. 创建功能分支
  3. 运行测试：pytest tests/ -v
  4. 提交拉取请求

📄 许可证

MIT 许可证 - 详情见 LICENSE 文件

🔗 链接

🌟 为什么选择 TOON？

在 AI 辅助开发中，令牌限制可能会约束您的工作流程。TOON 帮助您：

  • 在对话中容纳更多上下文
  • 通过较少的令牌减少 API 成本
  • 通过较小的数据包提高响应时间
  • 在令牌限制内处理更大的数据集

📊 架构

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

🎯 发展路线图

  • 核心 TOON 转换器
  • MCP 服务器实现
  • 模式检测
  • Claude 代码集成
  • 上下文管理器
  • 完整文档
  • TypeScript/JavaScript 移植
  • VSCode 插件
  • 浏览器扩展
  • 性能基准测试
  • 社区模板

💡 使用案例

  1. 大型代码库分析：压缩文件列表和搜索结果
  2. API 集成：优化 API 响应存储在对话中
  3. 数据库查询：减少分享查询结果时的令牌使用
  4. 配置管理：以紧凑格式存储配置
  5. 文档：包括示例而不增加令牌负担

为 AI 开发社区打造

减少令牌。提高生产力。