哈素拉_mcp

Name: 哈素拉_mcp
Author: husamabusafa

作者：husamabusafa16 星标更新：2025-04-05

安装使用来源：spider==github.com

项目介绍

【技术文档摘要】

高级 Hasura GraphQL MCP 服务器

版本: 1.1.0

此模型上下文协议（MCP）服务器提供了一个高级接口，使AI代理（如Cursor或Claude Desktop中的代理）能够与Hasura GraphQL端点进行交互。它允许代理发现API结构，执行只读查询和突变（需谨慎），预览数据，执行聚合操作，并检查服务健康状态。

该服务器通过允许大型语言模型根据自然语言请求动态利用您的Hasura API来增强其功能。

功能

此服务器公开了以下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'找到表名。非计数聚合需要'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管理员密钥以获得特权访问，或正确配置的默认角色权限。

安装和设置

克隆仓库（如适用）：

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

安装依赖项：
```
pnpm install
```
构建服务器：
```
pnpm run build
```
这会将TypeScript代码编译到dist目录中。

运行服务器

在终端中执行编译脚本，提供Hasura端点URL和可选的管理员密钥：

# 使用package.json中定义的pnpm start脚本
pnpm start <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

# 或直接使用Node
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 mysecretkey1

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

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

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

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

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

查找绝对路径：
- Node可执行文件：在终端中运行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对象）。

示例Cursor settings.json：

{
  // ...其他设置...
  "cursor.customMcpServers": [
    // ...其他服务器...
    {
      "name": "我的高级Hasura服务器", // 在Cursor UI中显示的名称
      "command": "/path/to/your/node", // <<< 来自'which node'的绝对路径
      "args": [
        "/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< 编译脚本的绝对路径
        "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // <<< 您的端点
        "YOUR_ADMIN_SECRET"                                   // <<< 您的密钥（如果没有密钥则移除）
      ],
      // 可选但推荐以保持模块解析一致性：
      "cwd": "/absolute/path/to/mcp-hasura-advanced" // <<< 项目的绝对路径
    }
  ]
}

示例Claude Desktop claude_desktop_config.json：

{
    "mcpServers": {
        // ...其他服务器...
        "hasura-advanced": { // Claude内部使用的键
            "command": "/path/to/your/node", // <<< 来自'which node'的绝对路径
            "args": [
                "/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< 编译脚本的绝对路径
                "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // <<< 您的端点
                "YOUR_ADMIN_SECRET"                                   // <<< 您的密钥（如果没有密钥则移除）
            ],
            // 可选：
            // "cwd": "/absolute/path/to/mcp-hasura-advanced"
        }
    }
}

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

开发

在开发模式下运行: 使用pnpm run dev <ENDPOINT> [SECRET]直接用ts-node运行服务器以加快迭代速度（无需构建步骤）。
测试: 通过手动运行服务器（pnpm start ...）并将其JSON-RPC请求管道化到其stdin来单独测试各个工具。