项目简介

该项目实现了一个基于 Model Context Protocol (MCP) 的服务器，旨在桥接 AI Agent (如 Cursor 或 Claude Desktop) 和 Hasura GraphQL API。它允许 Agent 通过标准化的 MCP 协议，以自然语言请求的方式，动态地发现、查询和操作 Hasura 管理的 GraphQL 数据。

主要功能点

GraphQL Schema 资源: 提供 Hasura GraphQL API 的完整 schema 定义，Agent 可通过读取此资源了解 API 结构。
GraphQL 查询工具: 支持执行只读 GraphQL 查询，用于安全地获取数据。
GraphQL 变更工具: 支持执行 GraphQL mutation，用于插入、更新或删除数据 (需谨慎使用)。
表和字段描述工具: 提供列出表、描述表结构、列出根字段、描述 GraphQL 类型等工具，帮助 Agent 理解数据和 API 结构。
数据预览和聚合工具: 支持预览表数据样本和执行简单的数据聚合操作。
健康检查工具: 检查 Hasura GraphQL 端点的可访问性。

安装步骤

安装 Node.js 和 pnpm: 确保你的系统已安装 Node.js (v18 或更高版本) 和 pnpm 包管理器。

克隆仓库: 如果需要，克隆 GitHub 仓库到本地：

git clone https://github.com/husamabusafa/hasura_mcp
cd hasura_mcp

安装依赖: 在项目根目录下运行以下命令安装项目依赖：
```
pnpm install
```
构建项目: 运行以下命令编译 TypeScript 代码：
```
pnpm run build
```

服务器配置

MCP 客户端 (如 Cursor, Claude Desktop) 需要配置服务器的启动命令和参数才能连接到 Hasura GraphQL MCP 服务器。以下是配置示例 (JSON 格式):

Cursor 'settings.json' 配置示例:

{
  "cursor.customMcpServers": [
    {
      "name": "Hasura GraphQL MCP Server",  // MCP 服务器名称，将显示在 Cursor UI 中
      "command": "/path/to/your/node",      // Node.js 可执行文件的绝对路径 (例如: 'which node' 的输出)
      "args": [
        "/absolute/path/to/hasura_mcp/dist/index.js", //  'index.js' 脚本的绝对路径 (项目根目录 + '/dist/index.js')
        "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // 你的 Hasura GraphQL 端点 URL，替换为实际地址
        "YOUR_ADMIN_SECRET"                                   // (可选) 你的 Hasura Admin Secret，如果不需要 admin secret 则移除此参数
      ],
      "cwd": "/absolute/path/to/hasura_mcp"   // (可选) 项目根目录的绝对路径，用于模块解析一致性
    }
  ]
}

Claude Desktop 'claude_desktop_config.json' 配置示例:

{
    "mcpServers": {
        "hasura-mcp": { // Claude Desktop 内部使用的服务器键名
            "command": "/path/to/your/node",      // Node.js 可执行文件的绝对路径
            "args": [
                "/absolute/path/to/hasura_mcp/dist/index.js", // 'index.js' 脚本的绝对路径
                "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // 你的 Hasura GraphQL 端点 URL
                "YOUR_ADMIN_SECRET"                                   // (可选) 你的 Hasura Admin Secret，如果不需要 admin secret 则移除此参数
            ]
        }
    }
}

重要:

请将 '/path/to/your/node', '/absolute/path/to/hasura_mcp', 'https://YOUR_HASURA_ENDPOINT.com/v1/graphql', 'YOUR_ADMIN_SECRET' 替换为你的实际值。
'/absolute/path/to/hasura_mcp' 可以通过在项目根目录运行 'pwd' 命令获取。
如果你的 Hasura 环境不需要 Admin Secret (例如使用了默认角色权限)，请移除 'YOUR_ADMIN_SECRET' 参数。

基本使用方法

启动服务器: 在项目根目录下，根据 README.md 的 "Running the Server" 部分，使用 'pnpm start' 或 'node dist/index.js' 命令启动服务器，并传入 Hasura GraphQL 端点 URL 和可选的 Admin Secret。
配置 MCP 客户端: 根据你的 MCP 客户端 (Cursor, Claude Desktop) 的配置方法，添加上面提供的服务器配置信息，并确保路径和参数正确。
连接服务器: 在 MCP 客户端中选择你配置的 "Hasura GraphQL MCP Server" (或你设置的名称)。
自然语言交互: 在 MCP 客户端中使用自然语言指令，例如：
- "List tables using the Hasura server" (列出表)
- "Describe the 'users' table using the Hasura server" (描述 'users' 表)
- "Preview data from the 'products' table using the Hasura server" (预览 'products' 表数据)
- "Run the query '{ products { name price } }' using the Hasura server" (运行 GraphQL 查询)

Agent 将通过 MCP 服务器与 Hasura GraphQL API 交互，并返回结果。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息