@hol-org/hashnet-mcp 0.1.0-canary.15.745b5eb

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,118 @@
+# HOL MCP Server POC
+
+No-stubs MCP server that bridges MCP tools to the HOL Registry Broker using `@hashgraphonline/standards-sdk`.
+
+## Quickstart
+
+1. Install dependencies:
+   - `pnpm install`
+2. Configure env:
+   - `cp .env.example .env`
+   - set `REGISTRY_BROKER_API_KEY` for paid flows, or configure ledger auth with `LEDGER_ACCOUNT_ID`/`HEDERA_ACCOUNT_ID` plus the matching network and private key
+3. Run transports:
+   - HTTP: `pnpm dev:http`
+   - stdio: `pnpm dev:stdio`
+   - HTTP + legacy SSE: `pnpm dev:http:compat`
+
+## NPX Launch
+
+Once this package is published, you can launch it directly with `npx`:
+
+- stdio: `REGISTRY_BROKER_API_KEY=... npx @hol-org/hashnet-mcp --stdio`
+- HTTP: `REGISTRY_BROKER_API_KEY=... npx @hol-org/hashnet-mcp --http --host 127.0.0.1 --port 3333`
+- help: `npx @hol-org/hashnet-mcp --help`
+
+Ledger-auth launches use the same binary and env-based credentials:
+
+- stdio: `LEDGER_ACCOUNT_ID=0.0.12345 HEDERA_NETWORK=hedera:testnet HEDERA_PRIVATE_KEY=... npx @hol-org/hashnet-mcp --stdio`
+
+When installed globally or linked locally, the binary name is `hashnet-mcp`.
+
+Supported CLI flags:
+
+- `--transport <stdio|http>`
+- `--stdio`
+- `--http`
+- `--host <host>`
+- `--port <port>`
+- `--allowed-origins <csv>`
+- `--broker-url <url>`
+- `--bearer-token <token>`
+- `--log-level <level>`
+- `--legacy-sse`
+
+## Commands
+
+- `pnpm build`
+- `pnpm start`
+- `pnpm test:run`
+- `pnpm test:coverage`
+- `pnpm check:no-stubs`
+- `pnpm smoke:http`
+- `pnpm smoke:stdio`
+
+## Security Defaults
+
+- Binds to `127.0.0.1` by default.
+- Validates `Origin` for HTTP requests when present.
+- Supports optional `MCP_SERVER_BEARER_TOKEN` gate for HTTP transport.
+- Reaps idle HTTP sessions and enforces a maximum active session count.
+- Redacts sensitive secrets in logs.
+
+## Tool Surface
+
+- Discovery: `hol.stats`, `hol.capabilities`, `hol.search`, `hol.vectorSearch`, `hol.resolveUaid`
+- Chat: `hol.chat.createSession`, `hol.chat.sendMessage`, `hol.chat.history`, `hol.chat.end`
+- Registration: `hol.getRegistrationQuote`, `hol.registerAgent`, `hol.waitForRegistrationCompletion`
+- Workflows: `workflow.discovery`, `workflow.delegate`, `workflow.registration`
+
+All tools now return a structured success envelope in `structuredContent`:
+
+- `ok`
+- `data`
+- `meta`
+
+Tool failures return `isError: true` plus a structured error envelope with machine-readable `code`, `category`, and `retryable` fields.
+
+## Transport Compatibility
+
+| Transport | Endpoint(s) | Status |
+|---|---|---|
+| stdio | process stdin/stdout | supported |
+| Streamable HTTP | `/mcp`, `/mcp/stream` | supported |
+| legacy HTTP+SSE | `/mcp/sse`, `/mcp/messages` | supported behind `FEATURE_LEGACY_SSE=1` |
+
+## HTTP Runtime Endpoints
+
+- MCP: `/mcp`, `/mcp/stream`
+- Health: `/healthz`
+- Readiness: `/readyz`
+- Metrics: `/metrics`
+
+## Environment Matrix
+
+| Variable | Required | Notes |
+|---|---|---|
+| `REGISTRY_BROKER_API_URL` | no | defaults to `https://hol.org/registry/api/v1` |
+| `REGISTRY_BROKER_API_KEY` | no | enables paid tools with a static broker API key |
+| `BROKER_REQUEST_TIMEOUT_MS` | no | default upstream request timeout is `15000` |
+| `MCP_TRANSPORT` | no | `http` (default) or `stdio` |
+| `MCP_HOST` | no | defaults to `127.0.0.1` |
+| `MCP_PORT` | no | defaults to `3333` |
+| `MCP_ALLOWED_ORIGINS` | no | used for HTTP Origin validation |
+| `MCP_SERVER_BEARER_TOKEN` | no | required when binding to non-local host |
+| `MCP_SESSION_IDLE_TTL_MS` | no | idle HTTP session timeout, defaults to `900000` |
+| `MCP_SESSION_MAX_COUNT` | no | maximum active HTTP sessions, defaults to `250` |
+| `MCP_SESSION_REAP_INTERVAL_MS` | no | idle session reap interval, defaults to `60000` |
+| `LEDGER_ACCOUNT_ID` | no | generic ledger identity used for ledger-auth flows; falls back to `HEDERA_ACCOUNT_ID` |
+| `HEDERA_ACCOUNT_ID` | no | Hedera account id for ledger auth and backwards compatibility |
+| `HEDERA_NETWORK` | no | Hedera ledger network, for example `hedera:testnet` |
+| `HEDERA_PRIVATE_KEY` | no | Hedera private key for broker ledger auth |
+| `EVM_LEDGER_NETWORK` | no | EVM CAIP-2 network id, for example `eip155:1` |
+| `ETH_PK` | no | EVM private key for broker ledger auth |
+
+## No-Stubs Validation
+
+- Static stub ban check in CI.
+- Smoke tests validate initialize -> tools/list -> real tool calls.
+- Live Broker calls required for final acceptance gates.

