高级 Hasura GraphQL MCP 服务器

版本: 1.1.0

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

此服务器通过允许 LLM 根据自然语言请求动态利用您的 Hasura API 来增强 LLM 的能力。

功能

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

资源:

• Hasura GraphQL Schema (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 变更以插入、更新或删除数据。 谨慎使用，确保操作是预期且安全的。 依赖于为提供的 Admin Secret 或默认角色配置的 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 Admin Secret，或正确配置的默认角色权限。

设置和安装

1. 克隆存储库（如果适用）：

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

2. 安装依赖项：

   pnpm install
   

3. 构建服务器：

   pnpm run build
   

   这会将 TypeScript 代码编译到 dist 目录中。

运行服务器

从您的终端执行编译后的脚本，提供 Hasura 端点 URL，并可选择提供 admin secret：

# 使用 pnpm start 脚本（在 package.json 中定义）
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 mysecretkey123

如果不需要 admin secret（使用默认角色权限）：

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

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

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

要将此服务器连接到像 Cursor 这样的 MCP 客户端：

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

Cursor settings.json 示例：

{
  // ... 其他设置 ...
  "cursor.customMcpServers": [
    // ... 其他服务器 ...
    {
      "name": "My Advanced Hasura Server", // 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"                                   // <<< 您的 secret (如果不需要 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"                                   // <<< 您的 secret (如果不需要 secret，请删除)
            ],
            // 可选：
            // "cwd": "/absolute/path/to/mcp-hasura-advanced"
        }
    }
}

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

开发

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