Hasura GraphQL

Servidor MCP Avanzado de Hasura GraphQL

Versión: 1.1.0

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

Este servidor mejora las capacidades de los LLM al permitirles aprovechar tu API de Hasura de forma dinámica según solicitudes en lenguaje natural.

Características

Este servidor expone las siguientes capacidades MCP:

Recursos:

• Esquema de 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 contra el endpoint de Hasura. Úsala para obtener datos cuando no haya una herramienta específica disponible. Asegúrate de que la consulta no modifique datos. Ejemplo: query { users { id name } }
  • Entrada: { query: string, variables?: object }
  • Nota: Realiza una verificación básica para evitar la ejecución de cadenas que comiencen con mutation. Se basa principalmente en que la consulta en sí sea de solo lectura.

• run_graphql_mutation

  • Descripción: Ejecuta una mutación GraphQL para insertar, actualizar o eliminar datos. Úsala con precaución, asegúrate de que la operación sea intencionada y segura. 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úrate de que los permisos de Hasura estén configurados adecuadamente.

• list_tables

  • Descripción: Lista las tablas de datos disponibles (o colecciones) 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 fuentes de datos disponibles.
  • Entrada: { schemaName?: string } (Nombre de esquema opcional, intenta inferir de las descripciones de campo si es posible, por defecto 'public' conceptualmente)

• describe_table

  • Descripción: Muestra la estructura de una tabla específica, incluidos todos sus campos (columnas) con sus tipos GraphQL y descripciones.
  • Entrada: { tableName: string, schemaName?: string }

• list_root_fields

  • Descripción: Lista los campos de consulta, mutación o suscripción de nivel superior disponibles en el esquema GraphQL. Útil para comprender los puntos de entrada principales para las operaciones.
  • Entrada: { fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' } (Filtro opcional)

• describe_graphql_type

  • Descripción: Proporciona detalles sobre un tipo GraphQL específico (Objeto, Entrada, Escalar, Enumeración, Interfaz, Unión) mediante introspección de esquema. Esencial para comprender cómo estructurar consultas o mutaciones que involucren tipos específicos.
  • Entrada: { typeName: string } (Nombre de tipo sensible a mayúsculas)

• preview_table_data

  • Descripción: Obtiene una muestra limitada de filas (5 por defecto) de una tabla especificada 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 especificada, aplicando opcionalmente un filtro 'where' de Hasura. Usa 'list_tables' para encontrar nombres de tablas. Requiere 'field' para agregaciones que no sean de conteo.
  • Entrada: { tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }

• health_check

  • Descripción: Verifica si el endpoint de Hasura GraphQL configurado es accesible y responde a una consulta GraphQL básica ({ __typename }). Opcionalmente puede verificar una URL específica de endpoint de salud HTTP si se conoce.
  • Entrada: { healthEndpointUrl?: string } (URL de salud específica opcional)

Requisitos

• Node.js (v18 o superior recomendado, consulta .nvmrc o package.json engines si se especifica)
• pnpm (o npm/yarn, ajusta los comandos en consecuencia)
• Acceso a un endpoint de Hasura GraphQL en ejecución.
• (Opcional pero recomendado) Secreto de Administrador de Hasura para acceso privilegiado, o permisos de rol predeterminados configurados adecuadamente.

Configuración e Instalación

1. Clonar el Repositorio (si aplica):

   # git clone <repository_url>
   # cd mcp-hasura-advanced
   

2. Instalar Dependencias:

   pnpm install
   

3. Compilar el Servidor:

   pnpm run build
   

   Esto compila el código TypeScript en el directorio dist.

Ejecutar el Servidor

Ejecuta el script compilado desde tu terminal, proporcionando la URL del endpoint de Hasura y opcionalmente el secreto de administrador:

# Using pnpm start script (defined in package.json)
pnpm start <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

# Or using Node directly
node dist/index.js <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

Ejemplo:

pnpm start https://my-hasura.cloud/v1/graphql mysecretkey123

o

node dist/index.js https://my-hasura.cloud/v1/graphql mysecretkey123

Si no se necesita secreto de administrador (usando permisos de rol predeterminados):

pnpm start https://my-hasura.cloud/v1/graphql

El servidor se iniciará, intentará una introspección inicial del esquema, se conectará al transporte STDIO y registrará mensajes de estado en stderr. Escucha solicitudes JSON-RPC de MCP en stdin y envía 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:
   • Ejecutable de Node: Ejecuta which node en tu terminal.
   • Script del servidor: Navega al directorio mcp-hasura-advanced y ejecuta pwd. Agrega /dist/index.js al resultado.
   • Directorio del proyecto: La salida de pwd.
2. Configurar el Cliente: Abre el archivo de configuración de tu cliente (por ejemplo, settings.json para Cursor, claude_desktop_config.json para Claude Desktop).
3. Agregar Entrada del Servidor: Agrega una entrada bajo la clave apropiada (por ejemplo, el arreglo cursor.customMcpServers para Cursor, el objeto mcpServers para Claude Desktop).

Ejemplo de settings.json de Cursor:

{
  // ... other settings ...
  "cursor.customMcpServers": [
    // ... other servers ...
    {
      "name": "My Advanced Hasura Server", // Name shown in Cursor UI
      "command": "/path/to/your/node", // <<< Absolute path from 'which node'
      "args": [
        "/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< Absolute path to compiled script
        "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // <<< Your endpoint
        "YOUR_ADMIN_SECRET"                                   // <<< Your secret (REMOVE if no secret)
      ],
      // Optional but recommended for module resolution consistency:
      "cwd": "/absolute/path/to/mcp-hasura-advanced" // <<< Absolute path to project root
    }
  ]
}

Ejemplo de claude_desktop_config.json de Claude Desktop:

{
    "mcpServers": {
        // ... other servers ...
        "hasura-advanced": { // Key used internally by Claude
            "command": "/path/to/your/node", // <<< Absolute path from 'which node'
            "args": [
                "/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< Absolute path to compiled script
                "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // <<< Your endpoint
                "YOUR_ADMIN_SECRET"                                   // <<< Your secret (REMOVE if no secret)
            ],
            // Optional:
            // "cwd": "/absolute/path/to/mcp-hasura-advanced"
        }
    }
}

4. Reemplazar Marcadores de Posición: Actualiza todos los marcadores de posición (/path/to/..., https://YOUR..., YOUR_ADMIN_SECRET) con tus valores reales.
5. Reiniciar/Recargar el Cliente: Guarda la configuración y reinicia o recarga tu aplicación cliente MCP.
6. Seleccionar Servidor: Elige "My Advanced Hasura Server" (o el nombre que hayas especificado) en la interfaz del cliente.
7. Interactuar: Usa indicaciones en lenguaje natural en el chat de tu cliente para aprovechar las herramientas del servidor (por ejemplo, "Listar tablas usando el servidor de Hasura", "Describir la tabla 'users'", "Previsualizar datos de la tabla 'orders'", "Ejecutar la consulta { products { name price } } usando el servidor de Hasura").

Desarrollo

• Ejecutar en Modo de Desarrollo: Usa pnpm run dev <ENDPOINT> [SECRET] para ejecutar el servidor directamente con ts-node para iteración más rápida (sin necesidad de compilación).
• Pruebas: Prueba herramientas individuales ejecutando el servidor manualmente (pnpm start ...) y enviando solicitudes JSON-RPC a su stdin.