Keeperhub MCP

🚀 KeeperHub MCP Server

KeeperHub用のModel Context Protocol (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

📚 詳細ドキュメント

設定

サーバーには以下の環境変数が必要です。

トランスポートモード

サーバーは2つのトランスポートモードをサポートしています。

1. Stdioモード（デフォルト）：標準入出力通信を使用するローカルAIクライアント用
2. HTTP/SSEモード：HTTPを介したServer-Sent Eventsを使用するリモートAIエージェント用

HTTPモードを有効にするには、PORT環境変数を設定します。HTTPモードで実行する場合は、認証のためにMCP_API_KEYも設定する必要があります。

MCPクライアント設定

Stdioモード（ローカル）

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プロトコルのServer-Sent Eventsエンドポイント
• 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. "Create API Key"をクリックします。
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 Issues: techops-services/keeperhub-mcp
• ドキュメント: KeeperHub Docs