mcp-graphql-enhanced

Un servidor MCP (Model Context Protocol) mejorado para GraphQL que soluciona problemas de interoperabilidad del mundo real entre LLMs y APIs de GraphQL.

Reemplazo directo para mcp-graphql — con cabeceras dinámicas, análisis robusto de variables y sin cambios disruptivos.

💬 Comunidad y Soporte

¡Únete a la conversación! Si tienes preguntas sobre el uso de este puente con Neo4j, grafos de datos de Discord o GraphQL en general, ven a pasar el rato con nosotros:

• Canal de Discord: #mcp-graphql-enhanced

• Servidor: El Discord oficial de GraphQL

Este es el mejor lugar para compartir tus comentarios, informar de problemas o sugerir nuevas funciones "mejoradas" para el puente.

Related MCP server: mcp-graphql-schema

✨ Mejoras clave

• ✅ IDE GraphiQL integrado — Entorno visual en http://localhost:MCP_PORT/ (o /graphiql) con cabeceras preconfiguradas.

• ✅ Transporte dual — Soporta tanto STDIO (para herramientas CLI/cliente locales) como HTTP/JSON-RPC (para clientes externos/navegador).

• ✅ Cabeceras dinámicas — pasa Authorization, X-API-Key, etc., mediante argumentos de herramienta (sin reinicios de configuración)

• ✅ Análisis robusto de variables — soluciona el error “Query variables must be a null or an object”

• ✅ Introspección filtrada — solicita solo tipos específicos (p. ej., typeNames: ["Query", "User"]) para reducir el ruido en el contexto del LLM

• ✅ Compatibilidad total con MCP — funciona con Claude Desktop, Cursor, Glama

• ✅ Seguro por defecto — mutaciones deshabilitadas a menos que se habiliten explícitamente

• ✅ Evolución dinámica del esquema — Diagnósticos inteligentes y análisis de brechas para servidores que regeneran tipos de GraphQL sobre la marcha (como Neo4j).

• ✅ Observabilidad profunda — Extracción y limpieza automática de Cypher desde extensiones de GraphQL.

🚀 Difusión multi-endpoint (Experimental en v3.9.0+)

A partir de la versión v3.9.0, el servidor admite realizar consultas a múltiples endpoints de GraphQL simultáneamente. Esto se diseñó originalmente para sincronizar mutaciones en diferentes entornos (p. ej., backends de Node.js y Python), pero abre posibilidades poderosas para la agregación de datos.

• Sin cambios disruptivos: Si proporcionas una única URL en ENDPOINT, el servidor se comporta exactamente igual que antes.

• Agregación inteligente: Cuando se proporcionan múltiples URLs separadas por comas, el servidor difunde la consulta a todas ellas y fusiona los arrays resultantes.

• Evitar límites de nivel gratuito: Perfecto para usuarios de bases de datos en la nube de "Nivel Gratuito" (como Neo4j Aura). Puedes dividir tus datos en múltiples instancias gratuitas y usar este puente para consultarlos como un único grafo unificado, evitando eficazmente las limitaciones de recuento de entidades.

• Deduplicación: El puente elimina automáticamente los objetos duplicados basándose en sus campos únicos para mantener limpio el contexto de la IA.

⚠️ Úsalo bajo tu propia responsabilidad: Esta función asume que todos los endpoints comparten el mismo esquema de GraphQL (o uno muy similar). La introspección se realiza contra el primer endpoint de la lista.

💡 Caso de uso: Conectar WSL y Windows (PowerShell)

Un desafío común para los desarrolladores de Windows es el aislamiento de red entre el Subsistema de Windows para Linux (WSL) y el SO anfitrión. Esta función te permite conectar estos dos mundos en un "Sistema Nervioso Unificado".

Configuración de ejemplo para Claude Desktop:

{
  "ENDPOINT": "http://DESKTOP-NAME.local:2311/graphql,http://127.0.0.1:4000/graphql"
}

• Ecosistema híbrido: Consulta y agrega datos sin problemas entre procesos nativos de Windows (PowerShell) y entornos basados en Linux (WSL).

• Soporte mDNS: Al usar direcciones .local, el puente resuelve automáticamente la IP de la máquina anfitriona desde dentro del entorno WSL.

