JinDaGe - keeperhub-mcp MCP Details

article

README

🚀 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

📚 详细文档

配置

服务器需要以下环境变量： | 变量 | 描述 | 是否必需 | 默认值 | |------|------|----------|---------| | KEEPERHUB_API_KEY | 你的 KeeperHub API 密钥 | 是 | - | | KEEPERHUB_API_URL | KeeperHub API 基础 URL | 否 | https://app.keeperhub.com | | PORT | HTTP/SSE 模式的端口（若使用标准输入输出则留空） | 否 | - | | MCP_API_KEY | 用于验证 MCP 请求的 API 密钥（若设置了 PORT 则必需） | 否 | - |

传输模式

服务器支持两种传输模式：

标准输入输出模式（默认）：适用于使用标准输入输出通信的本地 AI 客户端。
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 密钥：

登录 app.keeperhub.com
导航到组织设置
进入 API 密钥部分
点击“创建 API 密钥”
给它命名并复制密钥（仅显示一次）
在 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 文档

keeperhub-mcp

README

🚀 KeeperHub MCP 服务器

🚀 快速开始

✨ 主要特性

📦 安装指南

使用 Docker（推荐）

使用 Node.js

开发模式

📚 详细文档

配置

传输模式

MCP 客户端配置

标准输入输出模式（本地）

HTTP/SSE 模式（远程）

身份验证

示例：测试健康检查

可用工具

工作流管理

list_workflows

get_workflow

create_workflow

update_workflow

delete_workflow

AI 生成

ai_generate_workflow

执行

execute_workflow

get_execution_status

get_execution_logs

组织

list_projects

list_tags