Servidor MCP GraphQL de Hasura avanzado

Versión: 1.1.0

Este servidor de Protocolo de Contexto de Modelo (MCP) proporciona una interfaz avanzada para que los agentes de IA (como los de Cursor o Claude Desktop) interactúen con un endpoint GraphQL de Hasura. Permite a los agentes descubrir la estructura de la API, ejecutar consultas de solo lectura y mutaciones (con precaución), previsualizar datos, realizar agregaciones y comprobar el estado del servicio.

Este servidor mejora las capacidades de LLM al permitirles aprovechar su API Hasura de forma dinámica en función de solicitudes de lenguaje natural.

Características

Este servidor expone las siguientes capacidades de MCP:

Recursos:

• Esquema Hasura GraphQL ( hasura:/schema )
  • Proporciona la definición completa del esquema GraphQL obtenida mediante introspección estándar.
  • Tipo MIME: application/json
  • Los agentes pueden leer este recurso para comprender la estructura completa de la API, incluidos tipos, campos, argumentos, directivas, etc.

Herramientas:

• run_graphql_query
  • Descripción: Ejecuta una consulta GraphQL de solo lectura en el endpoint de Hasura. Úselo para obtener datos cuando una herramienta específica no esté disponible. Asegúrese de que la consulta no modifique los datos. Ejemplo: query { users { id name } }
  • Entrada: { query: string, variables?: object }
  • Nota: Realiza una comprobación básica para evitar la ejecución de cadenas que empiezan por mutation . Se basa principalmente en que la consulta sea de solo lectura.
• run_graphql_mutation
  • Descripción: Ejecuta una mutación de GraphQL para insertar, actualizar o eliminar datos. Úselo con precaución y asegúrese de que la operación sea segura y esté diseñada para el propósito previsto. Depende de los permisos de Hasura configurados para el secreto de administrador proporcionado o el rol predeterminado. Ejemplo: mutation { insert_users_one(object: {name: "Test"}) { id } }
  • Entrada: { mutation: string, variables?: object }
  • Seguridad: Permite cualquier mutación permitida por el rol de Hasura. Asegúrese de que los permisos de Hasura estén configurados correctamente.
• list_tables
  • Descripción: Enumera las tablas (o colecciones) de datos disponibles gestionadas por Hasura, organizadas por esquema con descripciones, basándose en heurísticas de introspección (busca tipos de objeto con un campo 'id', excluyendo tipos internos/agregados). Útil para descubrir las fuentes de datos disponibles.
  • Entrada: { schemaName?: string } (nombre de esquema opcional, intenta inferir a partir de las descripciones de los campos si es posible, el valor predeterminado es 'público' conceptualmente)
• describe_table
  • Descripción: Muestra la estructura de una tabla específica incluyendo todas sus columnas (campos) con sus tipos y descripciones GraphQL.
  • Entrada: { tableName: string, schemaName?: string }
