JSON Diff

MCP JSONDiff Kel

Ferramenta eficiente de comparação JSON baseada no Model Context Protocol (MCP), projetada especificamente para cenários de conversação com IA.

📋 Visão Geral do Projeto

Durante o desenvolvimento assistido por IA, a comparação de JSON frequentemente enfrenta os seguintes problemas:

1. Precisão insuficiente: Métodos tradicionais de comparação por IA podem gerar erros de julgamento
2. Desvios de compreensão: A IA pode interpretar mal os requisitos, gerando código de comparação em vez de resultados diretos de comparação
3. Saída extensa: Resultados de comparação excessivamente detalhados, dificultando a obtenção rápida de informações essenciais

Este projeto fornece um serviço padronizado de comparação JSON por meio do protocolo MCP, garantindo que a IA possa concluir tarefas de comparação JSON com precisão e rapidez.

🛠️ Guia de Implantação

Usando uvx (recomendado)

uvx mcp-jsondiff-kel@latest

Usando pip

pip install mcp-jsondiff-kel

Instalação a partir do código-fonte

git clone https://github.com/your-username/mcp-jsondiff.git
cd mcp-jsondiff
pip install -e .

Configuração do aplicativo

Configuração do Claude Desktop

Adicione a seguinte configuração ao arquivo de configuração do aplicativo:

{
  "mcpServers": {
    "mcp_jsondiff": {
      "command": "uvx",
      "args": [
        "mcp-jsondiff-kel@latest"
      ]
    }
  }
}

Configuração do Cherry Studio

{
  "mcpServers": {
    "mcp_jsondiff": {
      "command": "uvx",
      "args": [
        "mcp-jsondiff-kel@latest"
      ]
    }
  }
}

📖 Exemplos de uso

A demonstração usa o Cherry Studio para apresentação

Primeiro, selecione esta ferramenta mcp na caixa de diálogo Em seguida, insira um texto semelhante ao exemplo abaixo para realizar a comparação json对比,预期值:{"a":1,"b":2}, 实际值:{"a":1,"b":2}

Comparação de strings

Comparação de JSON

Comparação de JSON com escape

Comparação de JSON aninhado

Vídeo de demonstração

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

🚀 Recursos do projeto

• 🔍 Comparação inteligente: Detecção profunda de diferenças em JSON baseada na biblioteca deepdiff
• ⚡ Resposta rápida: Algoritmo de comparação otimizado, suporta documentos JSON de grande porte
• 🔄 Entrada flexível: Suporta dois formatos de entrada: strings JSON e objetos de dicionário
• 📊 Saída clara: Relatório de diferenças estruturado, localização rápida de problemas
• 🔧 Integração MCP: Integração perfeita com aplicativos de IA que suportam o protocolo MCP
• 🐍 Python nativo: Baseado em Python 3.13+, com desempenho superior

🔧 Documentação da API

Ferramenta principal: jsonDiff

Função: Compara dois objetos ou strings JSON e retorna informações detalhadas sobre as diferenças

Parâmetros:

• expectKey (Union[str, dict]): Valor JSON esperado, aceita strings JSON ou objetos de dicionário
• actualKey (Union[str, dict]): Valor JSON real, aceita strings JSON ou objetos de dicionário

Valor de retorno:

{
  "differences": "DeepDiff对象，包含所有差异信息",
  "is_identical": "布尔值，表示两个JSON是否完全一致",
  "message": "字符串，描述对比结果或错误信息"
}

Recursos:

• Ignora automaticamente diferenças na ordem de arrays (ignore_order=True)
• Suporta comparação de estruturas JSON aninhadas
• Tratamento inteligente de erros, fornecendo mensagens de erro claras

🧪 Depuração e testes

Depuração com o inspetor MCP

npx @modelcontextprotocol/inspector uvx mcp-jsondiff-kel

Executando testes localmente

cd src/mcp_jsondiff_kel
python server.py

🏗️ Estrutura do projeto

mcp-jsondiff/
├── pyproject.toml          # 项目配置和依赖
├── README.md              # 项目文档
├── src/
│   └── mcp_jsondiff_kel/
│       ├── __init__.py    # 包入口点
│       ├── __main__.py    # 命令行入口
│       └── server.py      # MCP服务器核心逻辑
└── uv.lock               # 依赖锁定文件

🔧 Pilha tecnológica

• Python 3.13+: Ambiente de execução principal
• FastMCP: Framework de implementação do protocolo MCP
• DeepDiff: Mecanismo de detecção de diferenças JSON
• Hatchling: Sistema de build

🤝 Guia de contribuição

Aceitamos contribuições da comunidade! Siga os passos abaixo:

1. Faça um fork deste repositório
2. Crie um branch de funcionalidade (git checkout -b feature/AmazingFeature)
3. Envie suas alterações (git commit -m 'Add some AmazingFeature')
4. Envie para o branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Configuração do ambiente de desenvolvimento

# 克隆仓库
git clone https://github.com/your-username/mcp-jsondiff.git
cd mcp-jsondiff

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
python -m pytest

📝 Registro de alterações

v0.1.5

• Lançamento da versão inicial
• Suporte à funcionalidade básica de comparação JSON
• Integração com o protocolo MCP
• Tratamento de erros e formato de saída amigável ao usuário

📄 Licença

Este projeto é licenciado sob a licença MIT — consulte o arquivo LICENSE para mais detalhes.

👥 Autores

• yohan - 2220041897@qq.com

🙏 Agradecimentos

• Model Context Protocol - Fornece o padrão do protocolo MCP
• DeepDiff - Poderosa biblioteca de detecção de diferenças
• FastMCP - Framework eficiente de implementação MCP

📞 Suporte e feedback

Se você encontrar problemas durante o uso ou tiver sugestões de melhoria, por favor:

1. Abra uma issue em GitHub Issues
2. Envie um e-mail para 2220041897@qq.com
3. Participe das discussões da comunidade

---

⭐ Se este projeto foi útil para você, dê-nos uma estrela!