动画上下文MCP服务器

Name: 动画上下文MCP服务器
Author: jellyjamin

作者：jellyjamin2 星标更新：2025-11-08

安装使用来源：spider==github.com

项目介绍

TOON上下文MCP服务器

一个MCP（模型上下文协议）服务器，能够自动提供TOON格式的上下文给编码代理，使得在不改变工作流程的情况下，结构化数据的token减少透明地达到30-60%。

这是什么？

此MCP服务器拦截来自编码代理的文件请求，并在有益时自动将数据文件转换为TOON格式。当你引用一个JSON文件时，服务器会：

分析数据结构
转换为TOON，如果可以节省token（通常对于表格数据可节省30-60%）
缓存TOON版本以供未来使用
如果TOON无益，则回退到原始格式

神奇之处？ 你无需考虑这些。正常引用文件，自动获得token优化。

快速开始

1. 安装

cd toon-context-mcp
./setup.sh

或手动安装：

cd toon-context-mcp
npm install
npm run build

2. 配置你的MCP客户端

对于Cline（VSCode扩展）

添加到你的Cline MCP配置中：

{
  "mcpServers": {
    "toon-context": {
      "command": "node",
      "args": ["/绝对路径/to/toon-context-mcp/build/index.js"],
      "env": {
        "TOON_THRESHOLD": "0.7",
        "AUTO_CONVERT": "true"
      }
    }
  }
}

对于Zed编辑器

添加到~/.config/zed/settings.json：

{
  "context_servers": {
    "toon-context": {
      "command": "node",
      "args": ["/绝对路径/to/toon-context-mcp/build/index.js"]
    }
  }
}

对于其他MCP客户端

该服务器遵循标准MCP协议。使用：

命令: node
参数: ["/路径/to/toon-context-mcp/build/index.js"]
传输: stdio

3. 测试它

# 交互式测试工具
cd toon-context-mcp
npm run inspector

# 或运行测试套件
cd ..
./TEST_MCP_SERVER.sh

4. 使用它

只需像平常一样使用你的编码代理！当你引用一个数据文件时：

"分析data/users.json并找到非活跃用户"

服务器会自动优化为TOON（如果有益），透明地为你节省30-60%的token。

示例：实际token节省

之前（JSON - 220个token）:

{
  "users": [
    { "id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin", "status": "active" },
    { "id": 2, "name": "Bob", "email": "bob@example.com", "role": "user", "status": "active" },
    ...
  ]
}

之后（TOON - 84个token，节省61.8%）:

users[5]{id,name,email,role,status,created}:
  1,Alice Johnson,alice@example.com,admin,active,2024-01-15
  2,Bob Smith,bob@example.com,user,active,2024-02-20
  ...

你的工作流: 没有变化。服务器自动处理一切。

工作原理

智能格式选择

服务器分析每个文件并选择最优格式：

数据结构	格式	原因
统一的对象数组	TOON	节省30-60%的token
纯平面表	CSV	对简单表格最有效
深度嵌套（≥4层）	JSON	对复杂结构更好
非统一数据	JSON	更灵活的格式

自动缓存

首次访问: 分析并转换文件，创建.toon文件
后续访问: 返回缓存的.toon文件（如果是最新的）
文件修改: 当源文件更改时自动重新转换

文件排除

系统文件自动被排除：

package.json, tsconfig.json, 配置文件
IDE设置文件
锁定文件

MCP工具

服务器提供了4个MCP工具：

1. get_optimized_file_context

主要工具用于透明优化。

返回优化后的文件内容（如果有益则为TOON，否则为原始内容）及token节省统计。

2. analyze_data_efficiency

分析TOON转换是否有益。

返回关于数据结构和预计token节省的详细指标。

3. batch_convert_directory

转换目录中的所有符合条件的文件。

一次处理多个文件并返回转换摘要。

4. get_conversion_metrics

获取格式比较的详细指标。

