README.md
Efficient JSON comparison tool for AI dialogue scenarios using deepdiff.
MCP JSONDiff Kel
基于 Model Context Protocol (MCP) 的高效JSON对比工具，专为AI对话场景设计。
📋 项目简介
在AI辅助开发过程中，JSON对比常常遇到以下问题：
- 准确性不足: 传统AI对比方法可能存在误判
- 理解偏差: AI可能误解需求，生成对比代码而非直接对比结果
- 输出冗长: 对比结果过于详细，难以快速获取关键信息
本项目通过MCP协议提供标准化的JSON对比服务，确保AI能够准确、快速地完成JSON对比任务。
🛠️ 部署指南
使用 uvx（推荐）
uvx mcp-jsondiff-kel@latest
使用 pip
pip install mcp-jsondiff-kel
从源码安装
git clone https://github.com/your-username/mcp-jsondiff.git
cd mcp-jsondiff
pip install -e .
应用配置
Claude Desktop 配置
在应用配置文件中添加以下配置：
{
"mcpServers": {
"mcp_jsondiff": {
"command": "uvx",
"args": [
"mcp-jsondiff-kel@latest"
]
}
}
}
Cherry Studio 配置
{
"mcpServers": {
"mcp_jsondiff": {
"command": "uvx",
"args": [
"mcp-jsondiff-kel@latest"
]
}
}
}
📖 使用示例
演示示例用 Cherry Studio进行演示
首先在对话框中选择此 mcp 工具
然后输入形如如下的文案即可进行对比 json对比,预期值:{"a":1,"b":2}, 实际值:{"a":1,"b":2}
字符串对比
json 对比
转义后的 json 对比
嵌套 json 对比
演示视频
🚀 项目特性
- 🔍 智能对比: 基于
deepdiff库的深度JSON差异检测 - ⚡ 快速响应: 优化的对比算法，支持大型JSON文档
- 🔄 灵活输入: 支持JSON字符串和字典对象两种输入格式
- 📊 清晰输出: 结构化的差异报告，快速定位问题
- 🔧 MCP集成: 无缝集成到支持MCP协议的AI应用中
- 🐍 Python原生: 基于Python 3.13+，性能优异
🔧 API 文档
核心工具：`jsonDiff`
功能: 对比两个JSON对象或字符串，返回详细的差异信息
参数:
expectKey(Union[str, dict]): 期望的JSON值，支持JSON字符串或字典对象actualKey(Union[str, dict]): 实际的JSON值，支持JSON字符串或字典对象
返回值:
{
"differences": "DeepDiff对象，包含所有差异信息",
"is_identical": "布尔值，表示两个JSON是否完全一致",
"message": "字符串，描述对比结果或错误信息"
}
特性:
- 自动忽略数组顺序差异 (
ignore_order=True) - 支持嵌套JSON结构对比
- 智能错误处理，提供清晰的错误信息
🧪 调试与测试
使用MCP检查器调试
npx @modelcontextprotocol/inspector uvx mcp-jsondiff-kel
本地运行测试
cd src/mcp_jsondiff_kel
python server.py
🏗️ 项目结构
mcp-jsondiff/
├── pyproject.toml # 项目配置和依赖
├── README.md # 项目文档
├── src/
│ └── mcp_jsondiff_kel/
│ ├── __init__.py # 包入口点
│ ├── __main__.py # 命令行入口
│ └── server.py # MCP服务器核心逻辑
└── uv.lock # 依赖锁定文件
🔧 技术栈
- Python 3.13+: 核心运行时
- FastMCP: MCP协议实现框架
- DeepDiff: JSON差异检测引擎
- Hatchling: 构建系统
🤝 贡献指南
我们欢迎社区贡献！请遵循以下步骤：
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
开发环境设置
# 克隆仓库
git clone https://github.com/your-username/mcp-jsondiff.git
cd mcp-jsondiff
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
python -m pytest
📝 更新日志
v0.1.5
- 初始版本发布
- 支持基础JSON对比功能
- MCP协议集成
- 错误处理和用户友好的输出格式
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
👥 作者
- yohan - 2220041897@qq.com
🙏 致谢
- Model Context Protocol - 提供MCP协议标准
- DeepDiff - 强大的差异检测库
- FastMCP - 高效的MCP实现框架
📞 支持与反馈
如果您在使用过程中遇到问题或有改进建议，请：
- 在 GitHub Issues 中提交问题
- 发送邮件至 2220041897@qq.com
- 参与社区讨论
⭐ 如果这个项目对您有帮助，请给我们一个星标！
Tools (1)
jsonDiffCompare two JSON objects or strings and return detailed difference information.Configuration
claude_desktop_config.json
{"mcpServers": {"mcp_jsondiff": {"command": "uvx", "args": ["mcp-jsondiff-kel@latest"]}}}Try it
→Compare these two JSON objects and tell me the differences: expected: {"a":1,"b":2}, actual: {"a":1,"b":3}
→Check if these two JSON strings are identical, ignoring array order.
→Perform a deep comparison of these nested JSON structures to find missing keys.
→Compare this escaped JSON string with the following dictionary object.