ヘデラMCPサーバー

概要

Hedera MCPサーバーは、 Hederaネットワーク上のAIエージェント間の分散通信を可能にするために設計された、本番環境対応のモジュール型Node.js（TypeScript）サーバーです。Model **-Context-Protocol（MCP）**アーキテクチャを実装し、RESTful APIとSSE（Server-Sent Events）ベースのMCPインターフェースの両方を公開しています。

Hedera エージェント キットを標準エージェント キットと一緒に使用することで、サーバーは複数の Hedera コンセンサス サービス (HCS) 標準をサポートします。

• HCS-1（ファイル/データ管理）

• HCS-2（エージェント検出レジストリ）

• HCS-3 (大規模メッセージの処理と再帰)

• HCS-10（エージェント通信プロトコル）

• HCS-11（分散型アイデンティティ/プロファイル管理）

このサーバーは、ハッカソン参加者や、Hedera上でAI統合型分散アプリケーションを構築する開発者を特に対象としています。また、自律エージェントインタラクションを実現するCursorなどのツールとも互換性があります。

Related MCP server: HashPilot

フォルダ構造

hedera-mcp-server/
├── src/
│   ├── config/
│   │   └── config.ts             # Configuration loader (environment variables, Hedera client)
│   ├── services/
│   │   ├── agentService.ts       # Agent registration & profile management (HCS-10/HCS-11)
│   │   ├── connectionService.ts  # Connection request, acceptance & messaging (HCS-10)
│   │   ├── fileService.ts        # File storage for large messages (HCS-1 & HCS-3)
│   │   ├── logger.ts             # Logging utility
│   │   └── profileUtil.ts        # Helper for serializing agent profiles
│   ├── routes/
│   │   ├── agentRoutes.ts        # API endpoints for agent registration & query
│   │   ├── connectionRoutes.ts   # API endpoints for connection and messaging
│   │   └── index.ts              # Route aggregator for the REST API
│   ├── mcp/
│   │   └── mcpServer.ts          # MCP server (SSE interface) definition using FastMCP and Zod
│   └── index.ts                  # Main entry point to initialize Express and MCP servers
├── test/
│   ├── unit/
│   │   ├── agentService.test.ts       # Unit tests for agent logic and profile serialization
│   │   ├── connectionService.test.ts  # Unit tests for connection and message formatting
│   │   └── fileService.test.ts        # Unit tests for file chunking and file storage
│   ├── integration/
│   │   └── apiEndpoints.test.ts       # Integration tests for REST API endpoints
│   └── e2e/
│       └── agentCommunication.e2e.ts  # End-to-end tests simulating agent registration, connection, and messaging
├── Dockerfile                   # Docker configuration for building the server image
├── docker-compose.yml           # One-command deployment configuration for Docker
├── package.json                 # Project metadata and scripts
└── README.md                    # This file

特徴

• エージェント登録とプロファイル (HCS-11):
  AIエージェント用に新しいHederaアカウントを作成（または既存のアカウントをインポート）します。インバウンド/アウトバウンドトピックとオンチェーンプロファイルを自動的に設定します。

• エージェント検出（HCS-2）：
  一元化されたレジストリトピックにエージェントを登録します。提供されている検索APIを使用して、名前または機能でエージェントを検索します。

• セキュア通信（HCS-10）：
  エージェント間の接続要求を開始および承認します。エージェントが安全にメッセージを交換できる専用の接続トピックを確立します。

• 大規模メッセージの処理 (HCS-1 および HCS-3):
  専用のファイル トピックに大量のメッセージ コンテンツを保存し、メッセージ内で HRL (HCS リソース ロケーター) 参照を返すことで、大量のメッセージ コンテンツをオフロードします。

• SSE経由のMCPインターフェース:
  MCP 準拠の SSE エンドポイントを公開します ( FastMCP経由)。これにより、Cursor などの AI ツールがサーバーの「ツール」(register_agent、send_message など) を直接呼び出すことができます。

• RESTful API:
  詳細な要求/応答形式を使用して、エージェント操作、接続管理、メッセージングのための包括的な HTTP エンドポイントを公開します。

• 本番環境対応のデプロイメント:
  シームレスなワンコマンド展開を実現する Docker および Docker Compose 構成が付属しています。

要件

• Node.js ≥ 18 (LTS 推奨)

• npm （Node に付属）

• DockerとDocker Compose (コンテナのデプロイメント用)

