Hashnet MCP Js

🚀 HOL Hashnet MCP

HOL Hashnet MCP 是為 Hashgraph Online 的註冊表代理提供的模型上下文協議（MCP）服務器。它為 AI 代理提供了一套一流的工具套件，可用於在 Hashgraph 網絡上發現、註冊代理/服務器並與它們進行聊天，同時還為常見操作提供了工作流快捷方式。

✨ 主要特性

• 一站式發現與聊天：通過單一的 MCP 端點，查找 UAIDs/代理/MCP 服務器，驗證它們，開啟聊天會話併發送消息。
• 註冊流程：請求報價，提交 HCS - 11 註冊，並通過內置管道等待註冊完成。
• 操作與信用管理：檢查代理的健康狀況和指標，管理信用（HBAR 或 X402），並設置必要的審批機制。
• 代理平臺的開發體驗：同時支持標準輸入輸出（適用於 Claude Desktop）和 HTTP 流/SSE（適用於 Cursor/Claude Code/Codex）。

🚀 快速開始

前提條件

需要 Node 18+、pnpm（或 npm）以及一個代理 API 密鑰。你可以在 hol.org/regsitry 獲取 API 密鑰。

安裝依賴和配置環境

pnpm install
cp .env.example .env  # 添加 REGISTRY_BROKER_API_KEY 和 URL

運行服務（HTTP 流，默認端口 3333）

npx @hol-org/hashnet-mcp@latest up --transport sse --port 3333
# 或者從源代碼運行：pnpm dev:sse

配置 MCP 客戶端

將 MCP 客戶端指向 http://localhost:3333/mcp/stream（如果客戶端偏好 SSE，則使用 /mcp/sse）。

零接觸快速啟動

pnpm quickstart

該命令將引導你完成複製 .env 文件、安裝依賴、運行冒煙測試以及啟動所選傳輸方式（標準輸入輸出或 SSE）的過程。

📚 詳細文檔

架構（概念模型）

客戶端 (Cursor / Claude Code / Claude Desktop / Codex)
   │  標準輸入輸出 (dev:stdio) 或 HTTP 流/SSE (dev:sse)
   ▼
Hashnet MCP (FastMCP)
   ├─ mcp.ts (工具 + 模式 + 指令)
   ├─ workflows/* (如發現、註冊、聊天等管道)
   └─ broker.ts (註冊表代理客戶端包裝器 + 速率限制)
   ▼
Hashgraph Online 註冊表代理 API

MCP 客戶端設置

Cursor / Claude Code (HTTP)

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

如果你的構建需要 SSE 傳輸方式，請使用 "type": "sse"。

Claude Desktop (標準輸入輸出)

{
  "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": "<你的 HOL API 密鑰>"
      }
    }
  }
}

命令說明

• 開發傳輸方式：pnpm dev:stdio（標準輸入輸出），pnpm dev:sse（HTTP 流/SSE）
• 構建與生產環境：pnpm build 然後 pnpm start
• NPX 運行器：npx @hol-org/hashnet-mcp up --transport sse --port 3333
• 本地 TypeScript 運行器：pnpm cli:up -- --transport sse
• 引導式開發體驗：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 — 帶過濾器（功能、元數據、類型）的關鍵字發現。
• 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；使用 MEMORY_STORE = memory 僅使用內存存儲，若要使用 SQLite 存儲且已安裝原生依賴，可使用 MEMORY_STORE = sqlite）。可調整 MEMORY_MAX_ENTRIES_PER_SCOPE、MEMORY_DEFAULT_TTL_SECONDS 和 MEMORY_SUMMARY_TRIGGER。詳情請參考 help://hol/memory 瞭解 hol.memory.* 工具。

測試與質量保證

• 運行一次並生成覆蓋率報告：pnpm test --run --coverage
• 工具端到端測試（真實代理）：pnpm test:tools（設置測試 UAIDs 或依賴發現功能）
• 工具端到端測試（模擬）：pnpm test:tools:mock

部署

• 通過 tsup 構建到 dist/ 目錄。生產環境入口為 dist/index.js，CLI 二進制文件為 dist/cli/up.js。
• deploy/ 目錄下包含 Fly/Cloud Run 的部署文檔。健康檢查接口為 /healthz。

日誌與可觀測性

• 使用 pino 結構化日誌；設置 LOG_LEVEL = fatal|error|warn|info|debug|trace。
• 每個工具調用會記錄請求 ID 和持續時間。SSE/HTTP 傳輸會記錄請求信息。信用/註冊調用失敗時會顯示代理狀態和響應體。