JSON Diff

A JSON diff tool to compare two JSON strings.

GitHub

MCP JSONDiff Kel

Python 3.13+ License Version

基于 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 工具image-20250828221215427 然后输入形如如下的文案即可进行对比 json对比,预期值:{"a":1,"b":2}, 实际值:{"a":1,"b":2}

字符串对比

image-20250828221334908

json 对比

image-20250828221439044

转义后的 json 对比

image-20250828221359169

嵌套 json 对比

image-20250828221531975

演示视频

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 文件了解详情。

👥 作者

🙏 致谢

📞 支持与反馈

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

  1. 在 GitHub Issues 中提交问题
  2. 发送邮件至 2220041897@qq.com
  3. 参与社区讨论

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

Related Servers