• Agregación transparente: El asistente de IA interactúa con un esquema unificado único, sin saber que los datos se están obteniendo de diferentes sistemas operativos simultáneamente.

🔍 Observabilidad avanzada y Cypher

El puente proporciona información detallada sobre cómo el LLM interactúa con tu base de datos de grafos.

🕸️ Extracción automatizada de Cypher

Para implementaciones de servidores GraphQL que devuelven planes de ejecución de consultas (como @neo4j/graphql), el puente automáticamente:

1. Detecta extensions.cypher en la respuesta.

2. Sanea la salida eliminando cabeceras internas (como CYPHER 5 o PARAMS vacíos).

3. Inyecta un bloque de Cypher limpio directamente en la salida de la herramienta para que la IA lo analice.

Nota: Esta función requiere que tu servidor GraphQL esté configurado para incluir información de depuración en las extensiones de respuesta.

🎨 Centro de comando visual (GraphiQL)

A diferencia de los servidores MCP estándar, este proporciona una interfaz visual para humanos. Al ejecutarlo con ENABLE_HTTP=true, puedes abrir un IDE GraphiQL completo en tu navegador.

• Endpoint: http://localhost:6274/ (o /graphiql)

• Sincronización de cabeceras: Cualquier cabecera configurada en tu entorno (como tokens de GitHub) se inyecta automáticamente en la pestaña "Headers" de GraphiQL para pruebas inmediatas.

💻 HTTP / Transporte dual

Este servidor ahora se ejecuta en modo de transporte dual, soportando tanto la comunicación STDIO estándar (utilizada por la mayoría de los clientes MCP) como un nuevo endpoint HTTP JSON-RPC en el puerto 6274.

Esto permite que sistemas externos, aplicaciones web y comandos curl directos accedan a las herramientas del servidor con registro de solicitudes en vivo en tu terminal (registros [HTTP-RPC]).

Selección automática de puerto

