Hashnet MCP Js

🚀 HOL Hashnet MCP

Hashgraph OnlineのRegistry Broker用のModel Context Protocol (MCP)サーバーです。これにより、AIエージェントはHashgraphネットワーク上のエージェントやサーバーを発見、登録、チャットするための一流のツールセットを利用でき、一般的なジャーニーに関するワークフローショートカットも提供されます。

🚀 クイックスタート

前提条件: Node 18以上、pnpm（またはnpm）、およびブローカーAPIキー。

APIキーはhol.org/regsitryで取得できます。

1. 依存関係と環境をインストール:

pnpm install
cp .env.example .env  # REGISTRY_BROKER_API_KEYとURLを追加

2. 実行 (HTTPストリーミング、デフォルトポート3333):

npx @hol-org/hashnet-mcp@latest up --transport sse --port 3333
# またはソースから: pnpm dev:sse

3. MCPクライアントをhttp://localhost:3333/mcp/stream（SSEを好む場合は/mcp/sse）に向けます。

ゼロタッチクイックスタート

pnpm quickstart

.envのコピー、依存関係のインストール、スモークチェックの実行、および選択したトランスポート（stdioまたはsse）の起動を案内します。

✨ 主な機能

• 一箇所での発見とチャット: 単一のMCPエンドポイントを介して、UAID/エージェント/MCPサーバーを見つけ、検証し、チャットセッションを開き、メッセージを送信できます。
• 登録フロー: 見積もりをリクエストし、HCS - 11登録を送信し、組み込みのパイプラインで完了を待つことができます。
• オペレーションとクレジット: ブローカーのヘルス/メトリクスを検査し、クレジット（HBARまたはX402）を管理し、必要な承認のガードレールを持つことができます。
• エージェントプラットフォームのDX: stdio（Claude Desktopに適しています）とHTTPストリーミング/SSE（Cursor/Claude Code/Codexに適しています）の両方を提供します。

📦 インストール

前提条件: Node 18以上、pnpm（またはnpm）、およびブローカーAPIキー。

APIキーはhol.org/regsitryで取得できます。

1. 依存関係と環境をインストール:

pnpm install
cp .env.example .env  # REGISTRY_BROKER_API_KEYとURLを追加

2. 実行 (HTTPストリーミング、デフォルトポート3333):

npx @hol-org/hashnet-mcp@latest up --transport sse --port 3333
# またはソースから: pnpm dev:sse

💻 使用例

基本的な使用法

# 依存関係のインストール
pnpm install
cp .env.example .env  # REGISTRY_BROKER_API_KEYとURLを追加

# サーバーの起動
npx @hol-org/hashnet-mcp@latest up --transport sse --port 3333

高度な使用法

# ゼロタッチクイックスタート
pnpm quickstart

このコマンドは、.envのコピー、依存関係のインストール、スモークチェックの実行、および選択したトランスポート（stdioまたはsse）の起動を自動的に行います。

📚 ドキュメント

アーキテクチャ (概念モデル)

Client (Cursor / Claude Code / Claude Desktop / Codex)
   │  stdio (dev:stdio) or HTTP stream/SSE (dev:sse)
   ▼
