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 传输会记录请求信息。信用/注册调用失败时会显示代理状态和响应体。