Keeperhub MCP

🚀 KeeperHub MCP 服務器

KeeperHub 的模型上下文協議（MCP）服務器，使 AI 代理能夠創建、管理和執行區塊鏈自動化工作流。

🚀 快速開始

KeeperHub MCP 服務器可助力 AI 代理實現區塊鏈自動化工作流的創建、管理與執行。你可以依據自身需求，選擇合適的安裝方式。

✨ 主要特性

• 工作流的完整 CRUD 操作：支持創建、讀取、更新和刪除工作流。
• AI 驅動的工作流生成：通過自然語言提示生成工作流。
• 異步執行：支持狀態輪詢和日誌檢索。
• MCP 資源：用於公開工作流定義。
• API 密鑰認證：保障安全訪問。

📦 安裝指南

使用 Docker（推薦）

# 構建 Docker 鏡像
docker build -t keeperhub-mcp .

# 運行服務器
docker run -i --rm \
  -e KEEPERHUB_API_KEY=your_api_key_here \
  keeperhub-mcp

使用 Node.js

# 安裝依賴
pnpm install

# 構建項目
pnpm build

# 運行服務器
KEEPERHUB_API_KEY=your_api_key_here pnpm start

開發模式

# 使用 tsx 進行熱重載
KEEPERHUB_API_KEY=your_api_key_here pnpm dev

📚 詳細文檔

配置

服務器需要以下環境變量：

傳輸模式

服務器支持兩種傳輸模式：

1. 標準輸入輸出模式（默認）：適用於使用標準輸入輸出通信的本地 AI 客戶端。
2. HTTP/SSE 模式：適用於通過 HTTP 使用服務器發送事件的遠程 AI 代理。

若要啟用 HTTP 模式，請設置 PORT 環境變量。在 HTTP 模式下運行時，還必須設置 MCP_API_KEY 進行身份驗證。

MCP 客戶端配置

標準輸入輸出模式（本地）

將以下內容添加到你的 MCP 客戶端配置中（例如，Claude Code 配置）：

{
  "mcpServers": {
    "keeperhub": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "KEEPERHUB_API_KEY",
        "keeperhub-mcp"
      ]
    }
  }
}

或者用於本地開發：

