Advanced Hasura GraphQL MCP Server

高级 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 } （可选模式名称，如果可能则尝试从字段描述中推断，概念上默认为“公共”）
• 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”查找表名。非计数聚合需要“field”。
  • 输入： { 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 和可选的管理员机密：

例子：

或者

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

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

与 MCP 客户端一起使用（例如 Cursor、Claude Desktop）

要将此服务器连接到 MCP 客户端（如 Cursor）：

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

示例游标settings.json ：

示例 Claude Desktop claude_desktop_config.json ：

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

发展

• **以开发模式运行：**使用pnpm run dev <ENDPOINT> [SECRET]直接通过ts-node运行服务器以实现更快的迭代（无需构建步骤）。
• **测试：**通过手动运行服务器（ pnpm start ... ）并将 JSON-RPC 请求传送到其stdin来测试各个工具。