@veyanet/mcp 1.0.0

package/docs/TRANSPORT.md

@@ -0,0 +1,91 @@
+# HTTP Transport — VEYA MCP
+
+## Protocol
+
+`@veyanet/mcp` implements **MCP Streamable HTTP** using `@modelcontextprotocol/sdk`’s `StreamableHTTPServerTransport`.
+
+Public clients (Claude, Cursor) should configure:
+
+* Transport: Streamable HTTP (HTTP)
+* URL: `https://mcp.veyanet.tech/mcp`
+
+## Endpoints
+
+### `GET /`
+
+Minimal HTML landing page: paste URL, local POST hint, health link, honesty line (testnet 46630 · AES-256-GCM · not mainnet), pointer to stdio sibling path for operators.
+
+### `GET /health`
+
+JSON honesty probe. Does not require MCP session. Safe to scrape from uptime monitors.
+
+Example shape:
+
+```json
+{
+  "status": "ok",
+  "service": "@veyanet/mcp",
+  "version": "1.0.0",
+  "publicMcpUrl": "https://mcp.veyanet.tech/mcp",
+  "chainId": 46630,
+  "contractAddress": "0x1a1Dc3c55550FCE9F70ef6cDEeF967c0b72a5d84",
+  "writesEnabled": false,
+  "sealed": "AES-256-GCM (not FHE)",
+  "settlement": "Robinhood Chain testnet 46630"
+}
+```
+
+### `POST /mcp`
+
+Stateless Streamable HTTP handler. Typical Accept header from clients:
+
+```http
+Accept: application/json, text/event-stream
+Content-Type: application/json
+```
+
+Body is JSON-RPC MCP messages (initialize, tools/list, tools/call, …). Response may be JSON or SSE (`text/event-stream`) depending on client/transport negotiation.
+
+Each request constructs an MCP server instance, connects a transport, handles the request, and closes on response end.
+
+### `POST /mcp/session`
+
+Optional path for clients that use `MCP-Session-Id`. Initialize without a session id creates a session; subsequent calls reuse the transport map. Prefer `/mcp` for simple paste-URL clients unless your client requires sessions.
+
+## CORS
+
+Configured in `createHttpApp`:
+
+* No `Origin` → allowed (server-side connectors)
+* `Origin` present → must be listed in `CORS_ORIGIN`
+* Credentials enabled for allowlisted origins
+
+## Proxy requirements
+
+When placing nginx (or similar) in front:
+
+1. `proxy_http_version 1.1`
+2. Forward `Authorization`
+3. Forward `X-Forwarded-Proto`
+4. `proxy_buffering off` for streaming responses
+5. Reasonable body size (MCP JSON is small; Express limit is `1mb`)
+
+## Timeouts
+
+Tool handlers that call RPC or `api.veyanet.tech` use short fetch timeouts (e.g. 8s for API health). Upstream proxy idle timeouts should exceed typical tool latency (recommend ≥ 60s).
+
+## Local debugging
+
+```bash
+npm start
+curl -s http://127.0.0.1:8788/health
+npm run smoke
+```
+
+Smoke exercises initialize + tools/list + tool calls against an ephemeral listen port.
+
+## What this transport is not
+
+* Not stdio MCP (see Anchor package)
+* Not Server-Sent Events only (Streamable HTTP may use SSE framing but is not a raw EventSource API for operators to scrape manually)
+* Not WebSocket MCP

package/docs/VERIFICATION.md

