JSON MCP Server

Um servidor MCP de alto desempenho para operações abrangentes com arquivos JSON, incluindo leitura, escrita e consultas avançadas, otimizado para interações com LLMs.

GitHub
5
Experimente este MCPPatrocinado

Documentação

JSON MCP Server

Um servidor de Protocolo de Contexto de Modelo (MCP) de alto desempenho baseado em Rust que fornece operações abrangentes de arquivos JSON otimizadas para interações com LLMs. Este servidor permite que LLMs leiam, escrevam, consultem e manipulem arquivos JSON de forma eficiente, com suporte para conjuntos de dados extremamente grandes e capacidades avançadas de consulta.

🚀 Recursos

Ferramentas JSON Principais

  • 📖 json-read: Leia arquivos JSON com filtragem JSONPath opcional e paginação
  • ✏️ json-write: Escreva ou atualize arquivos JSON com múltiplas estratégias de mesclagem
  • 🔍 json-query: Execute consultas JSONPath complexas com vários formatos de saída
  • ✅ json-validate: Valide estrutura e sintaxe JSON com diagnósticos detalhados
  • ❓ json-help: Sistema de ajuda interativo com exemplos abrangentes e solução de problemas

Principais Capacidades

  • Suporte a Arquivos Grandes: Paginação eficiente e streaming para arquivos de qualquer tamanho
  • Consultas JSONPath: Suporte completo a JSONPath para extração e filtragem complexa de dados
  • Escrita Flexível: Múltiplos modos (replace, merge_shallow, merge_deep, append) com opções de backup
  • Otimizado para LLM: Mensagens de erro detalhadas e exemplos de uso para interação ideal com LLM
  • Eficiência de Memória: Paginação inteligente evita estouro de memória em grandes conjuntos de dados
  • Conformidade com MCP: Suporte completo ao Protocolo de Contexto de Modelo com tratamento adequado de erros
  • Registro de Depuração: Registro de depuração baseado em arquivos para solução de problemas sem violar o protocolo MCP

📦 Instalação

Instalação Rápida

Via Cargo (Recomendado)

cargo install json-mcp-server

Via Script de Instalação

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/ciresnave/json-mcp-server/main/scripts/install.sh | bash

# Windows PowerShell  
iwr https://raw.githubusercontent.com/ciresnave/json-mcp-server/main/scripts/install.ps1 | iex

Binários Pré-compilados

Baixe binários específicos por plataforma em GitHub Releases:

  • Windows: json-mcp-server-v{version}-x86_64-pc-windows-msvc.zip
  • macOS: json-mcp-server-v{version}-x86_64-apple-darwin.tar.gz
  • Linux: json-mcp-server-v{version}-x86_64-unknown-linux-gnu.tar.gz

Gerenciadores de Pacotes

Debian/Ubuntu (pacotes .deb)

# Download and install .deb package
wget https://github.com/ciresnave/json-mcp-server/releases/latest/download/json-mcp-server_*_amd64.deb
sudo dpkg -i json-mcp-server_*_amd64.deb

RHEL/Fedora/CentOS (pacotes .rpm)

# Download and install .rpm package
wget https://github.com/ciresnave/json-mcp-server/releases/latest/download/json-mcp-server-*.x86_64.rpm
sudo rpm -i json-mcp-server-*.x86_64.rpm

Arch Linux (AUR)

# Manual install using PKGBUILD
wget https://github.com/ciresnave/json-mcp-server/releases/latest/download/PKGBUILD
makepkg -si

Compilando a partir do Código Fonte

# Clone the repository
git clone https://github.com/ciresnave/json-mcp-server.git
cd json-mcp-server

# Build the project
cargo build --release

# Run the server
cargo run

Verificação

Após a instalação, verifique se funciona:

json-mcp-server --version
json-mcp-server --help

Uso

O JSON MCP Server se comunica via JSON-RPC sobre stdin/stdout seguindo a especificação do Protocolo de Contexto de Modelo.

Começando

  1. Inicie o servidor:

    cargo run

  2. Obtenha ajuda: Use a ferramenta json-help para aprender sobre a funcionalidade disponível:

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "json-help",
    "arguments": {"topic": "overview"}
  }
}

Exemplo de Uso

Lendo Arquivos JSON

{
  "name": "json-read",
  "arguments": {
    "file_path": "./data.json",
    "json_path": "$.users[*].name",
    "format": "pretty"
  }
}

Escrevendo Dados JSON

{
  "name": "json-write", 
  "arguments": {
    "file_path": "./config.json",
    "data": {"setting": "value", "enabled": true},
    "mode": "merge"
  }
}

Consultando com JSONPath

{
  "name": "json-query",
  "arguments": {
    "file_path": "./products.json", 
    "query": "$.products[?(@.price > 100)].name",
    "format": "table"
  }
}

Processando Arquivos Grandes

{
  "name": "json-read",
  "arguments": {
    "file_path": "./large-dataset.json",
    "json_path": "$.records[*].id", 
    "limit": 1000,
    "offset": 0
  }
}

Referência de Ferramentas

json-read

Leia e analise arquivos JSON com filtragem JSONPath opcional e paginação.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo JSON
  • json_path (string, opcional): Expressão JSONPath para filtragem
  • start_index (inteiro, opcional): Índice inicial para paginação (padrão: 0)
  • limit (inteiro, opcional): Número máximo de itens a retornar (padrão: 1000)
  • output_format (string, opcional): Formato de saída - "json", "pretty", "compact" (padrão: "json")

json-write