package/bin/hashnet-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli/up.js";

package/dist/cli/up.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+// src/cli/args.ts
+var HELP_TEXT = `HOL MCP Server
+
+Usage:
+  npx @hol-org/hashnet-mcp [options]
+
+Options:
+  --transport <stdio|http>       Select MCP transport
+  --stdio                        Shortcut for --transport stdio
+  --http                         Shortcut for --transport http
+  --host <host>                  HTTP bind host
+  --port <port>                  HTTP bind port
+  --allowed-origins <csv>        Comma-separated HTTP origin allowlist
+  --broker-url <url>             Registry Broker base URL
+  --bearer-token <token>         HTTP bearer token gate
+  --log-level <level>            Pino log level
+  --legacy-sse                   Enable legacy SSE compatibility routes
+  --help                         Show this help
+
+Examples:
+  npx @hol-org/hashnet-mcp --stdio
+  npx @hol-org/hashnet-mcp --http --host 127.0.0.1 --port 3333
+  REGISTRY_BROKER_API_KEY=... npx @hol-org/hashnet-mcp --stdio
+`;
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+function parsePort(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`--port must be a positive integer, received "${value}"`);
+  }
+  return String(parsed);
+}
+function parseCliArgs(argv) {
+  const env = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "--help":
+        return {
+          env,
+          helpText: HELP_TEXT
+        };
+      case "--transport": {
+        const value = requireValue(argv, index + 1, "--transport");
+        if (value !== "stdio" && value !== "http") {
+          throw new Error(`--transport must be "stdio" or "http", received "${value}"`);
+        }
+        env.MCP_TRANSPORT = value;
+        index += 1;
+        break;
+      }
+      case "--stdio":
+        env.MCP_TRANSPORT = "stdio";
+        break;
+      case "--http":
+        env.MCP_TRANSPORT = "http";
+        break;
+      case "--host":
+        env.MCP_HOST = requireValue(argv, index + 1, "--host");
+        index += 1;
+        break;
+      case "--port":
+        env.MCP_PORT = parsePort(requireValue(argv, index + 1, "--port"));
+        index += 1;
+        break;
+      case "--allowed-origins":
+        env.MCP_ALLOWED_ORIGINS = requireValue(argv, index + 1, "--allowed-origins");
+        index += 1;
+        break;
+      case "--broker-url":
+        env.REGISTRY_BROKER_API_URL = requireValue(argv, index + 1, "--broker-url");
+        index += 1;
+        break;
+      case "--bearer-token":
+        env.MCP_SERVER_BEARER_TOKEN = requireValue(argv, index + 1, "--bearer-token");
+        index += 1;
+        break;
+      case "--log-level":
+        env.LOG_LEVEL = requireValue(argv, index + 1, "--log-level");
+        index += 1;
+        break;
+      case "--legacy-sse":
+        env.FEATURE_LEGACY_SSE = "1";
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return { env };
+}
+
+// src/cli/up.ts
+async function main() {
+  try {
+    const parsed = parseCliArgs(process.argv.slice(2));
+    if (parsed.helpText) {
+      process.stdout.write(`${parsed.helpText}
+`);
+      return;
+    }
+    Object.assign(process.env, parsed.env);
+    await import("../index.js");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}
+`);
+    process.exitCode = 1;
+  }
+}
+void main();
+//# sourceMappingURL=up.js.map

package/dist/cli/up.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/args.ts","../../src/cli/up.ts"],"sourcesContent":["export interface CliParseResult {\n  env: Record<string, string>;\n  helpText?: string;\n}\n\nconst HELP_TEXT = `HOL MCP Server\n\nUsage:\n  npx @hol-org/hashnet-mcp [options]\n\nOptions:\n  --transport <stdio|http>       Select MCP transport\n  --stdio                        Shortcut for --transport stdio\n  --http                         Shortcut for --transport http\n  --host <host>                  HTTP bind host\n  --port <port>                  HTTP bind port\n  --allowed-origins <csv>        Comma-separated HTTP origin allowlist\n  --broker-url <url>             Registry Broker base URL\n  --bearer-token <token>         HTTP bearer token gate\n  --log-level <level>            Pino log level\n  --legacy-sse                   Enable legacy SSE compatibility routes\n  --help                         Show this help\n\nExamples:\n  npx @hol-org/hashnet-mcp --stdio\n  npx @hol-org/hashnet-mcp --http --host 127.0.0.1 --port 3333\n  REGISTRY_BROKER_API_KEY=... npx @hol-org/hashnet-mcp --stdio\n`;\n\nfunction requireValue(argv: string[], index: number, flag: string): string {\n  const value = argv[index];\n  if (!value || value.startsWith(\"--\")) {\n    throw new Error(`${flag} requires a value`);\n  }\n\n  return value;\n}\n\nfunction parsePort(value: string): string {\n  const parsed = Number(value);\n  if (!Number.isInteger(parsed) || parsed <= 0) {\n    throw new Error(`--port must be a positive integer, received \"${value}\"`);\n  }\n\n  return String(parsed);\n}\n\nexport function parseCliArgs(argv: string[]): CliParseResult {\n  const env: Record<string, string> = {};\n\n  for (let index = 0; index < argv.length; index += 1) {\n    const arg = argv[index];\n\n    switch (arg) {\n      case \"--help\":\n        return {\n          env,\n          helpText: HELP_TEXT,\n        };\n      case \"--transport\": {\n        const value = requireValue(argv, index + 1, \"--transport\");\n        if (value !== \"stdio\" && value !== \"http\") {\n          throw new Error(`--transport must be \"stdio\" or \"http\", received \"${value}\"`);\n        }\n        env.MCP_TRANSPORT = value;\n        index += 1;\n        break;\n      }\n      case \"--stdio\":\n        env.MCP_TRANSPORT = \"stdio\";\n        break;\n      case \"--http\":\n        env.MCP_TRANSPORT = \"http\";\n        break;\n      case \"--host\":\n        env.MCP_HOST = requireValue(argv, index + 1, \"--host\");\n        index += 1;\n        break;\n      case \"--port\":\n        env.MCP_PORT = parsePort(requireValue(argv, index + 1, \"--port\"));\n        index += 1;\n        break;\n      case \"--allowed-origins\":\n        env.MCP_ALLOWED_ORIGINS = requireValue(argv, index + 1, \"--allowed-origins\");\n        index += 1;\n        break;\n      case \"--broker-url\":\n        env.REGISTRY_BROKER_API_URL = requireValue(argv, index + 1, \"--broker-url\");\n        index += 1;\n        break;\n      case \"--bearer-token\":\n        env.MCP_SERVER_BEARER_TOKEN = requireValue(argv, index + 1, \"--bearer-token\");\n        index += 1;\n        break;\n      case \"--log-level\":\n        env.LOG_LEVEL = requireValue(argv, index + 1, \"--log-level\");\n        index += 1;\n        break;\n      case \"--legacy-sse\":\n        env.FEATURE_LEGACY_SSE = \"1\";\n        break;\n      default:\n        throw new Error(`Unknown argument: ${arg}`);\n    }\n  }\n\n  return { env };\n}\n\nexport function getCliHelpText(): string {\n  return HELP_TEXT;\n}\n","#!/usr/bin/env node\n\nimport { parseCliArgs } from \"./args.js\";\n\nasync function main(): Promise<void> {\n  try {\n    const parsed = parseCliArgs(process.argv.slice(2));\n\n    if (parsed.helpText) {\n      process.stdout.write(`${parsed.helpText}\\n`);\n      return;\n    }\n\n    Object.assign(process.env, parsed.env);\n    await import(\"../index.js\");\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    process.stderr.write(`${message}\\n`);\n    process.exitCode = 1;\n  }\n}\n\nvoid main();\n"],"mappings":";;;AAKA,IAAM,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAwBlB,SAAS,aAAa,MAAgB,OAAe,MAAsB;AACzE,QAAM,QAAQ,KAAK,KAAK;AACxB,MAAI,CAAC,SAAS,MAAM,WAAW,IAAI,GAAG;AACpC,UAAM,IAAI,MAAM,GAAG,IAAI,mBAAmB;AAAA,EAC5C;AAEA,SAAO;AACT;AAEA,SAAS,UAAU,OAAuB;AACxC,QAAM,SAAS,OAAO,KAAK;AAC3B,MAAI,CAAC,OAAO,UAAU,MAAM,KAAK,UAAU,GAAG;AAC5C,UAAM,IAAI,MAAM,gDAAgD,KAAK,GAAG;AAAA,EAC1E;AAEA,SAAO,OAAO,MAAM;AACtB;AAEO,SAAS,aAAa,MAAgC;AAC3D,QAAM,MAA8B,CAAC;AAErC,WAAS,QAAQ,GAAG,QAAQ,KAAK,QAAQ,SAAS,GAAG;AACnD,UAAM,MAAM,KAAK,KAAK;AAEtB,YAAQ,KAAK;AAAA,MACX,KAAK;AACH,eAAO;AAAA,UACL;AAAA,UACA,UAAU;AAAA,QACZ;AAAA,MACF,KAAK,eAAe;AAClB,cAAM,QAAQ,aAAa,MAAM,QAAQ,GAAG,aAAa;AACzD,YAAI,UAAU,WAAW,UAAU,QAAQ;AACzC,gBAAM,IAAI,MAAM,oDAAoD,KAAK,GAAG;AAAA,QAC9E;AACA,YAAI,gBAAgB;AACpB,iBAAS;AACT;AAAA,MACF;AAAA,MACA,KAAK;AACH,YAAI,gBAAgB;AACpB;AAAA,MACF,KAAK;AACH,YAAI,gBAAgB;AACpB;AAAA,MACF,KAAK;AACH,YAAI,WAAW,aAAa,MAAM,QAAQ,GAAG,QAAQ;AACrD,iBAAS;AACT;AAAA,MACF,KAAK;AACH,YAAI,WAAW,UAAU,aAAa,MAAM,QAAQ,GAAG,QAAQ,CAAC;AAChE,iBAAS;AACT;AAAA,MACF,KAAK;AACH,YAAI,sBAAsB,aAAa,MAAM,QAAQ,GAAG,mBAAmB;AAC3E,iBAAS;AACT;AAAA,MACF,KAAK;AACH,YAAI,0BAA0B,aAAa,MAAM,QAAQ,GAAG,cAAc;AAC1E,iBAAS;AACT;AAAA,MACF,KAAK;AACH,YAAI,0BAA0B,aAAa,MAAM,QAAQ,GAAG,gBAAgB;AAC5E,iBAAS;AACT;AAAA,MACF,KAAK;AACH,YAAI,YAAY,aAAa,MAAM,QAAQ,GAAG,aAAa;AAC3D,iBAAS;AACT;AAAA,MACF,KAAK;AACH,YAAI,qBAAqB;AACzB;AAAA,MACF;AACE,cAAM,IAAI,MAAM,qBAAqB,GAAG,EAAE;AAAA,IAC9C;AAAA,EACF;AAEA,SAAO,EAAE,IAAI;AACf;;;ACvGA,eAAe,OAAsB;AACnC,MAAI;AACF,UAAM,SAAS,aAAa,QAAQ,KAAK,MAAM,CAAC,CAAC;AAEjD,QAAI,OAAO,UAAU;AACnB,cAAQ,OAAO,MAAM,GAAG,OAAO,QAAQ;AAAA,CAAI;AAC3C;AAAA,IACF;AAEA,WAAO,OAAO,QAAQ,KAAK,OAAO,GAAG;AACrC,UAAM,OAAO,aAAa;AAAA,EAC5B,SAAS,OAAO;AACd,UAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,YAAQ,OAAO,MAAM,GAAG,OAAO;AAAA,CAAI;AACnC,YAAQ,WAAW;AAAA,EACrB;AACF;AAEA,KAAK,KAAK;","names":[]}