@@ -0,0 +1,81 @@
+# Verification Guide — VEYA MCP
+
+How a stranger or auditor proves that MCP is talking to real Robinhood Chain settlement — without trusting marketing copy.
+
+## Goal
+
+Prove three facts:
+
+1. The MCP endpoint is alive and honest (`/health`, `veya_describe`).
+2. RPC chain id is **46630**.
+3. A known (or newly written) commitment exists as a `Veya.sol` event and/or mapping.
+
+## Procedure A — Public read verification (no keys)
+
+### A1. Health
+
+```bash
+curl -s https://mcp.veyanet.tech/health
+```
+
+Require:
+* `service` = `@veyanet/mcp`
+* `chainId` = `46630`
+* `sealed` contains `AES-256-GCM`
+* `publicMcpUrl` = `https://mcp.veyanet.tech/mcp` (or your documented URL)
+
+### A2. Describe via MCP client
+
+Connect Streamable HTTP to `https://mcp.veyanet.tech/mcp` and call `veya_describe`. Cross-check contract address against [NETWORK_PIN.md](./NETWORK_PIN.md).
+
+### A3. Ping
+
+Call `veya_ping_chain`. Confirm chain id string matches `46630`.
+
+### A4. Verify transaction
+
+Call `veya_verify_transaction` with:
+
+```text
+0xd68ab19671f0a3be63651cb6d6e24f5decf591da981708502827bca3689d31d8
+```
+
+Open the explorer URL from the tool result. Confirm the transaction targets `Veya.sol` and the event digest matches the tool output.
+
+### A5. Optional independent SDK check
+
+From `robinhood/sdk`:
+
+```bash
+npm run example:verify
+# or
+npx tsx examples/verify-commitment.ts <txHash>
+```
+
+This uses the same settlement pins and can `eth_call` `commitments(digest)`.
+
+## Procedure B — Operator write verification (keys required)
+
+1. Enable writes on a **non-public** or tightly controlled instance first.
+2. Call `veya_hash_blake3` to produce a 32-byte digest.
+3. Call `veya_store_commitment` with Bearer auth and a registered environment UUID.
+4. Call `veya_verify_transaction` on the returned `txHash`.
+5. Optionally re-check with SDK `verifyCommitmentOnChain`.
+
+If Bearer is wrong, the tool must fail. If keys are unset, write tools must not be available as an open surface.
+
+## What verification does not prove
+
+* That sealed-node AES ciphertext for some other workload is correct (different component).
+* That product API guest JWT auth is correct (different component).
+* That mainnet exists for VEYA (it is not claimed).
+
+## Evidence pack for diligence
+
+| Artifact | Source |
+|----------|--------|
+| `/health` JSON | curl |
+| `veya_describe` JSON | MCP client |
+| Explorer tx link | tool `explorer` field |
+| SDK verify output | `npm run example:verify` |
+| Package version | `package.json` / health `version` |

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@veyanet/mcp",
+  "version": "1.0.0",
+  "description": "VEYA MCP - Streamable HTTP Model Context Protocol for Robinhood Chain (testnet 46630)",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veyanet/veya-mcp.git"
+  },
+  "homepage": "https://mcp.veyanet.tech/mcp",
+  "bugs": {
+    "url": "https://github.com/veyanet/veya-mcp/issues"
+  },
+  "bin": {
+    "veya-mcp": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "assets",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx watch src/cli.ts",
+    "start": "node dist/cli.js",
+    "lint": "tsc --noEmit",
+    "test": "tsx --test src/**/*.test.ts",
+    "smoke": "tsx scripts/smoke.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@veyanet/sdk": "^1.2.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.15.29",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "veya",
+    "mcp",
+    "model-context-protocol",
+    "robinhood-chain",
+    "streamable-http"
+  ]
+}

package/src/auth.ts

@@ -0,0 +1,24 @@
+import type { Request } from "express";
+import type { McpServiceConfig } from "./config.js";
+
+export function extractBearer(req: Request): string | null {
+  const h = req.header("authorization") || req.header("Authorization");
+  if (!h) return null;
+  const m = /^Bearer\s+(.+)$/i.exec(h.trim());
+  return m?.[1]?.trim() || null;
+}
+
+/** Write tools require MCP_API_KEY match. Fail closed if key unset. */
+export function assertWriteAuthorized(cfg: McpServiceConfig, bearer: string | null): void {
+  if (!cfg.mcpApiKey) {
+    throw new Error(
+      "Write tools disabled on this server (set MCP_API_KEY + VEYA_RELAYER_PRIVATE_KEY)",
+    );
+  }
+  if (!bearer || bearer !== cfg.mcpApiKey) {
+    throw new Error("Unauthorized: provide Authorization: Bearer <MCP_API_KEY>");
+  }
+  if (!cfg.relayerPrivateKey) {
+    throw new Error("Write tools disabled: VEYA_RELAYER_PRIVATE_KEY not configured");
+  }
+}