• 取引に十分な資金を持つHederaテストネット（またはメインネット）アカウント
  (次の環境変数を設定します: HEDERA_OPERATOR_IDおよびHEDERA_OPERATOR_KEY 。)

はじめる

1. リポジトリのクローンを作成する

git clone https://github.com/hgraphpunks/hedera-mcp-server.git
cd hedera-mcp-server

2. 依存関係をインストールする

npm install

3. 環境変数を設定する

プロジェクト ルートに次の内容の.envファイルを作成します (実際の資格情報に合わせて調整してください)。

# .env
HEDERA_NETWORK=testnet
HEDERA_OPERATOR_ID=0.0.12345
HEDERA_OPERATOR_KEY=302e0201...
REGISTRY_TOPIC_ID=        # (optional – if not provided, a new registry topic will be created)
PORT=3000
SSE_PORT=3001

4. プロジェクトをビルドする

TypeScript コードを JavaScript にコンパイルします。

npm run build

5. ローカルでサーバーを実行する

REST API および MCP SSE サーバーを起動します。

npm start

次のようなログが表示されます:

• REST APIはhttp://localhost:3000でリッスンしています

• MCP SSE サーバーはhttp://localhost:3001/sseで利用できます。

6. 開発モード

自動再構築による迅速な開発には、以下を使用します。

npm run dev

APIドキュメント

エージェントエンドポイント

• POST /api/agents/register
  新しいエージェントを登録します。
  リクエスト本文:

  {
    "name": "AliceAgent",
    "accountId": "0.0.ABCDE",         // optional – leave empty to generate a new account
    "privateKey": "302e0201...",       // optional – required if accountId is provided
    "capabilities": [0, 4],
    "model": "gpt-4",
    "creator": "Alice"
  }

  レスポンス（201件作成）:

  {
    "accountId": "0.0.789123",
    "privateKey": "302e0201... (if new)",
    "profile": {
      "name": "AliceAgent",
      "inboundTopicId": "0.0.444444",
      "outboundTopicId": "0.0.444445",
      "type": 1,
      "capabilities": [0, 4],
      "model": "gpt-4",
      "creator": "Alice"
    }
  }

• GET /api/agents/{アカウントID}
  アカウント ID でエージェントのプロファイルを取得します。
  応答 (200 OK):

  {
    "name": "AliceAgent",
    "inboundTopicId": "0.0.444444",
    "outboundTopicId": "0.0.444445",
    "type": 1,
    "capabilities": [0, 4],
    "model": "gpt-4",
    "creator": "Alice"
  }

• GET /api/agents?name=Alice&capability=0
  名前や機能でエージェントを検索します。
  応答 (200 OK):

  [
    {
      "name": "AliceAgent",
      "inboundTopicId": "0.0.444444",
      "outboundTopicId": "0.0.444445",
      "type": 1,
      "capabilities": [0, 4],
      "model": "gpt-4",
      "creator": "Alice"
    }
  ]

接続エンドポイント

• POST /api/connections/request
  別のエージェントへの接続要求を開始します。
  リクエスト本文:

  {
    "fromAccount": "0.0.AAAAA",
    "fromPrivateKey": "302e0201...",
    "toAccount": "0.0.BBBBB"
  }

  応答 (200 OK):

  { "requestSequenceNumber": 42 }

• POST /api/connections/accept
  接続要求を受け入れ、専用の接続トピックを作成します。
  リクエスト本文:

  {
    "fromAccount": "0.0.BBBBB",
    "fromPrivateKey": "302e0201...",
    "requesterAccount": "0.0.AAAAA"
  }

  応答 (200 OK):

  { "connectionTopicId": "0.0.CCCCC" }

• /api/connections?accountId=0.0.AAAAA を取得します。
  特定のエージェントのすべてのアクティブな接続を一覧表示します。
  応答 (200 OK):

  [
    { "peer": "0.0.BBBBB", "connectionTopicId": "0.0.CCCCC" }
  ]

メッセージングエンドポイント

• POST /api/messages/send
  確立された接続を介してメッセージを送信します。
  リクエスト本文:

  {
    "senderAccount": "0.0.AAAAA",
    "senderKey": "302e0201...",
    "connectionTopicId": "0.0.CCCCC",
    "message": "Hello, AgentB!"
  }

  応答 (200 OK):

  { "sequenceNumber": 7 }

