Hasura GraphQL

Servidor MCP Avançado Hasura GraphQL

Versão: 1.1.0

Este servidor Model Context Protocol (MCP) fornece uma interface avançada para agentes de IA (como aqueles no Cursor ou Claude Desktop) interagirem com um endpoint GraphQL do Hasura. Ele permite que agentes descubram a estrutura da API, executem tanto consultas somente leitura quanto mutações (com cautela), visualizem dados, realizem agregações e verifiquem a saúde do serviço.

Este servidor aprimora as capacidades de LLMs, permitindo que eles aproveitem sua API Hasura dinamicamente com base em solicitações em linguagem natural.

Recursos

Este servidor expõe os seguintes recursos MCP:

Recursos:

• Esquema GraphQL do Hasura (hasura:/schema)
  • Fornece a definição completa do esquema GraphQL obtida por meio de introspecção padrão.
  • Tipo MIME: application/json
  • Agentes podem ler este recurso para entender a estrutura completa da API, incluindo tipos, campos, argumentos, diretivas, etc.

Ferramentas:

• run_graphql_query

  • Descrição: Executa uma consulta GraphQL somente leitura no endpoint Hasura. Use isto para buscar dados quando uma ferramenta específica não estiver disponível. Garanta que a consulta não modifique dados. Exemplo: query { users { id name } }
  • Entrada: { query: string, variables?: object }
  • Nota: Realiza uma verificação básica para impedir a execução de strings que começam com mutation. Depende principalmente da própria consulta ser somente leitura.

• run_graphql_mutation

  • Descrição: Executa uma mutação GraphQL para inserir, atualizar ou excluir dados. Use com cautela, garanta que a operação seja intencional e segura. Depende das permissões do Hasura configuradas para o Admin Secret fornecido ou papel padrão. Exemplo: mutation { insert_users_one(object: {name: "Test"}) { id } }
  • Entrada: { mutation: string, variables?: object }
  • Segurança: Permite qualquer mutação permitida pelo papel do Hasura. Garanta que permissões apropriadas do Hasura estejam configuradas.

• list_tables

  • Descrição: Lista as tabelas de dados disponíveis (ou coleções) gerenciadas pelo Hasura, organizadas por esquema com descrições, com base em heurísticas de introspecção (procura por tipos de objeto com um campo 'id', excluindo tipos internos/agregados). Útil para descobrir fontes de dados disponíveis.
  • Entrada: { schemaName?: string } (Nome de esquema opcional, tenta inferir das descrições de campo se possível, padroniza para 'public' conceitualmente)

• describe_table

  • Descrição: Mostra a estrutura de uma tabela específica, incluindo todas as suas colunas (campos) com seus tipos GraphQL e descrições.
  • Entrada: { tableName: string, schemaName?: string }

• list_root_fields

  • Descrição: Lista os campos de consulta, mutação ou assinatura de nível superior disponíveis no esquema GraphQL. Útil para entender os pontos de entrada primários para operações.
  • Entrada: { fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' } (Filtro opcional)

• describe_graphql_type

  • Descrição: Fornece detalhes sobre um tipo GraphQL específico (Objeto, Entrada, Escalar, Enum, Interface, União) usando introspecção de esquema. Essencial para entender como estruturar consultas ou mutações envolvendo tipos específicos.
  • Entrada: { typeName: string } (Nome do tipo sensível a maiúsculas/minúsculas)

• preview_table_data

  • Descrição: Busca uma amostra limitada de linhas (padrão 5) de uma tabela especificada para visualizar sua estrutura e conteúdo de dados. Seleciona campos escalares e enum comuns automaticamente.
  • Entrada: { tableName: string, limit?: number }

• aggregate_data

  • Descrição: Realiza uma agregação simples (contagem, soma, média, mínimo, máximo) em uma tabela especificada, opcionalmente aplicando um filtro 'where' do Hasura. Use 'list_tables' para encontrar nomes de tabelas. Requer 'field' para agregações que não sejam de contagem.
  • Entrada: { tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }

• health_check

  • Descrição: Verifica se o endpoint GraphQL do Hasura configurado está acessível e respondendo a uma consulta GraphQL básica ({ __typename }). Pode opcionalmente verificar uma URL específica de endpoint de saúde HTTP se conhecida.
  • Entrada: { healthEndpointUrl?: string } (URL de saúde específica opcional)

Requisitos

• Node.js (v18 ou superior recomendado, verifique .nvmrc ou package.json engines se especificado)
• pnpm (ou npm/yarn, ajuste os comandos de acordo)
• Acesso a um endpoint GraphQL do Hasura em execução.
• (Opcional, mas recomendado) Admin Secret do Hasura para acesso privilegiado, ou permissões de papel padrão configuradas adequadamente.

Configuração e Instalação

1. Clonar o Repositório (se aplicável):

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

2. Instalar Dependências:

   pnpm install
   

3. Compilar o Servidor:

   pnpm run build
   

   Isso compila o código TypeScript no diretório dist.

Executando o Servidor

Execute o script compilado a partir do seu terminal, fornecendo a URL do endpoint Hasura e opcionalmente o admin secret:

# 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]

Exemplo:

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

ou

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

Se nenhum admin secret for necessário (usando permissões de papel padrão):

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

O servidor iniciará, tentará uma introspecção inicial do esquema, conectará ao transporte STDIO e registrará mensagens de status em stderr. Ele escuta solicitações JSON-RPC MCP em stdin e envia respostas para stdout.

Uso com Clientes MCP (ex.: Cursor, Claude Desktop)

Para conectar este servidor a um cliente MCP como o Cursor:

1. Encontrar Caminhos Absolutos:
   • Executável Node: Execute which node no seu terminal.
   • Script do servidor: Navegue até o diretório mcp-hasura-advanced e execute pwd. Anexe /dist/index.js ao resultado.
   • Diretório do projeto: A saída de pwd.
2. Configurar o Cliente: Abra o arquivo de configuração do seu cliente (ex.: settings.json para Cursor, claude_desktop_config.json para Claude Desktop).
3. Adicionar Entrada do Servidor: Adicione uma entrada sob a chave apropriada (ex.: array cursor.customMcpServers para Cursor, objeto mcpServers para Claude Desktop).

Exemplo de settings.json do 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
    }
  ]
}

Exemplo de claude_desktop_config.json do 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. Substituir Espaços Reservados: Atualize todos os espaços reservados (/path/to/..., https://YOUR..., YOUR_ADMIN_SECRET) com seus valores reais.
5. Reiniciar/Recarregar Cliente: Salve a configuração e reinicie ou recarregue seu aplicativo cliente MCP.
6. Selecionar Servidor: Escolha "My Advanced Hasura Server" (ou o nome que você especificou) na interface do cliente.
7. Interagir: Use prompts em linguagem natural no chat do seu cliente para aproveitar as ferramentas do servidor (ex.: "Listar tabelas usando o servidor Hasura", "Descrever a tabela 'users'", "Visualizar dados da tabela 'orders'", "Executar a consulta { products { name price } } usando o servidor Hasura").

Desenvolvimento

• Executar em Modo Dev: Use pnpm run dev <ENDPOINT> [SECRET] para executar o servidor diretamente com ts-node para iteração mais rápida (sem necessidade de etapa de compilação).
• Testes: Teste ferramentas individuais executando o servidor manualmente (pnpm start ...) e enviando solicitações JSON-RPC para seu stdin.