提供token比较而不实际进行转换。

详见MCP_SERVER.md获取详细的工具文档。

配置

环境变量

在你的MCP客户端配置中设置这些变量：

变量	默认值	描述
`TOON_THRESHOLD`	0.7	转换为TOON的最小表格资格（0-1）
`AUTO_CONVERT`	true	是否自动转换文件
`CACHE_DIR`	./.toon-cache	缓存TOON文件的目录

阈值指南

0.5-0.6: 积极（可能转换混合数据）
0.7（默认）: 平衡妥协
0.8-0.9: 保守（仅高度统一的数据）
1.0: 严格（仅100%统一数组）

测试

运行测试套件

./TEST_MCP_SERVER.sh

运行17项测试覆盖：

数据分析准确性
文件优化
缓存行为
token节省计算
文件排除

交互式检查器

cd toon-context-mcp
npm run inspector

使用自己的文件与服务器工具进行交互式测试。

性能

指标	值
转换时间	典型JSON文件10-50毫秒
缓存查找	已缓存TOON文件<1毫秒
内存使用	最小（不需要流式处理）
token节省	对统一表格数据节省30-60%

实际结果

从样本数据测试中：

文件	原始token数	TOON token数	节省
users.json (5条目)	220	84	61.8%
users.json (100条目)	3,171	1,245	60.7%
products.json (50条目)	1,856	798	57.0%

项目结构

toon-context-mcp/
├── src/
│   ├── index.ts           # 主MCP服务器
│   ├── inspector.ts       # 交互式测试工具
│   ├── file-handler.ts    # 文件操作及转换逻辑
│   ├── data-analyzer.ts   # 数据结构分析
│   └── toon-utils.ts      # TOON编码/解码
├── build/                 # 编译后的JavaScript
├── examples/              # 测试数据
├── config/                # 示例配置
├── setup.sh               # 设置脚本
├── README.md              # 服务器文档
└── package.json           # 依赖项

使用场景

完美适用于

✅ 统一的对象数组 - 相同字段，基本值
✅ 大型表格数据集 - 用户列表、产品目录、分析数据
✅ API响应 - 一致的结构化数据
✅ 数据库导出 - 类似表格的数据结构

不理想适用于

❌ 深度嵌套对象 - 复杂层次数据
❌ 非统一数据 - 混合结构
❌ 小型数据集 - 开销不值得（<10条目）
❌ 配置文件 - 自动排除

故障排除

服务器无法启动

cd toon-context-mcp
rm -rf node_modules package-lock.json
npm install
npm run build

文件未转换

检查阈值：TOON_THRESHOLD=0.7
分析文件：npm run inspector → 选项2
验证数据是统一的（≥70%表格）
检查文件是否被排除（系统文件）

缓存文件过期

当源文件更改时，缓存会自动失效。要强制刷新：

rm 路径/to/file.toon

代理未使用服务器

验证MCP配置正确
检查服务器路径是绝对路径
重启MCP客户端
检查服务器日志（stderr）

文档

MCP_SERVER.md - 详细的MCP服务器指南及示例
toon-context-mcp/README.md - 技术文档
TOON格式规范 - 正式的TOON规范
模型上下文协议 - MCP规范

为什么是TOON？

TOON（面向token的对象表示法）是一种针对LLM token效率优化的格式。对于统一的表格数据，它消除了重复的键，与JSON相比减少了30-60%的token数量。

关键优势：

📉 更低的成本 - 更少的token = 更低的API成本
🚀 更长的上下文 - 在上下文窗口中容纳更多数据
⚡ 更快的响应 - 减少处理的数据量
🧠 更好的性能 - 更高效的数据显示

许可证

MIT许可证 - 查看LICENSE文件

致谢

TOON格式由Johann Schopplich创建
模型上下文协议由Anthropic创建
为集成Factory.ai Droid和其他兼容MCP的工具而构建