package/src/cli.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { startHttpServer } from "./http.js";
+import { loadConfig } from "./config.js";
+
+const cfg = loadConfig();
+startHttpServer(cfg);

package/src/config.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { loadConfig, writesEnabled, MCP_SERVICE_NAME } from "./config.js";
+import { createHttpApp } from "./http.js";
+
+describe("veyanet mcp config", () => {
+  it("defaults to testnet 46630", () => {
+    delete process.env.ROBINHOOD_CHAIN_ID;
+    const cfg = loadConfig();
+    assert.equal(cfg.chainId, 46630);
+    assert.match(cfg.contractAddress, /^0x1a1D/i);
+  });
+
+  it("writes disabled without keys", () => {
+    delete process.env.MCP_API_KEY;
+    delete process.env.VEYA_RELAYER_PRIVATE_KEY;
+    delete process.env.VEYA_DEPLOYER_PRIVATE_KEY;
+    const cfg = loadConfig();
+    assert.equal(writesEnabled(cfg), false);
+  });
+});
+
+describe("veyanet mcp http", () => {
+  it("GET /health returns honesty fields", async () => {
+    const cfg = loadConfig();
+    cfg.port = 0;
+    const app = createHttpApp(cfg);
+    const server = app.listen(0);
+    try {
+      const addr = server.address();
+      assert.ok(addr && typeof addr === "object");
+      const res = await fetch(`http://127.0.0.1:${addr.port}/health`);
+      assert.equal(res.status, 200);
+      const body = (await res.json()) as Record<string, unknown>;
+      assert.equal(body.service, MCP_SERVICE_NAME);
+      assert.equal(body.chainId, 46630);
+      assert.match(String(body.sealed), /AES-256-GCM/);
+    } finally {
+      await new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      );
+    }
+  });
+});

package/src/config.ts