El servidor utiliza por defecto el puerto 6274. Si encuentras un error EADDRINUSE, el servidor encontrará automáticamente el siguiente puerto disponible. Revisa los registros del servidor para ver el puerto final vinculado (p. ej., [HTTP] Started server on http://localhost:6275).

Resolución de conflictos de puerto (EADDRINUSE) y selección automática

El servidor utiliza por defecto el puerto 6274. Si encuentras un error EADDRINUSE: address already in use :::6274 (común en el desarrollo local debido a procesos antiguos), el servidor encontrará automáticamente el siguiente puerto disponible (hasta 10 intentos, sin generar múltiples servidores).

Esto asegura que el servidor se inicie correctamente incluso cuando el puerto predeterminado está bloqueado. Revisa siempre los registros del servidor para ver el puerto final vinculado (p. ej., [HTTP] Started server on http://localhost:6275) si tu curl o herramienta cliente falla en el 6274 predeterminado.

Para forzar un puerto específico (p. ej., para configuraciones de firewall externo garantizadas), aún puedes establecer explícitamente la variable de entorno MCP_PORT:

Prueba del endpoint HTTP

Puedes probar el endpoint usando curl siempre que el servidor esté ejecutándose (p. ej., mediante npm run dev):

# Test the health check (assuming the server bound to the default or found the next available port)
curl http://localhost:6274/health

# Example: Test the query tool via JSON-RPC (using port 6275 if 6274 was busy)
curl -X POST http://localhost:6275/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"query-graphql","params":{"query":"query { __typename }"},"id":1}'

## 🔍 Filtered Introspection
Avoid 50k-line schema dumps. Ask for only what you need:
`@introspect-schema typeNames ["Query", "User"]`
## 🔍 Debug & Inspect
Use the official MCP Inspector to test your server live:
```bash
npx @modelcontextprotocol/inspector \
  -e ENDPOINT=https://api.example.com/graphql \
  npx @letoribo/mcp-graphql-enhanced

Variables de entorno (Cambio disruptivo en 1.0.0)

Nota: A partir de la versión 1.0.0, los argumentos de línea de comandos han sido reemplazados por variables de entorno.

• auto (predeterminado): Habilita automáticamente HTTP solo cuando se ejecuta en el Inspector MCP...

• true: Habilitar siempre el servidor HTTP

• false: Deshabilitar completamente el servidor HTTP

Ejemplos

# Basic usage
ENDPOINT=http://localhost:3000/graphql npx @letoribo/mcp-graphql-enhanced
# With auth header
ENDPOINT=https://api.example.com/graphql \
HEADERS='{"Authorization":"Bearer xyz"}' \
npx @letoribo/mcp-graphql-enhanced
# Enable mutations
ENDPOINT=http://localhost:3000/graphql \
ALLOW_MUTATIONS=true \
npx @letoribo/mcp-graphql-enhanced
# Use local schema file
ENDPOINT=http://localhost:3000/graphql \
SCHEMA=./schema.graphql \
npx @letoribo/mcp-graphql-enhanced
# Change the HTTP port
MCP_PORT=8080 npx @letoribo/mcp-graphql-enhanced
# Disable HTTP transport (fastest, recommended for Claude Desktop)
ENABLE_HTTP=false npx @letoribo/mcp-graphql-enhanced
# Test the surgical precision and the IDE immediately:
ENDPOINT=https://api.github.com/graphql \
HEADERS='{"Authorization":"Bearer YOUR_GITHUB_TOKEN"}' \
ENABLE_HTTP=true \
npx @letoribo/mcp-graphql-enhanced

# Then visit http://localhost:6274/graphiql

🖥️ Ejemplos de configuración de Claude Desktop

Puedes conectar Claude Desktop a tu API de GraphQL usando el paquete npx (recomendado por simplicidad) o la imagen de Docker (ideal para reproducibilidad y aislamiento).

✅ Opción 1: Usando npx

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "npx",
      "args": ["@letoribo/mcp-graphql-enhanced"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql"
      }
    }
  }
}

🐳 Opción 2: Usando Docker (soporta auto-pull)

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "sh",
      "args": [
        "-c",
        "docker run --rm -i -e ENDPOINT=$ENDPOINT -e HEADERS=$HEADERS -e ALLOW_MUTATIONS=$ALLOW_MUTATIONS ghcr.io/letoribo/mcp-graphql-enhanced:main"
      ],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "HEADERS": "{\"Authorization\": \"Bearer YOUR_TOKEN\"}",
        "ALLOW_MUTATIONS": "false"
      }
    }
  }
}

🧪 Opción 3: Usando node con compilación local (para desarrollo)

Si has clonado el repositorio y compilado el proyecto (npm run build → genera en dist/):

{
  "mcpServers": {
    "mcp-graphql-enhanced": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "ENDPOINT": "https://your-api.com/graphql",
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}

Recursos

• graphql-schema: El servidor expone el esquema de GraphQL como un recurso al que los clientes pueden acceder. Esto es el archivo de esquema local, un archivo de esquema alojado en una URL o basado en una consulta de introspección.

Herramientas disponibles

El servidor proporciona dos herramientas principales:

1. introspect-schema: Esta herramienta recupera el esquema de GraphQL o un subconjunto filtrado (mediante typeNames). Úsala primero si no tienes acceso al esquema como recurso. Esto utiliza el archivo de esquema local, un archivo de esquema alojado en una URL o una consulta de introspección. La introspección filtrada (typeNames) solo está disponible cuando se utiliza un endpoint de GraphQL en vivo (no con archivo SCHEMA o URL).

2. query-graphql: Ejecuta consultas de GraphQL contra el endpoint. Por defecto, las mutaciones están deshabilitadas a menos que ALLOW_MUTATIONS se establezca en true.

Consideraciones de seguridad

Las mutaciones están deshabilitadas por defecto para evitar cambios de datos no deseados. Valida siempre las entradas de HEADERS y SCHEMA en producción. Usa endpoints HTTPS y tokens de corta duración siempre que sea posible.

Personaliza para tu propio servidor

Esta es una implementación muy genérica que permite una introspección completa y que tus usuarios hagan lo que quieran (incluyendo mutaciones). Si necesitas una implementación más específica, te sugeriría crear tu propio MCP y restringir la llamada a herramientas para que los clientes solo ingresen campos de consulta y/o variables específicos. Puedes usar esto como referencia.