高级 Hasura GraphQL MCP 服务器
版本： 1.1.0
该模型上下文协议 (MCP) 服务器为 AI 代理（例如 Cursor 或 Claude Desktop 中的代理）提供了一个高级接口，用于与 Hasura GraphQL 端点交互。它使代理能够发现 API 结构、执行只读查询和变更（需谨慎操作）、预览数据、执行聚合以及检查服务运行状况。
该服务器允许他们根据自然语言请求动态利用您的 Hasura API，从而增强了 LLM 功能。
特征
该服务器公开以下 MCP 功能：
资源：
Hasura GraphQL 架构 (
提供通过标准自省获得的完整 GraphQL 模式定义。
MIME 类型：
application/json代理可以阅读此资源来了解 API 的完整结构，包括类型、字段、参数、指令等。
工具：
run_graphql_query**描述：**针对 Hasura 端点执行只读 GraphQL 查询。当特定工具不可用时，使用此方法获取数据。确保查询不会修改数据。示例：
输入：
{ query: string, variables?: object }**注意：**执行基本检查以防止执行以
mutation开头的字符串。主要依赖于查询本身是否为只读。
run_graphql_mutation**描述：**执行 GraphQL 突变以插入、更新或删除数据。请谨慎使用，确保操作符合预期且安全。依赖于为提供的管理员密钥或默认角色配置的 Hasura 权限。示例：
输入：
{ 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）
Related MCP server: CodeAlive MCP
要求
Node.js（建议使用 v18 或更高版本，如果指定，请检查
.nvmrc或package.json engines）pnpm(或npm/yarn，相应调整命令)访问正在运行的 Hasura GraphQL 端点。
（可选但推荐）Hasura 管理员机密用于特权访问，或正确配置的默认角色权限。
设置和安装
克隆存储库（如果适用）：
# git clone <repository_url> # cd mcp-hasura-advanced安装依赖项：
pnpm install构建服务器：
pnpm run build这会将 TypeScript 代码编译到
dist目录中。
运行服务器
从您的终端执行已编译的脚本，提供 Hasura 端点 URL 和可选的管理员机密：
例子：
或者
如果不需要管理员机密（使用默认角色权限）：
服务器将启动，尝试进行初始模式自检，连接到 STDIO 传输，并将状态消息记录到stderr 。它会在stdin上监听 MCP JSON-RPC 请求，并将响应发送到stdout 。
与 MCP 客户端一起使用（例如 Cursor、Claude Desktop）
要将此服务器连接到 MCP 客户端（如 Cursor）：
查找绝对路径：
节点可执行文件：在终端中运行
which node。服务器脚本：导航到
mcp-hasura-advanced目录并运行pwd。将/dist/index.js附加到结果中。项目目录：
pwd的输出。
**配置客户端：**打开客户端的配置文件（例如，Cursor 的
settings.json、Claude Desktop 的claude_desktop_config.json）。**添加服务器条目：**在适当的键下添加一个条目（例如，Cursor 的
cursor.customMcpServers数组，Claude Desktop 的mcpServers对象）。
示例游标
示例 Claude Desktop
**替换占位符：**用您的实际值更新所有占位符（
/path/to/...、https://YOUR...、YOUR_ADMIN_SECRET）。**重启/重新加载客户端：**保存配置并重启或重新加载您的 MCP 客户端应用程序。
**选择服务器：**在客户端的 UI 中选择“我的高级 Hasura 服务器”（或您指定的名称）。
**互动：**在客户的聊天中使用自然语言提示来利用服务器的工具（例如，“使用 Hasura 服务器列出表格”、“描述‘用户’表格”、“预览‘订单’表格中的数据”、“使用 Hasura 服务器运行查询
{ products { name price } }”）。
发展
**以开发模式运行：**使用
pnpm run dev <ENDPOINT> [SECRET]直接通过ts-node运行服务器以实现更快的迭代（无需构建步骤）。**测试：**通过手动运行服务器（
pnpm start ...）并将 JSON-RPC 请求传送到其stdin来测试各个工具。