Escreva ou atualize arquivos JSON com estratégias de mesclagem flexíveis.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo JSON
  • content (string, obrigatório): Conteúdo JSON a escrever
  • mode (string, opcional): Modo de escrita - "replace", "merge_shallow", "merge_deep", "append" (padrão: "replace")

json-query

Execute consultas JSONPath em arquivos JSON com vários formatos de saída.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo JSON
  • json_path (string, obrigatório): Expressão de consulta JSONPath
  • output_format (string, opcional): Formato de saída - "json", "pretty", "compact", "csv", "markdown" (padrão: "json")

json-validate

Valide a estrutura e sintaxe de arquivos JSON.

Parâmetros:

  • file_path (string, obrigatório): Caminho para o arquivo JSON a validar

json-help

Obtenha ajuda abrangente sobre as ferramentas disponíveis e a sintaxe JSONPath.

Parâmetros:

  • topic (string, opcional): Tópico de ajuda - "overview", "tools", "jsonpath", "examples", "troubleshooting" (padrão: "overview")

Suporte a JSONPath

O servidor suporta sintaxe JSONPath completa para consulta de dados JSON:

  • $ - Elemento raiz
  • .field - Acesso a campo filho
  • [index] - Acesso a índice de array
  • [*] - Todos os elementos do array
  • ..field - Descida recursiva
  • [?(@.field > value)] - Expressões de filtro
  • {field1, field2} - Projeção

Exemplos de JSONPath

# Get all user names
$.users[*].name

# Filter users over 25
$.users[?(@.age > 25)]

# Get nested data
$.data.items[*].details.price

# All prices anywhere in document  
$..price

# Complex filtering
$.products[?(@.category == 'electronics' && @.price < 500)].name

Notas de Desempenho

Manipulação de Arquivos Grandes

  • Arquivos de qualquer tamanho: A ferramenta json-read usa automaticamente streaming para eficiência de memória
  • JSON delimitado por linhas: Detectado e processado automaticamente de forma eficiente
  • Uso de memória: Streaming mantém o uso de memória constante independentemente do tamanho do arquivo

Melhores Práticas

  • Use consultas JSONPath específicas para filtrar dados antecipadamente
  • Defina limites razoáveis ao processar grandes conjuntos de dados
  • Use offset para paginação em grandes conjuntos de resultados
  • O servidor otimiza automaticamente para o tamanho do arquivo e memória disponível

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para ajudar a diagnosticar problemas:

  • Arquivo não encontrado: Orientação clara de resolução de caminho
  • Erros de sintaxe JSON: Informações de linha e coluna quando disponíveis
  • Erros de JSONPath: Validação de sintaxe e sugestões
  • Problemas de memória: Orientação sobre alternativas de streaming

Configuração do Cliente MCP

O JSON MCP Server funciona com qualquer cliente compatível com MCP. Guias de configuração detalhados estão disponíveis no diretório examples/mcp_clients/:

Clientes Suportados

Configuração Rápida

VS Code + GitHub Copilot:

{
  "mcp.servers": {
    "json-mcp-server": {
      "path": "json-mcp-server"
    }
  }
}

Claude Desktop:

{
  "mcpServers": {
    "json-mcp-server": {
      "command": "json-mcp-server",
      "args": []
    }
  }
}

Para instruções detalhadas de configuração, solução de problemas e configurações avançadas, consulte os guias de cliente respectivos no diretório examples/mcp_clients/.

Desenvolvimento

Estrutura do Projeto

json-mcp-server/
├── src/                    # Source code
│   ├── main.rs            # Application entry point and MCP server
│   ├── lib.rs             # Library exports for testing
│   ├── mcp/               # MCP protocol implementation
│   │   ├── mod.rs
│   │   ├── protocol.rs    # Protocol definitions and types
│   │   └── server.rs      # MCP server implementation
│   └── json_tools/        # JSON tool implementations
│       ├── mod.rs
│       ├── handler.rs     # Tool coordination and help system
│       ├── operations.rs  # Read/write/validate operations
│       ├── query.rs       # JSONPath querying with multiple formats
│       └── streaming.rs   # Large file streaming and pagination
├── tests/                 # Integration tests
│   └── integration_tests.rs
├── examples/              # Example configurations and data
│   ├── mcp_clients/       # Client configuration guides
│   │   ├── vscode.md      # VS Code setup
│   │   ├── claude-desktop.md
│   │   ├── github-copilot.md
│   │   ├── generic.md     # Generic MCP client setup
│   │   ├── client_implementation.md
│   │   └── python_client.py
│   ├── sample-data.json   # Sample test data
│   ├── test-commands.jsonl
│   └── test-output.json
├── dev_tools/             # Development and testing utilities
│   ├── README.md          # Development tools documentation
│   └── testing/           # Test scripts and utilities
│       ├── test_all_tools.py
│       ├── test_multiple_instances.py
│       ├── test_json_help.py
│       └── [other test files]
├── Cargo.toml            # Rust project configuration
└── README.md             # This file

Compilação

# Development build
cargo build

# Release build  
cargo build --release

# Run tests
cargo test

# Check for issues
cargo check

Dependências

  • tokio: Runtime assíncrono
  • serde/serde_json: Serialização JSON
  • jsonpath-rust: Suporte a consultas JSONPath
  • anyhow: Tratamento de erros
  • clap: Análise de linha de comando

Licença

Este projeto é licenciado sob a licença MIT OR Apache-2.0.

Contribuição

Contribuições são bem-vindas! Por favor, garanta:

  1. O código segue as convenções do Rust
  2. Todos os testes passam
  3. Novos recursos incluem testes apropriados
  4. A documentação é atualizada para novas funcionalidades

Suporte

Para problemas, perguntas ou contribuições, consulte o repositório do projeto.