Hasura GraphQL

🚀 高級功能

本項目提供了一系列高級功能，可幫助你快速搭建並運行服務器，同時支持與 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，可按以下步驟操作：

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"                                   // <<< 您的秘密（如果不需要秘密請刪除）
      ],
      // 可選但推薦以保持模塊解析一致性：
      "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 分支上進行修改。提交前，請確保通過所有測試。

📄 許可證

[此處插入許可證信息]