AI导哈

GraphQL接口服务

一个高级的Hasura GraphQL MCP服务器，为AI代理提供动态交互接口，支持查询、突变、数据预览和聚合等功能。

  • by husamabusafa
  • TypeScript
  • 本地部署
  • 24 星标
  • 更新于
在 GitHub 查看 husamabusafa/hasura_mcp

使用说明

高级Hasura GraphQL MCP服务器

版本： 1.1.0

此模型上下文协议（MCP）服务器为AI代理（如Cursor或Claude Desktop中的代理）提供了一个高级接口，用于与Hasura GraphQL端点进行交互。它使代理能够发现API结构、执行只读查询和突变（注意）、预览数据、执行聚合和检查服务运行状况。

该服务器允许他们根据自然语言请求动态利用您的Hasura API，从而增强LLM功能。

特性

此服务器公开了以下MCP功能：

资源：

  • Hasura GraphQL架构(hasura:/schema)
    • 提供通过标准自检获得的完整GraphQL模式定义。
    • MIME类型： application/json
    • 代理可以阅读此资源以了解API的完整结构，包括类型、字段、参数、指令等。

工具：

  • run_graphql_query

    • 说明： 对Hasura端点执行只读GraphQL查询。当特定工具不可用时，使用此工具获取数据。确保查询不会修改数据。 例子： query { users { id name } }
    • 输入： { query: string, variables?: object }
    • 注： 执行基本检查以防止执行以开头的字符串 mutation。主要依赖于查询本身是只读的。

  • run_graphql_mutation

    • 说明： 执行GraphQL变异以插入、更新或删除数据。 谨慎使用，确保操作是有意和安全的。依赖于为提供的管理员密码或默认角色配置的Hasura权限。 例子： mutation { insert_users_one(object: {name: "Test"}) { id } }
    • 输入： { mutation: string, variables?: object }
    • 安全： 允许Hasura角色允许的任何突变。确保配置了适当的Hasura权限。

  • list_tables

    • 说明： 列出由Hasura管理的可用数据表（或集合），按带有描述的模式组织，基于内省启发式（查找具有“id”字段的对象类型，不包括内部/聚合类型）。有助于发现可用的数据源。
    • 输入： { schemaName?: string } （可选模式名称，如果可能的话，尝试从字段描述中推断，在概念上默认为“public”）

  • describe_table

    • 说明： 显示特定表的结构，包括其所有列（字段）及其GraphQL类型和描述。
    • 输入： { tableName: string, schemaName?: string }

  • list_root_fields

    • 说明： 列出GraphQL架构中可用的顶级查询、变异或订阅字段。有助于理解操作的主要切入点。
    • 输入： { fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' } （可选过滤器）

  • describe_graphql_type

    • 说明： 使用模式自检提供有关特定GraphQL类型（对象、输入、标量、枚举、接口、联合）的详细信息。对于理解如何构建涉及特定类型的查询或突变至关重要。
    • 输入： { typeName: string } （区分大小写的类型名称）

  • preview_table_data

    • 说明： 从指定表中获取有限的行样本（默认值5），以预览其数据结构和内容。自动选择常用标量和枚举字段。
    • 输入： { tableName: string, limit?: number }

  • aggregate_data

    • 说明： 对指定表执行简单聚合（计数、求和、平均值、最小值、最大值），可选地应用Hasura“where”筛选器。使用“list_tables”查找表名。非计数聚合需要“字段”。
    • 输入： { tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }

  • health_check

    • 说明： 检查配置的Hasura GraphQL端点是否可访问并响应基本GraphQL查询({ __typename }).如果已知，可以选择检查特定的HTTP健康端点URL。
    • 输入： { healthEndpointUrl?: string } （可选的特定健康URL）

需求

  • Node.js（建议使用v18或更高版本，请检查 .nvmrc 或 package.json engines 如果指定）
  • pnpm （或 npm/yarn，相应地调整命令）
  • 访问正在运行的Hasura GraphQL端点。
  • （可选但推荐）Hasura管理员密码用于特权访问，或正确配置默认角色权限。

设置和安装

  1. 克隆存储库（如果适用）：
    # git clone <repository_url>
# cd mcp-hasura-advanced
  2. 安装依赖关系：
    pnpm install
  3. 构建服务器：
    pnpm run build
    这将TypeScript代码编译为 dist 目录。

运行服务器

从终端执行编译后的脚本，提供Hasura端点URL和可选的管理员密码：

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

例子：

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

或

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

如果不需要管理员密码（使用默认角色权限）：

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

服务器将启动，尝试初始模式自检，连接到STDIO传输，并将状态消息记录到 stderr。它在上监听MCP JSON-RPC请求 stdin 并向发送响应 stdout.

使用MCP客户端（例如，Cursor、Claude Desktop）

要将此服务器连接到像Cursor这样的MCP客户端，请执行以下操作：

  1. 查找绝对路径：
    • 节点可执行文件：运行 which node 在你的终端。
    • 服务器脚本：导航到 mcp-hasura-advanced 目录并运行 pwd.附录 /dist/index.js 结果。
    • 项目目录：输出 pwd.
  2. 配置客户端： 打开客户端的配置文件（例如。， settings.json 对于光标， claude_desktop_config.json 克劳德桌面）。
  3. 添加服务器条目： 在适当的键下添加条目（例如。， cursor.customMcpServers 游标数组， mcpServers 克劳德桌面的对象）。

光标示例 settings.json:

{
  // ... 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
    }
  ]
}

克劳德桌面示例 claude_desktop_config.json:

{
    "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"
        }
    }
}
  1. 更换占位符： 更新所有占位符(/path/to/..., https://YOUR..., YOUR_ADMIN_SECRET)与你的实际价值观。
  2. 重新启动/重新加载客户端： 保存配置并重新启动或重新加载MCP客户端应用程序。
  3. 选择服务器： 在客户端的UI中选择“我的高级Hasura服务器”（或您指定的名称）。
  4. 互动： 在客户的聊天中使用自然语言提示来利用服务器的工具（例如，“列出使用Hasura服务器的表”，“描述‘用户’表”，”预览‘订单’表中的数据”，“运行查询 { products { name price } } 使用Hasura服务器”）。

发展

  • 在开发模式下运行： 使用 pnpm run dev <ENDPOINT> [SECRET] 直接运行服务器 ts-node 为了更快的迭代（不需要构建步骤）。
  • 测试： 通过手动运行服务器来测试单个工具(pnpm start ...)并将JSON-RPC请求传输到其 stdin.

相关 MCP