• list_root_fields
  • Descripción: Enumera los campos de consulta, mutación o suscripción de nivel superior disponibles en el esquema GraphQL. Resulta útil para comprender los principales puntos de entrada de las operaciones.
  • Entrada: { fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' } (Filtro opcional)
• describe_graphql_type
  • Descripción: Proporciona detalles sobre un tipo específico de GraphQL (Objeto, Entrada, Escalar, Enumeración, Interfaz, Unión) mediante introspección de esquemas. Esencial para comprender cómo estructurar consultas o mutaciones que involucran tipos específicos.
  • Entrada: { typeName: string } (nombre de tipo que distingue entre mayúsculas y minúsculas)
• preview_table_data
  • Descripción: Obtiene una muestra limitada de filas (5 por defecto) de una tabla específica para previsualizar su estructura y contenido de datos. Selecciona automáticamente campos escalares y de enumeración comunes.
  • Entrada: { tableName: string, limit?: number }
• aggregate_data
  • Descripción: Realiza una agregación simple (conteo, suma, promedio, mínimo, máximo) en una tabla específica, aplicando opcionalmente un filtro "donde" de Hasura. Use "list_tables" para buscar nombres de tabla. Requiere "campo" para agregaciones sin conteo.
  • Entrada: { tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }
• health_check
  • Descripción: Comprueba si el punto final de Hasura GraphQL configurado es accesible y responde a una consulta básica de GraphQL ( { __typename } ). Opcionalmente, puede comprobar la URL de un punto final de estado HTTP específico si se conoce.
  • Entrada: { healthEndpointUrl?: string } (URL de salud específica opcional)

Requisitos

• Node.js (se recomienda v18 o superior, verifique los motores .nvmrc o package.json engines si se especifican)
• pnpm (o npm / yarn , ajuste los comandos según corresponda)
• Acceso a un punto final GraphQL de Hasura en ejecución.
• (Opcional pero recomendado) Secreto de administrador de Hasura para acceso privilegiado o permisos de rol predeterminados configurados correctamente.

Configuración e instalación

1. Clonar el repositorio (si corresponde):
   # git clone <repository_url> # cd mcp-hasura-advanced
2. Dependencias de instalación:
   pnpm install
3. Construir el servidor:
   pnpm run build
   Esto compila el código TypeScript en el directorio dist .

Ejecución del servidor

Ejecute el script compilado desde su terminal, proporcionando la URL del punto final de Hasura y, opcionalmente, el secreto de administrador:

Ejemplo:

o

Si no se necesita ningún secreto de administrador (usando los permisos de rol predeterminados):

El servidor se iniciará, intentará una introspección inicial del esquema, se conectará al transporte STDIO y registrará los mensajes de estado en stderr . Escuchará las solicitudes JSON-RPC de MCP en stdin y enviará las respuestas a stdout .

Uso con clientes MCP (por ejemplo, Cursor, Claude Desktop)

Para conectar este servidor a un cliente MCP como Cursor:

1. Encontrar rutas absolutas:
   • Nodo ejecutable: ejecuta which node en tu terminal.
   • Script del servidor: Diríjase al directorio mcp-hasura-advanced y ejecute pwd . Añada /dist/index.js al resultado.
   • Directorio del proyecto: La salida de pwd .
2. Configurar el cliente: abra el archivo de configuración de su cliente (por ejemplo, settings.json para Cursor, claude_desktop_config.json para Claude Desktop).
3. Agregar entrada de servidor: agregue una entrada bajo la clave apropiada (por ejemplo, matriz cursor.customMcpServers para Cursor, objeto mcpServers para Claude Desktop).

Ejemplo settings.json del cursor.json:

Ejemplo de Claude Desktop claude_desktop_config.json :

4. Reemplazar marcadores de posición: actualice todos los marcadores de posición ( /path/to/... , https://YOUR... , YOUR_ADMIN_SECRET ) con sus valores reales.
5. Reiniciar/Recargar cliente: guarde la configuración y reinicie o recargue su aplicación cliente MCP.
6. Seleccionar servidor: elija “Mi servidor Hasura avanzado” (o el nombre que especificó) en la interfaz de usuario del cliente.
7. Interactuar: utilice indicaciones en lenguaje natural en el chat de su cliente para aprovechar las herramientas del servidor (por ejemplo, "Enumerar tablas usando el servidor Hasura", "Describir la tabla 'usuarios'", "Obtener una vista previa de los datos de la tabla 'pedidos'", "Ejecutar la consulta { products { name price } } usando el servidor Hasura").

Desarrollo

• Ejecutar en modo de desarrollo: use pnpm run dev <ENDPOINT> [SECRET] para ejecutar el servidor directamente con ts-node para una iteración más rápida (no se necesita ningún paso de compilación).
• Pruebas: pruebe herramientas individuales ejecutando el servidor manualmente ( pnpm start ... ) y canalizando solicitudes JSON-RPC a su stdin .