Json diff

MCP JSONDiff Kel

基于 Model Context Protocol (MCP) 的高效JSON对比工具，专为AI对话场景设计。

📋 项目简介

在AI辅助开发过程中，JSON对比常常遇到以下问题：

1. 准确性不足: 传统AI对比方法可能存在误判
2. 理解偏差: AI可能误解需求，生成对比代码而非直接对比结果
3. 输出冗长: 对比结果过于详细，难以快速获取关键信息

本项目通过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 对比

演示视频

https://www.bilibili.com/video/BV1yYh2zNEcY/?spm_id_from=333.1387.homepage.video_card.click&vd_source=1a77b8b856c66190a0ab82a7acb92136

🚀 项目特性

• 🔍 智能对比: 基于 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: 构建系统

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 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 - [email protected]

🙏 致谢

• Model Context Protocol - 提供MCP协议标准
• DeepDiff - 强大的差异检测库
• FastMCP - 高效的MCP实现框架

📞 支持与反馈

如果您在使用过程中遇到问题或有改进建议，请：

1. 在 GitHub Issues 中提交问题
2. 发送邮件至 [email protected]
3. 参与社区讨论

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！