@@ -0,0 +1,49 @@
+export type McpServiceConfig = {
+  port: number;
+  host: string;
+  publicMcpUrl: string;
+  chainId: number;
+  rpcUrl: string;
+  explorerUrl: string;
+  contractAddress: string;
+  apiUrl: string;
+  mcpApiKey: string | null;
+  relayerPrivateKey: string | null;
+  corsOrigins: string[];
+  nodeEnv: string;
+};
+
+export const MCP_SERVICE_NAME = "@veyanet/mcp";
+export const MCP_SERVICE_VERSION = "1.0.0";
+
+export function loadConfig(): McpServiceConfig {
+  const mcpApiKey = process.env.MCP_API_KEY?.trim() || null;
+  const relayer =
+    process.env.VEYA_RELAYER_PRIVATE_KEY?.trim() ||
+    process.env.VEYA_DEPLOYER_PRIVATE_KEY?.trim() ||
+    null;
+
+  return {
+    port: Number(process.env.PORT || 8788),
+    host: process.env.HOST || "0.0.0.0",
+    publicMcpUrl: (process.env.PUBLIC_MCP_URL || "https://mcp.veyanet.tech/mcp").replace(/\/$/, ""),
+    chainId: Number(process.env.ROBINHOOD_CHAIN_ID || 46630),
+    rpcUrl: process.env.ROBINHOOD_RPC_URL || "https://rpc.testnet.chain.robinhood.com",
+    explorerUrl:
+      process.env.ROBINHOOD_EXPLORER_URL || "https://explorer.testnet.chain.robinhood.com",
+    contractAddress:
+      process.env.VEYA_CONTRACT_ADDRESS || "0x1a1Dc3c55550FCE9F70ef6cDEeF967c0b72a5d84",
+    apiUrl: (process.env.VEYA_API_URL || "https://api.veyanet.tech").replace(/\/$/, ""),
+    mcpApiKey,
+    relayerPrivateKey: relayer,
+    corsOrigins: (process.env.CORS_ORIGIN || "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+    nodeEnv: process.env.NODE_ENV || "development",
+  };
+}
+
+export function writesEnabled(cfg: McpServiceConfig): boolean {
+  return Boolean(cfg.mcpApiKey && cfg.relayerPrivateKey);
+}

package/src/http.ts

@@ -0,0 +1,143 @@
+import express, { type Request, type Response } from "express";
+import cors from "cors";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import {
+  loadConfig,
+  writesEnabled,
+  MCP_SERVICE_NAME,
+  MCP_SERVICE_VERSION,
+  type McpServiceConfig,
+} from "./config.js";
+import { extractBearer } from "./auth.js";
+import { createMcpServer, requestAuth } from "./server.js";
+
+export function createHttpApp(cfg: McpServiceConfig = loadConfig()) {
+  const app = express();
+  app.use(express.json({ limit: "1mb" }));
+
+  app.use(
+    cors({
+      origin(origin, cb) {
+        if (!origin) return cb(null, true);
+        if (cfg.corsOrigins.length === 0) return cb(null, false);
+        if (cfg.corsOrigins.includes(origin)) return cb(null, true);
+        return cb(null, false);
+      },
+      credentials: true,
+    }),
+  );
+
+  app.get("/health", (_req, res) => {
+    res.json({
+      status: "ok",
+      service: MCP_SERVICE_NAME,
+      version: MCP_SERVICE_VERSION,
+      publicMcpUrl: cfg.publicMcpUrl,
+      chainId: cfg.chainId,
+      contractAddress: cfg.contractAddress,
+      writesEnabled: writesEnabled(cfg),
+      sealed: "AES-256-GCM (not FHE)",
+      settlement: "Robinhood Chain testnet 46630",
+    });
+  });
+
+  // Stateless Streamable HTTP — paste URL into Claude / Cursor (POST /mcp)
+  app.post("/mcp", async (req: Request, res: Response) => {
+    const bearer = extractBearer(req);
+    await requestAuth.run({ bearer }, async () => {
+      try {
+        const server = createMcpServer(cfg);
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        res.on("close", () => {
+          void transport.close();
+          void server.close();
+        });
+      } catch (err) {
+        console.error("[veyanet/mcp] POST /mcp", err);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: "Internal server error" },
+            id: null,
+          });
+        }
+      }
+    });
+  });
+
+  // Optional stateful path for clients that send MCP-Session-Id
+  const sessions = new Map<string, StreamableHTTPServerTransport>();
+
+  app.post("/mcp/session", async (req: Request, res: Response) => {
+    const bearer = extractBearer(req);
+    await requestAuth.run({ bearer }, async () => {
+      try {
+        const sessionId = req.header("mcp-session-id") || undefined;
+        if (sessionId && sessions.has(sessionId)) {
+          await sessions.get(sessionId)!.handleRequest(req, res, req.body);
+          return;
+        }
+        if (!sessionId && isInitializeRequest(req.body)) {
+          const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+              sessions.set(id, transport);
+            },
+          });
+          transport.onclose = () => {
+            if (transport.sessionId) sessions.delete(transport.sessionId);
+          };
+          const server = createMcpServer(cfg);
+          await server.connect(transport);
+          await transport.handleRequest(req, res, req.body);
+          return;
+        }
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "No valid MCP session" },
+          id: null,
+        });
+      } catch (err) {
+        console.error("[veyanet/mcp] POST /mcp/session", err);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: "Internal server error" },
+            id: null,
+          });
+        }
+      }
+    });
+  });
+
+  app.get("/", (_req, res) => {
+    res.type("html").send(`<!doctype html>
+<html><head><meta charset="utf-8"/><title>VEYA MCP</title></head>
+<body style="font-family:system-ui;max-width:40rem;margin:2rem auto;line-height:1.5">
+  <h1>VEYA MCP</h1>
+  <p>Paste this URL into Claude / Cursor (Streamable HTTP):</p>
+  <pre>${cfg.publicMcpUrl}</pre>
+  <p>Local: <code>POST http://127.0.0.1:${cfg.port}/mcp</code></p>
+  <p>Health: <a href="/health">/health</a></p>
+  <p>Settlement: Robinhood testnet <strong>46630</strong> · Sealed = AES-256-GCM (not FHE) · Not mainnet.</p>
+  <p>Local stdio MCP for operators: <code>veya-anchor/packages/mcp</code></p>
+</body></html>`);
+  });
+
+  return app;
+}
+
+export function startHttpServer(cfg: McpServiceConfig = loadConfig()) {
+  const app = createHttpApp(cfg);
+  return app.listen(cfg.port, cfg.host, () => {
+    console.log(`[veyanet/mcp] listening on http://${cfg.host}:${cfg.port}`);
+    console.log(`[veyanet/mcp] MCP POST ${cfg.publicMcpUrl} (local /mcp)`);
+    console.log(`[veyanet/mcp] writesEnabled=${writesEnabled(cfg)}`);
+  });
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  loadConfig,
+  writesEnabled,
+  MCP_SERVICE_NAME,
+  MCP_SERVICE_VERSION,
+  type McpServiceConfig,
+} from "./config.js";
+export { createMcpServer } from "./server.js";
+export { createHttpApp, startHttpServer } from "./http.js";

