金大哥 - Hasura GraphQL MCP 详情

article

README

🚀 高级功能

本项目提供一系列高级功能，可帮助你轻松搭建和配置基于 Hasura 的服务器，实现与 MCP 客户端的连接。

🚀 快速开始

📦 安装指南

运行以下命令安装项目所需的依赖：

pnpm install

🏗️ 构建服务

构建 TypeScript 代码到 dist 目录：

pnpm run build

🚀 运行服务器

使用以下命令启动服务器，指定 Hasura GraphQL 终点和可选的管理员密钥：

# 使用 pnpm 脚本运行
pnpm start <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

# 或者直接使用 Node.js
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

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

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

服务器启动后，将尝试初始模式反编译，连接到 STDIO 传输，并将状态消息记录到 stderr。它监听 MCP JSON-RPC 请求在 stdin 并将响应发送到 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": "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"                                   // <<< 您的秘密（如果不需要秘密请删除）
      ],
      // 可选但推荐以保持模块解析一致性：
      "cwd": "/absolute/path/to/mcp-hasura-advanced" // <<< 绝对路径到项目根目录
    }
  ]
}

示例 Claude Desktop claude_desktop_config.json：

{
    "mcpServers": {
        // ... 其他服务器 ...
        "hasura-advanced": { // 关键字由 Claude 内部使用
            "command": "/path/to/your/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"
        }
    }
}

✨ 主要特性

⚙️ 设置环境变量

您可以在 package.json 中添加自定义环境变量：

{
  "env": {
    "NODE_ENV": "production",
    "MY_SECRET": "my-secret-value"
  }
}

🌐 使用不同端口

要更改默认端口（3000），可以在运行时指定：

pnpm start --port=3001 <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

✅ 验证配置

在启动服务器之前，验证所有配置是否正确：

pnpm run lint

❓ 解决问题

如果遇到问题，请检查以下内容：

确保 Hasura 终点是有效的 URL。
检查管理员密钥是否正确配置。
查看控制台输出以获取错误信息。

📚 详细文档

📋 命令行选项

pnpm start [options] <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]
Options:
  --port=VALUE          自定义服务器端口 (默认: 3000)
  --verbose             启用详细日志记录

📁 示例项目结构

mcp-hasura-advanced/
├── dist/              # 编译后的输出目录
├── src/
│   ├── index.ts      # 主应用文件
│   └── schema.ts     # GraphQL 模式定义
└── package.json       # 依赖和脚本配置

🤝 贡献指南

要为项目做出贡献，请 fork 仓库并在 dev 分支上进行修改。提交前，请确保通过所有测试。

📄 许可证

[此处插入许可证信息]

Hasura GraphQL