{
  "mcpServers": {
    "keeperhub": {
      "command": "node",
      "args": [
        "/absolute/path/to/keeperhub-mcp/dist/index.js"
      ],
      "env": {
        "KEEPERHUB_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP/SSE 模式（遠程）

對於遠程 AI 代理，在 HTTP 模式下運行服務器：

# 使用 Node.js
PORT=3000 \
MCP_API_KEY=your_secure_mcp_key \
KEEPERHUB_API_KEY=your_keeperhub_key \
pnpm start

或者使用 Docker：

docker run -p 3000:3000 \
  -e PORT=3000 \
  -e MCP_API_KEY=your_secure_mcp_key \
  -e KEEPERHUB_API_KEY=your_keeperhub_key \
  keeperhub-mcp

服務器將公開以下端點：

• GET /health - 健康檢查端點
• GET /sse - MCP 協議的服務器發送事件端點
• POST /message - 客戶端請求的消息端點

身份驗證

所有 HTTP 請求必須包含帶有 Bearer 令牌的 Authorization 標頭：

Authorization: Bearer your_secure_mcp_key

示例：測試健康檢查

curl -H "Authorization: Bearer your_secure_mcp_key" \
  http://localhost:3000/health

可用工具

工作流管理

list_workflows

列出組織中的工作流。 參數：

• limit（可選）：返回的最大工作流數量
• offset（可選）：跳過的工作流數量
• project_id（可選）：按項目 ID 過濾（使用 list_projects 查找 ID）
• tag_id（可選）：按標籤 ID 過濾（使用 list_tags 查找 ID）

示例：

{
  "limit": 10,
  "offset": 0,
  "project_id": "proj_abc123",
  "tag_id": "tag_xyz789"
}

get_workflow

按 ID 獲取工作流詳細信息。 參數：

• workflow_id（必需）：要檢索的工作流 ID

示例：

{
  "workflow_id": "wf_abc123"
}

create_workflow

創建新的工作流。 參數：

• name（必需）：工作流名稱
• description（可選）：可選描述
• project_id（可選）：要分配的項目 ID（使用 list_projects 查找 ID）
• tag_id（可選）：要分配的標籤 ID（使用 list_tags 查找 ID）
• nodes（可選）：工作流節點數組
• edges（可選）：工作流邊數組

示例：

{
  "name": "My Workflow",
  "description": "A simple workflow",
  "project_id": "proj_abc123",
  "tag_id": "tag_xyz789",
  "nodes": [
    {
      "id": "1",
      "type": "trigger",
      "data": { "type": "manual" }
    }
  ],
  "edges": []
}

update_workflow

更新工作流節點/邊。 參數：

• workflow_id（必需）：要更新的工作流 ID
• name（可選）：工作流的新名稱
• description（可選）：新描述
• project_id（可選）：要分配的項目 ID（null 表示取消分配）
• tag_id（可選）：要分配的標籤 ID（null 表示取消分配）
• nodes（可選）：更新後的工作流節點
• edges（可選）：更新後的工作流邊

示例：

{
  "workflow_id": "wf_abc123",
  "name": "Updated Workflow Name",
  "project_id": "proj_abc123",
  "nodes": [...]
}

delete_workflow

刪除工作流。 參數：

• workflow_id（必需）：要刪除的工作流 ID

示例：

{
  "workflow_id": "wf_abc123"
}

AI 生成

ai_generate_workflow

通過自然語言進行 AI 驅動的工作流生成。 參數：

• prompt（必需）：工作流的自然語言描述
• existing_workflow_id（可選）：要修改的現有工作流 ID

示例：

{
  "prompt": "Create a workflow that monitors Ethereum wallet balance and sends a Discord notification when it changes"
}

執行

execute_workflow

啟動工作流的異步執行。 參數：

• workflow_id（必需）：要執行的工作流 ID
• input（可選）：工作流的輸入數據

示例：

{
  "workflow_id": "wf_abc123",
  "input": {
    "walletAddress": "0x1234..."
  }
}

get_execution_status

輪詢執行狀態。 參數：

• execution_id（必需）：要檢查的執行 ID

示例：

{
  "execution_id": "exec_xyz789"
}

get_execution_logs

獲取執行日誌。 參數：

• execution_id（必需）：要獲取日誌的執行 ID

示例：

{
  "execution_id": "exec_xyz789"
}

組織

list_projects

列出組織中的所有項目。 參數：無

示例：

{}

list_tags

列出組織中的所有標籤。 參數：無

示例：

{}

直接鏈上執行

execute_transfer

直接發送 ETH 或 ERC - 20 代幣，無需創建工作流。 參數：

• network（必需）：區塊鏈網絡（例如，"ethereum"、"polygon"、"base"）
• recipient_address（必需）：目標錢包地址
• amount（必需）：以人類可讀單位表示的金額（例如，"0.1"）
• token_address（可選）：ERC - 20 合約地址；原生轉賬時省略

示例：

{
  "network": "sepolia",
  "recipient_address": "0xRecipient...",
  "amount": "0.01"
}

execute_contract_call

直接調用任何智能合約函數。自動檢測讀操作和寫操作。 參數：

• contract_address（必需）：目標合約地址
• network（必需）：區塊鏈網絡
• function_name（必需）：要調用的函數
• function_args（可選）：作為 JSON 數組字符串的參數
• abi（可選）：ABI JSON 字符串；若省略則自動獲取

execute_check_and_execute

讀取合約值，評估條件，並在滿足條件時執行寫操作。 參數：

• contract_address（必需）：要讀取的合約
• network（必需）：區塊鏈網絡
• function_name（必需）：用於條件判斷的讀取函數
• condition（必需）：{operator, value} — 運算符：eq、neq、gt、lt、gte、lte
• action（必需）：{contract_address, function_name, ...} 在條件滿足時執行的寫操作

get_direct_execution_status

檢查直接執行的狀態。返回交易哈希和區塊瀏覽器鏈接。 參數：

• execution_id（必需）：直接執行調用返回的 ID

可用資源

keeperhub://workflows

返回組織中所有工作流的列表。 URI：keeperhub://workflows MIME 類型：application/json

keeperhub://workflows/{id}

返回特定工作流的詳細信息。 URI：keeperhub://workflows/{workflow_id} MIME 類型：application/json

API 密鑰管理

要使用此 MCP 服務器，你需要從 KeeperHub 應用程序生成 API 密鑰：

1. 登錄 app.keeperhub.com
2. 導航到組織設置
3. 進入 API 密鑰部分
4. 點擊“創建 API 密鑰”
5. 給它命名並複製密鑰（僅顯示一次）
6. 在 KEEPERHUB_API_KEY 環境變量中使用該密鑰

開發

項目結構

keeperhub-mcp/
├── src/
│   ├── index.ts              # MCP 服務器入口點
│   ├── http-server.ts        # HTTP/SSE 傳輸服務器
│   ├── tools/
│   │   ├── index.ts          # 工具導出
│   │   ├── workflows.ts      # 工作流 CRUD 工具
│   │   ├── executions.ts     # 執行工具
│   │   └── generate.ts       # AI 生成工具
│   ├── resources/
│   │   ├── index.ts          # 資源導出
│   │   └── workflows.ts      # 工作流資源
│   ├── client/
│   │   └── keeperhub.ts      # KeeperHub API 客戶端
│   └── types/
│       └── index.ts          # 類型定義
├── Dockerfile
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

構建

pnpm build

類型檢查

pnpm type-check

構建 Docker 鏡像

docker build -t keeperhub-mcp .

錯誤處理

所有工具返回的錯誤格式如下：

{
  "content": [
    {
      "type": "text",
      "text": "Error: <error message>"
    }
  ],
  "isError": true
}

常見錯誤：

• 401 Unauthorized：API 密鑰無效或缺失
• 404 Not Found：工作流或執行未找到
• 400 Bad Request：參數無效
• 500 Internal Server Error：服務器錯誤

安全

• API 密鑰通過 Bearer 認證傳輸。
• 密鑰作用域限於單個組織。
• 與 KeeperHub API 的所有通信均通過 HTTPS 進行。
• 密鑰不會記錄在日誌中，也不會在錯誤消息中暴露。

📄 許可證

MIT

支持

如有問題或疑問：

• GitHub 問題：techops-services/keeperhub-mcp
• 文檔：KeeperHub 文檔