package/src/sdk.ts

@@ -0,0 +1,36 @@
+import { VeyaClient } from "@veyanet/sdk";
+import type { McpServiceConfig } from "./config.js";
+
+export function createReadClient(cfg: McpServiceConfig): VeyaClient {
+  return new VeyaClient({
+    rpcUrl: cfg.rpcUrl,
+    contractAddress: cfg.contractAddress,
+    chainId: cfg.chainId,
+    explorerUrl: cfg.explorerUrl,
+  });
+}
+
+export function createWriteClient(cfg: McpServiceConfig): VeyaClient {
+  if (!cfg.relayerPrivateKey) {
+    throw new Error("VEYA_RELAYER_PRIVATE_KEY required for write tools");
+  }
+  return new VeyaClient({
+    rpcUrl: cfg.rpcUrl,
+    contractAddress: cfg.contractAddress,
+    chainId: cfg.chainId,
+    explorerUrl: cfg.explorerUrl,
+    payerPrivateKey: cfg.relayerPrivateKey,
+  });
+}
+
+export function parseHexBytes(value: string, expectedLen?: number): Uint8Array {
+  const hex = value.trim().replace(/^0x/, "");
+  if (!/^[0-9a-fA-F]*$/.test(hex) || hex.length % 2 !== 0) {
+    throw new Error("Expected even-length hex string");
+  }
+  const buf = Buffer.from(hex, "hex");
+  if (expectedLen !== undefined && buf.length !== expectedLen) {
+    throw new Error(`Expected ${expectedLen} bytes, got ${buf.length}`);
+  }
+  return Uint8Array.from(buf);
+}

package/src/server.ts

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  MCP_SERVICE_NAME,
+  MCP_SERVICE_VERSION,
+  type McpServiceConfig,
+} from "./config.js";
+import { registerPublicTools } from "./tools/public.js";
+import { registerWriteTools } from "./tools/write.js";
+
+export const requestAuth = new AsyncLocalStorage<{ bearer: string | null }>();
+
+export function createMcpServer(cfg: McpServiceConfig): McpServer {
+  const server = new McpServer({
+    name: MCP_SERVICE_NAME,
+    version: MCP_SERVICE_VERSION,
+  });
+
+  registerPublicTools(server, cfg);
+  registerWriteTools(server, cfg, () => requestAuth.getStore()?.bearer ?? null);
+
+  return server;
+}