JSON MCP Server

Un servidor MCP de alto rendimiento para operaciones integrales con archivos JSON, que incluye lectura, escritura y consultas avanzadas, optimizado para interacciones con LLM.

GitHub
5
Prueba este MCPPatrocinado

Documentación

JSON MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) de alto rendimiento basado en Rust que proporciona operaciones integrales de archivos JSON optimizadas para interacciones con LLM. Este servidor permite a los LLM leer, escribir, consultar y manipular archivos JSON de manera eficiente, con soporte para conjuntos de datos extremadamente grandes y capacidades avanzadas de consulta.

🚀 Características

Herramientas JSON Principales

  • 📖 json-read: Lee archivos JSON con filtrado JSONPath opcional y paginación
  • ✏️ json-write: Escribe o actualiza archivos JSON con múltiples estrategias de fusión
  • 🔍 json-query: Ejecuta consultas JSONPath complejas con varios formatos de salida
  • ✅ json-validate: Valida la estructura y sintaxis JSON con diagnósticos detallados
  • ❓ json-help: Sistema de ayuda interactivo con ejemplos completos y solución de problemas

Capacidades Clave

  • Soporte para Archivos Grandes: Paginación eficiente y transmisión para archivos de cualquier tamaño
  • Consultas JSONPath: Soporte completo de JSONPath para extracción y filtrado de datos complejos
  • Escritura Flexible: Múltiples modos (reemplazar, fusión superficial, fusión profunda, agregar) con opciones de respaldo
  • Optimizado para LLM: Mensajes de error detallados y ejemplos de uso para una interacción óptima con LLM
  • Eficiencia de Memoria: Paginación inteligente que previene el desbordamiento de memoria en conjuntos de datos grandes
  • Compatible con MCP: Soporte completo del Protocolo de Contexto de Modelo con manejo adecuado de errores
  • Registro de Depuración: Registro de depuración basado en archivos para solución de problemas sin violar el protocolo MCP

📦 Instalación

Instalación Rápida

Mediante Cargo (Recomendado)

cargo install json-mcp-server

Mediante Script de Instalación

# 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

Binarios Precompilados

Descargue binarios específicos para su plataforma desde 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

Gestores de Paquetes

Debian/Ubuntu (paquetes .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 (paquetes .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

Compilación desde el Código Fuente

# 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

Verificación

Después de la instalación, verifique que funciona:

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

Uso

El JSON MCP Server se comunica mediante JSON-RPC a través de stdin/stdout siguiendo la especificación del Protocolo de Contexto de Modelo.

Primeros Pasos

  1. Inicie el servidor:

    cargo run

  2. Obtenga ayuda: Use la herramienta json-help para conocer la funcionalidad disponible:

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

Ejemplos de Uso

Lectura de Archivos JSON

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

Escritura de Datos JSON

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

Consultas con JSONPath

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

Procesamiento de Archivos Grandes

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

Referencia de Herramientas

json-read

Lee y analiza archivos JSON con filtrado JSONPath opcional y paginación.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo JSON
  • json_path (cadena, opcional): Expresión JSONPath para filtrado
  • start_index (entero, opcional): Índice inicial para paginación (predeterminado: 0)
  • limit (entero, opcional): Cantidad máxima de elementos a devolver (predeterminado: 1000)
  • output_format (cadena, opcional): Formato de salida - "json", "pretty", "compact" (predeterminado: "json")

json-write

Escribe o actualiza archivos JSON con estrategias de fusión flexibles.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo JSON
  • content (cadena, obligatorio): Contenido JSON a escribir
  • mode (cadena, opcional): Modo de escritura - "replace", "merge_shallow", "merge_deep", "append" (predeterminado: "replace")

json-query

Ejecuta consultas JSONPath en archivos JSON con varios formatos de salida.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo JSON
  • json_path (cadena, obligatorio): Expresión de consulta JSONPath
  • output_format (cadena, opcional): Formato de salida - "json", "pretty", "compact", "csv", "markdown" (predeterminado: "json")

json-validate

Valida la estructura y sintaxis de archivos JSON.

Parámetros:

  • file_path (cadena, obligatorio): Ruta al archivo JSON a validar

json-help

Obtenga ayuda completa sobre las herramientas disponibles y la sintaxis JSONPath.

Parámetros:

  • topic (cadena, opcional): Tema de ayuda - "overview", "tools", "jsonpath", "examples", "troubleshooting" (predeterminado: "overview")

Soporte JSONPath

El servidor admite la sintaxis JSONPath completa para consultar datos JSON:

  • $ - Elemento raíz
  • .field - Acceso a campos secundarios
  • [index] - Acceso a índices de matriz
  • [*] - Todos los elementos de la matriz
  • ..field - Descenso recursivo
  • [?(@.field > value)] - Expresiones de filtro
  • {field1, field2} - Proyección

Ejemplos 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 Rendimiento

Manejo de Archivos Grandes

  • Archivos de cualquier tamaño: La herramienta json-read usa automáticamente transmisión para eficiencia de memoria
  • JSON delimitado por líneas: Se detecta y procesa automáticamente de manera eficiente
  • Uso de memoria: La transmisión mantiene el uso de memoria constante independientemente del tamaño del archivo

Mejores Prácticas

  • Use consultas JSONPath específicas para filtrar datos tempranamente
  • Establezca límites razonables al procesar conjuntos de datos grandes
  • Use offset para paginar a través de grandes conjuntos de resultados
  • El servidor optimiza automáticamente según el tamaño del archivo y la memoria disponible

Manejo de Errores

El servidor proporciona mensajes de error detallados para ayudar a diagnosticar problemas:

  • Archivo no encontrado: Orientación clara sobre resolución de rutas
  • Errores de sintaxis JSON: Información de línea y columna cuando esté disponible
  • Errores JSONPath: Validación de sintaxis y sugerencias
  • Problemas de memoria: Orientación sobre alternativas de transmisión

Configuración del Cliente MCP

El JSON MCP Server funciona con cualquier cliente compatible con MCP. Guías de configuración detalladas están disponibles en el directorio examples/mcp_clients/:

Clientes Compatibles

Configuración 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 instrucciones de configuración detalladas, solución de problemas y configuraciones avanzadas, consulte las guías de cliente respectivas en el directorio examples/mcp_clients/.

Desarrollo

Estructura del Proyecto

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

Compilación

# Development build
cargo build

# Release build  
cargo build --release

# Run tests
cargo test

# Check for issues
cargo check

Dependencias

  • tokio: Tiempo de ejecución asíncrono
  • serde/serde_json: Serialización JSON
  • jsonpath-rust: Soporte de consultas JSONPath
  • anyhow: Manejo de errores
  • clap: Análisis de línea de comandos

Licencia

Este proyecto está licenciado bajo la licencia MIT OR Apache-2.0.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, asegúrese de:

  1. Que el código siga las convenciones de Rust
  2. Que todas las pruebas pasen
  3. Que las nuevas características incluyan pruebas apropiadas
  4. Que la documentación se actualice para nuevas funcionalidades

Soporte

Para problemas, preguntas o contribuciones, consulte el repositorio del proyecto.