高级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管理员密码用于特权访问，或正确配置默认角色权限。
设置和安装
- 克隆存储库（如果适用）：
# git clone
# cd mcp-hasura-advanced- 安装依赖关系：
pnpm install- 构建服务器：
pnpm run build这将TypeScript代码编译为 dist 目录。
运行服务器
从终端执行编译后的脚本，提供Hasura端点URL和可选的管理员密码：
# Using pnpm start script (defined in package.json)
pnpm start [ADMIN_SECRET]
# Or using Node directly
node dist/index.js [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客户端，请执行以下操作：
- 查找绝对路径：
- 节点可执行文件：运行 which node 在你的终端。 - 服务器脚本：导航到 mcp-hasura-advanced 目录并运行 pwd.附录 /dist/index.js 结果。 - 项目目录：输出 pwd.
- 配置客户端： 打开客户端的配置文件（例如。，
settings.json对于光标，claude_desktop_config.json克劳德桌面）。 - 添加服务器条目： 在适当的键下添加条目（例如。，
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", // [SECRET]` 直接运行服务器 `ts-node` 为了更快的迭代（不需要构建步骤）。
- **测试：** 通过手动运行服务器来测试单个工具(`pnpm start ...`)并将JSON-RPC请求传输到其 `stdin`.