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 文档