• GET /api/messages?connectionTopicId=0.0.CCCCC&limit=10
  接続トピックから最近のメッセージを取得します。
  応答 (200 OK):

  {
    "messages": [
      "{\"p\":\"hcs-10\",\"op\":\"message\",\"operator_id\":\"0.0.444444@0.0.AAAAA\",\"data\":\"Hello, AgentB!\",\"m\":\"Message from agent.\"}"
    ]
  }

MCP SSEインターフェース

サーバーは、 FastMCPを利用した SSE (Server-Sent Events) 経由の MCP インターフェースを公開します。このインターフェースは次の場所で利用できます。

http://localhost:3001/sse

カーソルとの統合

1. サーバーを実行します。
   MCP SSEサーバーが実行中であることを確認してください（デフォルトはポート3001）。以下の説明に従って、 npm startまたはDockerを使用してください。

2. カーソルで設定:
   カーソルの MCP 設定で、次の URL を持つ新しい MCP サーバーを追加します。

   http://localhost:3001/sse

   カーソルは、使用可能なツールのリスト (例: register_agent 、 request_connection 、 send_messageなど) を自動的に取得します。

3. 使用法：
   これらのツールを使って、カーソルのAIにアクションを実行するよう指示できます。例えば、次のようにプロンプトします。

   「AliceAgent という名前の新しいエージェントを登録し、BobAgent に接続します。」
   カーソルは、SSE インターフェイスで定義されているそれぞれの MCP ツールを呼び出します。

Docker デプロイメント

このプロジェクトには、コマンド 1 つで簡単にデプロイできる Dockerfile と docker-compose.yml ファイルが付属しています。

Docker Composeの使用

1. 環境変数を確認する:
   プロジェクト ルートの.envファイルで環境変数を設定します (上記を参照)。

2. ビルドと実行:

   docker-compose up --build -d

   このコマンドはDockerイメージをビルドし、コンテナをデタッチモードで起動します。REST APIはポート3000で、MCP SSEサーバーはポート3001でアクセス可能になります。

3. 展開の検証:
   ブラウザを開くか、 curlを使用して確認します。

   • ヘルスチェック: http://localhost:3000/

   • MCP SSE エンドポイント: http://localhost:3001/sse

テスト

テストスイートの実行

このプロジェクトではテストにJestを使用しています。テストはユニットテスト、統合テスト、エンドツーエンドテストの3つのスイートに分かれています。

すべてのテストを次のように実行します。

npm test

テストには次のものが含まれます:

• **ユニット テスト:**個々のサービス内のロジックを検証します (例: fileService.test.ts内のファイル チャンク)。

• 統合テスト: Supertest を使用して REST API エンドポイントをテストし、適切な応答を確認します。

• エンドツーエンド テスト: Hedera Testnet で完全なエージェント通信フロー (エージェントの登録、接続、およびメッセージング) をシミュレートします。

*注：*テストはHedera Testnet上でライブオペレーションを実行します。テスト環境に十分な資金があり、HBARの消費量が最小限に抑えられていることを確認してください。

メンテナンスと最適化

• ログ記録と監視:
  サーバーには基本的なロガーが含まれています。本番環境では、より堅牢なロギングソリューション（WinstonやPinoなど）を統合し、ログローテーションと監視ダッシュボードを設定することを検討してください。

• キャッシング：
  エージェントプロファイルと接続リストはメモリにキャッシュされます。高負荷のシナリオでは、これらを永続的なストア（Redisやデータベースなど）に置き換えることを検討してください。

• スケーリング：
  サーバーはメモリ内キャッシュを除きステートレスです。ロードバランサーを介して水平方向にスケールできます。複数のインスタンスを使用する場合は、すべてのエージェントがグローバルレジストリに表示されるように、同じレジストリ設定を共有してください。

• セキュリティに関する考慮事項:

  • .envファイルを保護し、秘密鍵を公開しないでください。

  • 本番環境では、API エンドポイントに適切な認証/承認を実装します。

  • HTTPS やその他の安全な通信方法の使用を検討してください。

• 標準コンプライアンスの更新:
  Hedera Agent Kit と Standards Agent Kit のアップデートにご注目ください。新しいフィールドやプロトコルが導入された場合、依存関係のアップグレードには最小限の調整が必要になる場合があります。

貢献

貢献を歓迎します！リポジトリをフォークし、改善点をプルリクエストでお知らせください。大きな変更については、まずIssueを開いて、変更したい点についてご相談ください。

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています。