HOL Hashnet MCP

1# HOL Hashnet MCP
2 
3Model Context Protocol (MCP) server for Hashgraph Online’s Registry Broker. It gives AI agents a first-class tool suite to discover, register, and chat with agents/servers on the Hashgraph network, plus workflow shortcuts for common journeys.
4 
5[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18748327.svg?style=for-the-badge)](https://doi.org/10.5281/zenodo.18748327)
6[![HOL MCP](https://img.shields.io/badge/HOL-MCP-5599FE?style=for-the-badge)](https://hol.org/mcp)
7[![HOL Registry](https://img.shields.io/badge/HOL-Registry-5599FE?style=for-the-badge)](https://hol.org/registry)
8 
9## Why use this server?
10- **Discovery & chat in one place**: Find UAIDs/agents/MCP servers, validate them, open chat sessions, and send messages via a single MCP endpoint.
11- **Registration flows**: Request quotes, submit HCS-11 registrations, and wait for completion with built-in pipelines.
12- **Ops & credits**: Inspect broker health/metrics, and manage credits (HBAR or X402), with guardrails for required approvals.
13- **DX for agent platforms**: Ships both stdio (great for Claude Desktop) and HTTP streaming/SSE (great for Cursor/Claude Code/Codex).
14 
15## Quickstart
16Prereqs: Node 18+, `pnpm` (or npm), and a broker API key.
17 
18You can get a API key at [hol.org/regsitry](https://hol.org/registry)
19 
201) Install deps and env:
21```bash
22pnpm install
23cp .env.example .env  # add REGISTRY_BROKER_API_KEY + URL
24```
252) Run (HTTP streaming, default port 3333):
26```bash
27npx @hol-org/hashnet-mcp@latest up --transport sse --port 3333
28# or from source: pnpm dev:sse
29```
303) Point your MCP client at `http://localhost:3333/mcp/stream` (or `/mcp/sse` if it prefers SSE).
31 
32### Zero-touch quickstart
33```bash
34pnpm quickstart
35```
36Guides you through copying `.env`, installing deps, running smoke checks, and launching your chosen transport (stdio or sse).
37 
38## Architecture (mental model)
39```
40Client (Cursor / Claude Code / Claude Desktop / Codex)
41   │  stdio (dev:stdio) or HTTP stream/SSE (dev:sse)
42   ▼
43Hashnet MCP (FastMCP)
44   ├─ mcp.ts (tools + schemas + instructions)
45   ├─ workflows/* (pipelines like discovery, registration, chat)
46   └─ broker.ts (RegistryBrokerClient wrapper + rate limits)
47   ▼
48Hashgraph Online Registry Broker API
49```
50 
51## MCP client setup
52### Cursor / Claude Code (HTTP)
53```json
54{
55  "mcpServers": {
56    "hashnet-mcp": {
57      "enabled": true,
58      "type": "http",
59      "url": "http://localhost:3333/mcp/stream"
60    }
61  }
62}
63```
64Use `"type": "sse"` if your build expects it.
65 
66### Claude Desktop (stdio)
67```json
68{
69  "mcpServers": {
70    "hashnet": {
71      "type": "stdio",
72      "command": "npx",
73      "args": [
74        "-y",
75        "@hol-org/hashnet-mcp",
76        "up"
77      ],
78      "env": {
79        "REGISTRY_BROKER_API_URL": "https://registry.hashgraphonline.com/api/v1",
80        "REGISTRY_BROKER_API_KEY": "<your HOL API key>"
81      }
82    }
83  }
84}
85```
86 
87## Commands
88- Dev transports: `pnpm dev:stdio` (stdio), `pnpm dev:sse` (HTTP stream/SSE)
89- Build / prod: `pnpm build` then `pnpm start`
90- NPX runner: `npx @hol-org/hashnet-mcp up --transport sse --port 3333`
91- Local TS runner: `pnpm cli:up -- --transport sse`
92- Guided DX: `pnpm quickstart` (env copy → deps → smoke → launch)
93- Manual chat smoke: `pnpm chat:smoke --uaid <uaid> [--auth-token <token>] [--top-up --account-id <id> --private-key <key>]`
94- Workflows: `pnpm workflow:list`, `pnpm workflow:run <name> --payload examples/workflows/<file>.json`
95- Tests: `pnpm test --run --coverage`
96 
97## Tooling at a glance
98Categories are exposed as MCP tools (`hol.*`) plus workflows (`workflow.*`):
99- **Discovery**: `hol.search`, `hol.vectorSearch`, `hol.agenticSearch`, `hol.delegate.suggest`, `hol.registrySearchByNamespace`, `hol.resolveUaid`
100- **Registration**: `hol.getRegistrationQuote`, `hol.registerAgent`, `hol.waitForRegistrationCompletion`, `hol.updateAgent`
101- **Chat**: `hol.chat.createSession` (uaid or agentUrl), `hol.chat.sendMessage` (sessionId or uaid/agentUrl; auto-creates session), `hol.chat.history`, `hol.chat.compact`, `hol.chat.end`, `hol.closeUaidConnection`; encrypted helpers: `hol.chat.ensureEncryptionKey`, `hol.chat.startEncryptedConversation`, `hol.chat.acceptEncryptedConversation`, `hol.chat.sendEncrypted`
102- **Protocols/Ops**: `hol.listProtocols`, `hol.detectProtocol`, `hol.stats`, `hol.metricsSummary`, `hol.dashboardStats`, `hol.websocketStats`
103- **Credits**: `hol.credits.balance`, `hol.purchaseCredits.hbar`, `hol.x402.minimums`, `hol.x402.buyCredits`
104- **Ledger**: `hol.ledger.challenge`, `hol.ledger.authenticate`
105- **Workflows** (pipelines): discovery, registration, full registration, chat smoke, encrypted chat, ops check, ERC-8004 and X402 helpers, OpenRouter chat, registry showcase, Agentverse bridge. See `examples/workflows/` for payloads.
106 
107## Usage patterns
108- **Delegation (default)**: `workflow.delegate { task }` to discover a top candidate and message them immediately (set `REGISTRY_BROKER_API_KEY` or authenticate with the ledger if chat is protected).
109- **Delegation (pick-first)**: `hol.delegate.suggest { task }` then `hol.chat.sendMessage { uaid, message }` to ask a specialized registry agent for a focused deliverable.
110- **Discovery**: `workflow.discovery { query?, limit? }` or `hol.search` / `hol.vectorSearch` / `hol.agenticSearch` with filters (`capabilities`, `metadata`, `type=ai-agents|mcp-servers`).
111- **Registration**: `workflow.registerMcp { payload }` (quote → register → wait) or `workflow.fullRegistration` to add discovery/chat/ops.
112- **Chat**: Start with `hol.chat.sendMessage { uaid, message }` if you don’t have a sessionId— it will create a session and send. Otherwise use `hol.chat.createSession` then `hol.chat.sendMessage { sessionId, message }`. Manage with `hol.chat.history/compact/end`. For end-to-end encrypted sessions, run `workflow.encryptedChat` or the `hol.chat.start/accept/sendEncrypted` trio after calling `hol.chat.ensureEncryptionKey`.
113- **Ops/Health**: `workflow.opsCheck` or the `hol.stats`/`hol.metricsSummary`/`hol.dashboardStats` trio.
114- **Credits**: Always check `hol.credits.balance` before purchasing; use HBAR or X402 tools with explicit approval.
115- **Memory**: When `MEMORY_ENABLED=1`, workflows (chatSmoke, openrouterChat, historyTopUp, registryBrokerShowcase, fullRegistration) will load scoped context and append chat/discovery traces; pass `disableMemory: true` to skip.
116 
117## Memory (how it works)
118- Enable with `MEMORY_ENABLED=1` (defaults to a file-backed store at `MEMORY_STORAGE_PATH`; use `MEMORY_STORE=memory` for in-memory only, or `MEMORY_STORE=sqlite` if you want SQLite and have native build tools installed). Tune `MEMORY_MAX_ENTRIES_PER_SCOPE`, `MEMORY_DEFAULT_TTL_SECONDS`, `MEMORY_SUMMARY_TRIGGER`, `MEMORY_MAX_RETURN_ENTRIES`, and `MEMORY_CAPTURE_TOOLS`.
119- MCP tools: `hol.memory.context`, `hol.memory.note`, `hol.memory.search`, `hol.memory.clear` (see `help://hol/memory`). Scopes use `uaid`, `sessionId`, `namespace`, or `userId`.
120- Automatic capture: `hol.chat.sendMessage` logs user/assistant exchanges; tool wrapper can log tool calls/results when `MEMORY_CAPTURE_TOOLS=1`.
121- Workflows: `chatSmoke`, `openrouterChat`, `historyTopUp`, `registryBrokerShowcase`, and `fullRegistration` load prior context and append transcripts/results when memory is enabled. Add `disableMemory: true` in workflow inputs to opt out.
122- Guardrails: entries are truncated to stay within size budgets, secrets are redacted, TTL + max-entries bounds keep storage from growing unbounded. Summaries are generated heuristically once thresholds are exceeded.
123 
124## Tool catalog (what each does)
125**Discovery**
126- `hol.search` — keyword discovery with filters (capabilities, metadata, type).
127- `hol.vectorSearch` — semantic similarity search for agents.
128- `hol.agenticSearch` — hybrid semantic + lexical search (uses broker `/search/agentic` when available).
129- `hol.delegate.suggest` — shortlist candidates for delegating a subtask (includes message templates).
130- `hol.registrySearchByNamespace` — search within a specific registry.
131- `hol.resolveUaid` — resolve + validate + connection status for a UAID.
132- `hol.closeUaidConnection` — force-close a UAID connection.
133 
134**Registration**
135- `hol.getRegistrationQuote` — cost estimate for a registration payload.
136- `hol.registerAgent` — submit HCS-11 registration.
137- `hol.waitForRegistrationCompletion` — poll registration attempt until done.
138- `hol.updateAgent` — update an existing registration payload.
139- `hol.additionalRegistries` — catalog of additional registries/networks.
140 
141**Chat**
142- `hol.chat.createSession` — open a session by `uaid` or `agentUrl`.
143- `hol.chat.sendMessage` — send to an existing sessionId or auto-create via `uaid/agentUrl`.
144- `hol.chat.history` / `hol.chat.compact` / `hol.chat.end` — manage chat lifecycle.
145- Encrypted helpers: `hol.chat.ensureEncryptionKey`, `hol.chat.startEncryptedConversation`, `hol.chat.acceptEncryptedConversation`, `hol.chat.sendEncrypted` (encrypt/decrypt via broker-managed keys).
146 
147**Protocols / Ops**
148- `hol.stats`, `hol.metricsSummary`, `hol.dashboardStats`, `hol.websocketStats` — broker health/metrics.
149 
150**Credits**
151- `hol.credits.balance` — check balances (API key + optional Hedera/X402).
152- `hol.purchaseCredits.hbar` — buy credits with HBAR.
153- `hol.x402.minimums`, `hol.x402.buyCredits` — X402 purchase helpers.
154 
155**Ledger**
156- `hol.ledger.challenge` — create ledger verification challenge.
157- `hol.ledger.authenticate` — verify challenge (sets ledger API key).
158 
159**Workflows (pipelines)**
160- Discovery: `workflow.discovery`, `workflow.erc8004Discovery`
161- Registration: `workflow.registerMcp`, `workflow.fullRegistration`, `workflow.erc8004X402`, `workflow.x402Registration`, `workflow.registerAgentErc8004`
162- Chat/Ops: `workflow.chatSmoke`, `workflow.encryptedChat`, `workflow.opsCheck`, `workflow.registryBrokerShowcase`, `workflow.openrouterChat`, `workflow.agentverseBridge`
163- Utilities: see `examples/workflows/` for payloads and `pnpm workflow:list`
164 
165## Environment
166Set in `.env` or your process:
167- `REGISTRY_BROKER_API_URL` (default `https://registry.hashgraphonline.com/api/v1`)
168- `REGISTRY_BROKER_API_KEY` (required for live broker)
169- Optional: `HEDERA_ACCOUNT_ID`, `HEDERA_PRIVATE_KEY` (auto top-up), `LOG_LEVEL`, `PORT`, `HTTP_STREAM_PORT`, `BROKER_*` rate limit vars, `WORKFLOW_DRY_RUN`, `BROKER_AUTO_TOP_UP`.
170- Encrypted chat defaults: `ENCRYPTED_CHAT_KEY_LABEL`, `ENCRYPTED_CHAT_PREFERENCE` (`preferred|required|disabled`), `ENCRYPTED_CHAT_AUTO_DECRYPT` (1/0), plus history tuning knobs `HISTORY_COMPACTION_TOP_UP_HBAR`, `CHAT_HISTORY_TTL_SECONDS`.
171- Memory (optional): set `MEMORY_ENABLED=1` to enable local storage (defaults to file-backed JSON at `MEMORY_STORAGE_PATH`; use `MEMORY_STORE=memory` for in-memory only, or `MEMORY_STORE=sqlite` if you want SQLite with native deps). Tune `MEMORY_MAX_ENTRIES_PER_SCOPE`, `MEMORY_DEFAULT_TTL_SECONDS`, and `MEMORY_SUMMARY_TRIGGER`. See `help://hol/memory` for the `hol.memory.*` tools.
172 
173## Testing & quality
174- Run once with coverage: `pnpm test --run --coverage`
175- Tool E2E (real broker): `pnpm test:tools` (set test UAIDs or rely on discovery)
176- Tool E2E (mock): `pnpm test:tools:mock`
177 
178## Deploy
179- Builds to `dist/` via `tsup`. Prod entry: `dist/index.js`, CLI bin: `dist/cli/up.js`.
180- Deploy docs for Fly/Cloud Run under `deploy/`. Health probe at `/healthz`.
181 
182## Logging & observability
183- `pino` structured logs; set `LOG_LEVEL=fatal|error|warn|info|debug|trace`.
184- Each tool call logs requestId + duration. SSE/HTTP transport logs requests. Credits/registration calls surface broker status/body on failure.
185