Hasura GraphQL

高級Hasura GraphQL MCP服務器，為AI代理提供動態交互接口

開發者工具數據庫 #GraphQL接口 #數據交互 #AI集成 #API管理本地 .TypeScript

評分 : 2.5分

下載量 : 17

更新時間 : 2025-04-28

什麼是高級Hasura GraphQL MCP服務器？

這是一個強大的工具，允許AI代理（如Cursor或Claude Desktop）動態地與您的Hasura GraphQL API交互。它可以幫助您發現API結構、執行查詢和突變操作、預覽數據、執行聚合以及檢查服務健康狀態。

如何使用高級Hasura GraphQL MCP服務器？

首先安裝並運行服務器，然後將其連接到您的MCP客戶端（例如Cursor或Claude Desktop）。通過自然語言提示詞，您可以輕鬆地探索和利用您的Hasura GraphQL API。

適用場景

適用於需要快速訪問和操作GraphQL數據的企業應用開發人員、數據科學家及業務分析師。

主要功能

GraphQL模式提供完整的GraphQL模式定義，包括類型、字段、參數和指令等。

執行只讀查詢安全地執行只讀GraphQL查詢，獲取所需的數據。

執行突變謹慎地執行GraphQL突變操作，用於插入、更新或刪除數據。

列出表列出可用的數據表，幫助您快速瞭解數據源。

描述表結構查看特定表的詳細結構，包括字段及其類型和描述。

聚合數據對指定表進行簡單的聚合操作，如計數、求和、平均值等。

健康檢查驗證Hasura GraphQL端點是否正常工作。

優勢與侷限性

優勢

支持多種功能，包括查詢、突變和聚合。

易於集成到現有的MCP客戶端中。

無需編寫複雜的GraphQL查詢即可快速獲取數據。

侷限性

需要正確的權限配置來確保安全執行突變操作。

可能不支持某些自定義的GraphQL擴展功能。

如何使用

克隆倉庫

下載並克隆高級Hasura GraphQL MCP服務器的代碼倉庫。

安裝依賴

安裝所需的Node.js依賴項。

構建服務器

編譯TypeScript代碼以生成可執行文件。

啟動服務器

運行服務器並連接到您的Hasura GraphQL端點。

使用案例

列出所有表展示系統中的所有可用表。

預覽訂單表數據顯示訂單表的前幾行數據。

計算產品價格總和計算產品表的價格總和。

常見問題

如何安裝高級Hasura GraphQL MCP服務器？

是否可以執行突變操作？

如何檢查服務器健康狀態？

🚀 高級功能

本項目提供了一系列高級功能，可幫助你快速搭建並運行服務器，同時支持與 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       # 依賴和腳本配置