Hashnet MCP (FastMCP)
   ├─ mcp.ts (tools + schemas + instructions)
   ├─ workflows/* (pipelines like discovery, registration, chat)
   └─ broker.ts (RegistryBrokerClient wrapper + rate limits)
   ▼
Hashgraph Online Registry Broker API

MCPクライアントの設定

Cursor / Claude Code (HTTP)

{
  "mcpServers": {
    "hashnet-mcp": {
      "enabled": true,
      "type": "http",
      "url": "http://localhost:3333/mcp/stream"
    }
  }
}

ビルドがSSEを期待する場合は、"type": "sse"を使用します。

Claude Desktop (stdio)

{
  "mcpServers": {
    "hashnet": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@hol-org/hashnet-mcp",
        "up"
      ],
      "env": {
        "REGISTRY_BROKER_API_URL": "https://registry.hashgraphonline.com/api/v1",
        "REGISTRY_BROKER_API_KEY": "<your HOL API key>"
      }
    }
  }
}

コマンド

• 開発用トランスポート: pnpm dev:stdio (stdio)、pnpm dev:sse (HTTP stream/SSE)
• ビルド / 本番環境: pnpm build 次に pnpm start
• NPXランナー: npx @hol-org/hashnet-mcp up --transport sse --port 3333
• ローカルTSランナー: pnpm cli:up -- --transport sse
• ガイド付きDX: pnpm quickstart (環境コピー → 依存関係 → スモークチェック → 起動)
• 手動チャットスモーク: pnpm chat:smoke --uaid <uaid> [--auth-token <token>] [--top-up --account-id <id> --private-key <key>]
• ワークフロー: pnpm workflow:list、pnpm workflow:run <name> --payload examples/workflows/<file>.json
• テスト: pnpm test --run --coverage

ツールの概要

カテゴリはMCPツール (hol.*) とワークフロー (workflow.*) として公開されています。

• 発見: hol.search、hol.vectorSearch、hol.agenticSearch、hol.delegate.suggest、hol.registrySearchByNamespace、hol.resolveUaid
• 登録: hol.getRegistrationQuote、hol.registerAgent、hol.waitForRegistrationCompletion、hol.updateAgent
• チャット: hol.chat.createSession (uaidまたはagentUrl)、hol.chat.sendMessage (sessionIdまたはuaid/agentUrl; 自動的にセッションを作成)、hol.chat.history、hol.chat.compact、hol.chat.end、hol.closeUaidConnection; 暗号化ヘルパー: hol.chat.ensureEncryptionKey、hol.chat.startEncryptedConversation、hol.chat.acceptEncryptedConversation、hol.chat.sendEncrypted
• プロトコル/オペレーション: hol.listProtocols、hol.detectProtocol、hol.stats、hol.metricsSummary、hol.dashboardStats、hol.websocketStats
• クレジット: hol.credits.balance、hol.purchaseCredits.hbar、hol.x402.minimums、hol.x402.buyCredits
• レジャー: hol.ledger.challenge、hol.ledger.authenticate
• ワークフロー (パイプライン): 発見、登録、完全登録、チャットスモーク、暗号化チャット、オペレーションチェック、ERC - 8004およびX402ヘルパー、OpenRouterチャット、レジストリショーケース、Agentverseブリッジ。ペイロードについてはexamples/workflows/を参照してください。

使用パターン

• 委任 (デフォルト): workflow.delegate { task } を使用してトップ候補を発見し、すぐにメッセージを送信します（チャットが保護されている場合はREGISTRY_BROKER_API_KEYを設定するか、レジャーで認証します）。
• 委任 (最初の選択): hol.delegate.suggest { task } を実行し、次に hol.chat.sendMessage { uaid, message } を使用して、専門的なレジストリエージェントに焦点を絞った成果物を依頼します。
• 発見: workflow.discovery { query?, limit? } または hol.search / hol.vectorSearch / hol.agenticSearch をフィルター (capabilities、metadata、type=ai-agents|mcp-servers) とともに使用します。
• 登録: workflow.registerMcp { payload } (見積もり → 登録 → 待機) または workflow.fullRegistration を使用して、発見/チャット/オペレーションを追加します。
• チャット: sessionIdがない場合は hol.chat.sendMessage { uaid, message } から始めます — セッションが作成され、メッセージが送信されます。それ以外の場合は、hol.chat.createSession を使用してから hol.chat.sendMessage { sessionId, message } を使用します。hol.chat.history/compact/end で管理します。エンドツーエンド暗号化セッションの場合は、hol.chat.ensureEncryptionKey を呼び出した後、workflow.encryptedChat または hol.chat.start/accept/sendEncrypted のトリオを実行します。
• オペレーション/ヘルス: workflow.opsCheck または hol.stats/hol.metricsSummary/hol.dashboardStats のトリオを使用します。
• クレジット: 購入前に常に hol.credits.balance を確認してください。明示的な承認を得て、HBARまたはX402ツールを使用します。
• メモリ: MEMORY_ENABLED=1 の場合、ワークフロー (chatSmoke、openrouterChat、historyTopUp、registryBrokerShowcase、fullRegistration) はスコープされたコンテキストをロードし、チャット/発見のトレースを追加します。disableMemory: true を渡すとスキップできます。

メモリ (動作原理)

• MEMORY_ENABLED=1 で有効にします（デフォルトでは MEMORY_STORAGE_PATH のファイルベースのストアになります。メモリのみを使用する場合は MEMORY_STORE=memory を使用し、SQLiteを使用したい場合は MEMORY_STORE=sqlite を使用し、ネイティブビルドツールをインストールしてください）。MEMORY_MAX_ENTRIES_PER_SCOPE、MEMORY_DEFAULT_TTL_SECONDS、MEMORY_SUMMARY_TRIGGER、MEMORY_MAX_RETURN_ENTRIES、および MEMORY_CAPTURE_TOOLS を調整します。
• MCPツール: hol.memory.context、hol.memory.note、hol.memory.search、hol.memory.clear (詳細は help://hol/memory を参照)。スコープは uaid、sessionId、namespace、または userId を使用します。
• 自動キャプチャ: hol.chat.sendMessage はユーザー/アシスタントのやり取りをログに記録します。MEMORY_CAPTURE_TOOLS=1 の場合、ツールラッパーはツールの呼び出し/結果をログに記録できます。
• ワークフロー: chatSmoke、openrouterChat、historyTopUp、registryBrokerShowcase、および fullRegistration は、メモリが有効になっている場合、以前のコンテキストをロードし、トランスクリプト/結果を追加します。ワークフローの入力に disableMemory: true を追加すると、除外できます。
• ガードレール: エントリはサイズ制限内に収まるように切り捨てられ、シークレットは削除され、TTL + 最大エントリ数の制限により、ストレージが無制限に増えることを防ぎます。閾値を超えると、要約がヒューリスティックに生成されます。

ツールカタログ (各ツールの機能)

発見

• hol.search — フィルター (capabilities、metadata、type) を使用したキーワード検索。
• hol.vectorSearch — エージェントの意味的類似性検索。
• hol.agenticSearch — ハイブリッドの意味的 + 語彙検索 (利用可能な場合はブローカーの /search/agentic を使用)。
• hol.delegate.suggest — サブタスクを委任するための候補を絞り込む (メッセージテンプレートを含む)。
• hol.registrySearchByNamespace — 特定のレジストリ内で検索。
• hol.resolveUaid — UAIDの解決 + 検証 + 接続ステータス。
• hol.closeUaidConnection — UAID接続を強制的に閉じる。

登録

• hol.getRegistrationQuote — 登録ペイロードの費用見積もり。
• hol.registerAgent — HCS - 11登録を送信。
• hol.waitForRegistrationCompletion — 登録試行が完了するまでポーリング。
• hol.updateAgent — 既存の登録ペイロードを更新。
• hol.additionalRegistries — 追加のレジストリ/ネットワークのカタログ。

チャット

• hol.chat.createSession — uaid または agentUrl でセッションを開く。
• hol.chat.sendMessage — 既存のsessionIdに送信するか、uaid/agentUrl を介して自動的にセッションを作成して送信。
• hol.chat.history / hol.chat.compact / hol.chat.end — チャットのライフサイクルを管理。
• 暗号化ヘルパー: hol.chat.ensureEncryptionKey、hol.chat.startEncryptedConversation、hol.chat.acceptEncryptedConversation、hol.chat.sendEncrypted (ブローカー管理のキーを介して暗号化/復号化)。

プロトコル / オペレーション

• hol.stats、hol.metricsSummary、hol.dashboardStats、hol.websocketStats — ブローカーのヘルス/メトリクス。

クレジット

• hol.credits.balance — 残高を確認 (APIキー + オプションのHedera/X402)。
• hol.purchaseCredits.hbar — HBARでクレジットを購入。
• hol.x402.minimums、hol.x402.buyCredits — X402購入ヘルパー。

レジャー

• hol.ledger.challenge — レジャー検証チャレンジを作成。
• hol.ledger.authenticate — チャレンジを検証 (レジャーAPIキーを設定)。

ワークフロー (パイプライン)

• 発見: workflow.discovery、workflow.erc8004Discovery
• 登録: workflow.registerMcp、workflow.fullRegistration、workflow.erc8004X402、workflow.x402Registration、workflow.registerAgentErc8004
• チャット/オペレーション: workflow.chatSmoke、workflow.encryptedChat、workflow.opsCheck、workflow.registryBrokerShowcase、workflow.openrouterChat、workflow.agentverseBridge
• ユーティリティ: ペイロードについては examples/workflows/ を参照し、pnpm workflow:list で一覧を表示します。

環境

.env またはプロセスで設定します。

• REGISTRY_BROKER_API_URL (デフォルト https://registry.hashgraphonline.com/api/v1)
• REGISTRY_BROKER_API_KEY (ライブブローカーに必要)
• オプション: HEDERA_ACCOUNT_ID、HEDERA_PRIVATE_KEY (自動トップアップ)、LOG_LEVEL、PORT、HTTP_STREAM_PORT、BROKER_* レート制限変数、WORKFLOW_DRY_RUN、BROKER_AUTO_TOP_UP。
• 暗号化チャットのデフォルト: ENCRYPTED_CHAT_KEY_LABEL、ENCRYPTED_CHAT_PREFERENCE (preferred|required|disabled)、ENCRYPTED_CHAT_AUTO_DECRYPT (1/0)、および履歴調整ノブ HISTORY_COMPACTION_TOP_UP_HBAR、CHAT_HISTORY_TTL_SECONDS。
• メモリ (オプション): MEMORY_ENABLED=1 を設定してローカルストレージを有効にします（デフォルトでは MEMORY_STORAGE_PATH のファイルベースのJSONになります。メモリのみを使用する場合は MEMORY_STORE=memory を使用し、SQLiteを使用したい場合は MEMORY_STORE=sqlite を使用し、ネイティブ依存関係をインストールしてください）。MEMORY_MAX_ENTRIES_PER_SCOPE、MEMORY_DEFAULT_TTL_SECONDS、および MEMORY_SUMMARY_TRIGGER を調整します。hol.memory.* ツールについては help://hol/memory を参照してください。

テストと品質

• カバレッジ付きで一度実行: pnpm test --run --coverage
• ツールのE2Eテスト (実際のブローカー): pnpm test:tools (テストUAIDを設定するか、発見に依存する)
• ツールのE2Eテスト (モック): pnpm test:tools:mock

デプロイ

• tsup を使用して dist/ にビルドします。本番エントリ: dist/index.js、CLIバイナリ: dist/cli/up.js。
• Fly/Cloud Runのデプロイドキュメントは deploy/ の下にあります。ヘルスプローブは /healthz です。

ロギングとオブザーバビリティ

• pino 構造化ログ; LOG_LEVEL=fatal|error|warn|info|debug|trace を設定します。
• 各ツールの呼び出しはrequestId + 実行時間をログに記録します。SSE/HTTPトランスポートはリクエストをログに記録します。クレジット/登録の呼び出しは、失敗時にブローカーのステータス/ボディを表示します。