# MCP JSONDiff Kel
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://pypi.org/project/mcp-jsondiff-kel/)
基于 Model Context Protocol (MCP) 的高效JSON对比工具，专为AI对话场景设计。
## 📋 项目简介
在AI辅助开发过程中，JSON对比常常遇到以下问题：
1. **准确性不足**: 传统AI对比方法可能存在误判
2. **理解偏差**: AI可能误解需求，生成对比代码而非直接对比结果
3. **输出冗长**: 对比结果过于详细，难以快速获取关键信息
本项目通过MCP协议提供标准化的JSON对比服务，确保AI能够准确、快速地完成JSON对比任务。
## 🛠️ 部署指南
### 使用 uvx（推荐）
```bash
uvx mcp-jsondiff-kel@latest
```
### 使用 pip
```bash
pip install mcp-jsondiff-kel
```
### 从源码安装
```bash
git clone https://github.com/your-username/mcp-jsondiff.git
cd mcp-jsondiff
pip install -e .
```
### 应用配置
#### Claude Desktop 配置
在应用配置文件中添加以下配置：
```json
{
"mcpServers": {
"mcp_jsondiff": {
"command": "uvx",
"args": [
"mcp-jsondiff-kel@latest"
]
}
}
}
```
#### Cherry Studio 配置
```json
{
"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字符串或字典对象
**返回值**:
```json
{
"differences": "DeepDiff对象，包含所有差异信息",
"is_identical": "布尔值，表示两个JSON是否完全一致",
"message": "字符串，描述对比结果或错误信息"
}
```
**特性**:
- 自动忽略数组顺序差异 (`ignore_order=True`)
- 支持嵌套JSON结构对比
- 智能错误处理，提供清晰的错误信息
## 🧪 调试与测试
### 使用MCP检查器调试
```bash
npx @modelcontextprotocol/inspector uvx mcp-jsondiff-kel
```
### 本地运行测试
```bash
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
### 开发环境设置
```bash
# 克隆仓库
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](LICENSE) 文件了解详情。
## 👥 作者
- **yohan** - [2220041897@qq.com](mailto:2220041897@qq.com)
## 🙏 致谢
- [Model Context Protocol](https://modelcontextprotocol.io/) - 提供MCP协议标准
- [DeepDiff](https://github.com/seperman/deepdiff) - 强大的差异检测库
- [FastMCP](https://github.com/jlowin/fastmcp) - 高效的MCP实现框架
## 📞 支持与反馈
如果您在使用过程中遇到问题或有改进建议，请：
1. 在 [GitHub Issues](https://github.com/your-username/mcp-jsondiff/issues) 中提交问题
2. 发送邮件至 [2220041897@qq.com](mailto:2220041897@qq.com)
3. 参与社区讨论
---
⭐ 如果这个项目对您有帮助，请给我们一个星标！
