@veyanet/mcp 1.0.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,88 @@
+# Configuration Reference — VEYA MCP
+
+How `@veyanet/mcp` resolves runtime configuration. Source of truth: `src/config.ts`.
+
+## Resolution order
+
+1. Process environment variables (including values loaded from `.env` by your process manager)
+2. Hard-coded Robinhood **testnet** defaults in `loadConfig()`
+
+There is no separate config file format. Operators use `.env` on the host; the repository only ships `.env.example`.
+
+## Variable catalog
+
+### Process bind
+
+| Variable | Type | Default | Notes |
+|----------|------|---------|-------|
+| `PORT` | number | `8788` | nginx should proxy here |
+| `HOST` | string | `0.0.0.0` | use `127.0.0.1` only if nginx is local and you want bind lockdown |
+| `PUBLIC_MCP_URL` | URL | `https://mcp.veyanet.tech/mcp` | Trailing slash stripped; shown on landing + health |
+| `NODE_ENV` | string | `development` | use `production` on the public host |
+
+### Settlement pins
+
+| Variable | Type | Default |
+|----------|------|---------|
+| `ROBINHOOD_NETWORK` | string | documented in `.env.example` as `testnet` (informational) |
+| `ROBINHOOD_CHAIN_ID` | number | `46630` |
+| `ROBINHOOD_RPC_URL` | URL | `https://rpc.testnet.chain.robinhood.com` |
+| `ROBINHOOD_EXPLORER_URL` | URL | `https://explorer.testnet.chain.robinhood.com` |
+| `VEYA_CONTRACT_ADDRESS` | address | `0x1a1Dc3c55550FCE9F70ef6cDEeF967c0b72a5d84` |
+
+### Product API
+
+| Variable | Type | Default |
+|----------|------|---------|
+| `VEYA_API_URL` | URL | `https://api.veyanet.tech` |
+
+Used only by `veya_api_health` (trailing slash stripped).
+
+### Write gate
+
+| Variable | Type | Default |
+|----------|------|---------|
+| `MCP_API_KEY` | string | empty → writes disabled |
+| `VEYA_RELAYER_PRIVATE_KEY` | `0x` hex key | empty → writes disabled |
+| `VEYA_DEPLOYER_PRIVATE_KEY` | `0x` hex key | fallback if relayer unset |
+
+`writesEnabled` is true only when **both** an API key and a payer key resolve.
+
+### CORS
+
+| Variable | Type | Default |
+|----------|------|---------|
+| `CORS_ORIGIN` | comma-separated origins | empty |
+
+Empty allowlist: credentialed browser Origins are rejected. Requests with no `Origin` (typical MCP connectors) still work.
+
+## Derived helpers
+
+```typescript
+import { loadConfig, writesEnabled, MCP_SERVICE_NAME, MCP_SERVICE_VERSION } from "@veyanet/mcp";
+
+const cfg = loadConfig();
+writesEnabled(cfg); // boolean
+```
+
+## Local `.env` hygiene
+
+```bash
+cp .env.example .env
+chmod 600 .env
+# never git add .env
+```
+
+`.gitignore` already excludes `.env`.
+
+## Misconfiguration patterns
+
+| Mistake | Symptom |
+|---------|---------|
+| Wrong chain id alone | Writes fail `CHAIN_MISMATCH`; reads may look “fine” on wrong network data |
+| `PUBLIC_MCP_URL` still localhost in prod | Landing/health advertise wrong paste URL |
+| Write key set without `MCP_API_KEY` | Writes stay disabled |
+| `MCP_API_KEY` set without relayer | Writes stay disabled |
+| Forgetting nginx `Authorization` forward | Bearer never reaches Node; writes always unauthorized |
+
+See also [NETWORK_PIN.md](./NETWORK_PIN.md) and [AUTHENTICATION.md](./AUTHENTICATION.md).

package/docs/DEPLOYMENT.md

@@ -0,0 +1,119 @@
+# Deployment Guide — VEYA MCP
+
+Production target: **`https://mcp.veyanet.tech/mcp`**  
+Package: `@veyanet/mcp` in monorepo directory `robinhood/hosted-mcp/`  
+Stdio sibling (not this service): `veya-anchor/packages/mcp/`
+
+## Architecture on the host
+
+```text
+Internet → TLS (mcp.veyanet.tech) → nginx → 127.0.0.1:8788 → node dist/cli.js
+```
+
+## Build on the server
+
+```bash
+cd /opt/veya/sdk   # or your checkout path for robinhood/sdk
+npm install && npm run build
+
+cd /opt/veya/mcp   # checkout of robinhood/hosted-mcp
+npm install && npm run build
+```
+
+Copy `.env.example` → `.env` and edit secrets **on the server only**.
+
+## Required production env
+
+```bash
+NODE_ENV=production
+HOST=0.0.0.0
+PORT=8788
+PUBLIC_MCP_URL=https://mcp.veyanet.tech/mcp
+ROBINHOOD_CHAIN_ID=46630
+ROBINHOOD_RPC_URL=https://rpc.testnet.chain.robinhood.com
+ROBINHOOD_EXPLORER_URL=https://explorer.testnet.chain.robinhood.com
+VEYA_CONTRACT_ADDRESS=0x1a1Dc3c55550FCE9F70ef6cDEeF967c0b72a5d84
+VEYA_API_URL=https://api.veyanet.tech
+CORS_ORIGIN=https://veyanet.tech,https://www.veyanet.tech,https://app.veyanet.tech
+```
+
+Optional writes:
+
+```bash
+MCP_API_KEY=<long-random-secret>
+VEYA_RELAYER_PRIVATE_KEY=0x...
+```
+
+Leave write vars empty for a public read-only MCP (recommended default until you need agent writes).
+
+## nginx
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name mcp.veyanet.tech;
+    ssl_certificate     /etc/letsencrypt/live/mcp.veyanet.tech/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/mcp.veyanet.tech/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8788;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Authorization $http_authorization;
+        proxy_buffering off;
+    }
+}
+```
+
+**Critical:** forward `Authorization` so Bearer write auth reaches Node. Disable response buffering for Streamable HTTP.
+
+## systemd unit (example)
+
+```ini
+[Unit]
+Description=VEYA MCP
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/opt/veya/mcp
+ExecStart=/usr/bin/node dist/cli.js
+EnvironmentFile=/opt/veya/mcp/.env
+Restart=always
+RestartSec=3
+User=veya
+Group=veya
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now veya-mcp
+sudo systemctl status veya-mcp
+```
+
+## Post-deploy checklist
+
+- [ ] `curl -s https://mcp.veyanet.tech/health` → `status: ok`, `chainId: 46630`
+- [ ] Landing `/` shows paste URL `https://mcp.veyanet.tech/mcp`
+- [ ] Claude / Cursor can connect and call `veya_describe`
+- [ ] `veya_ping_chain` returns 46630
+- [ ] `veya_verify_transaction` works on a known tx
+- [ ] If writes disabled: `/health` has `writesEnabled: false`
+- [ ] If writes enabled: Bearer required; wrong Bearer fails
+- [ ] `.env` not in git; file mode restricted (`chmod 600`)
+
+## Rollback
+
+1. `systemctl stop veya-mcp`
+2. Redeploy previous `dist/` + `.env`
+3. `systemctl start veya-mcp`
+4. Re-run health + `veya_ping_chain`
+
+## Companion docs
+
+* Tree: `robinhood/docs/phase2/MCP.md`
+* Ship board: `robinhood/docs/phase2/SHIP.md` §3b

package/docs/NETWORK_PIN.md

@@ -0,0 +1,51 @@
+# Network Specifications — VEYA MCP
+
+Pinned settlement constants for `@veyanet/mcp`. These match `@veyanet/sdk` defaults so MCP tools and library callers speak the same chain.
+
+## Robinhood Chain testnet
+
+| Constant | Value |
+|----------|-------|
+| Network name | Robinhood Chain Testnet |
+| Chain ID (decimal) | `46630` |
+| Chain ID (hex) | `0xb636` |
+| JSON-RPC | `https://rpc.testnet.chain.robinhood.com` |
+| Explorer | `https://explorer.testnet.chain.robinhood.com` |
+| Protocol contract | `Veya.sol` |
+| Contract address | `0x1a1Dc3c55550FCE9F70ef6cDEeF967c0b72a5d84` |
+
+## Public VEYA endpoints
+
+| Service | URL |
+|---------|-----|
+| MCP (Streamable HTTP) | `https://mcp.veyanet.tech/mcp` |
+| MCP landing | `https://mcp.veyanet.tech/` |
+| MCP health | `https://mcp.veyanet.tech/health` |
+| Product API | `https://api.veyanet.tech` |
+| Product API health | `https://api.veyanet.tech/health` |
+| Marketing site | `https://veyanet.tech` |
+
+## What is not pinned here
+
+| Claim | Status |
+|-------|--------|
+| Mainnet chain id / contract | **Not** a VEYA settlement claim until Phase 3 |
+| ERC-20 / token address | **Never** — `Veya.sol` is not a token |
+| Live FHE / TFHE | **Not** — sealed path is AES-256-GCM; TFHE is a later phase |
+| Loopback validators `7701–7703` | Local ops only; not required for public MCP read tools |
+| Sealed-node `7800` | Local / fleet ops; not this MCP’s default execution surface |
+
+## Changing pins
+
+If you change `ROBINHOOD_CHAIN_ID`, you must also change RPC, explorer, and `VEYA_CONTRACT_ADDRESS` together. SDK write paths call `ensureRobinhoodChain()` and will reject a mismatched `eth_chainId`. Do not advertise a custom pin as “VEYA production” unless the protocol deploy and docs agree.
+
+## Explorer checks
+
+* Contract: `{explorer}/address/{VEYA_CONTRACT_ADDRESS}`
+* Transaction: `{explorer}/tx/{txHash}`
+
+Example commitment transaction used in smoke / docs:
+
+```text
+0xd68ab19671f0a3be63651cb6d6e24f5decf591da981708502827bca3689d31d8
+```

package/docs/QUICKSTART.md

@@ -0,0 +1,111 @@
+# Quickstart Guide — VEYA MCP
+
+This guide takes a stranger from zero to a verified chain ping, then a developer from clone to smoke green. It mirrors the “first success” role of the SDK quickstart, but for Streamable HTTP MCP.
+
+## Part 1 — Stranger (no code, no keys)
+
+### Step 1 — Add the MCP URL
+
+In Claude or Cursor, add a custom MCP connector with **Streamable HTTP** transport:
+
+```text
+https://mcp.veyanet.tech/mcp
+```
+
+### Step 2 — Honesty card
+
+Ask the agent:
+
+> Call `veya_describe` and summarize settlement and sealed claims.
+
+You should see:
+* `@veyanet/mcp`
+* chain id **46630**
+* `Veya.sol` address
+* sealed = **AES-256-GCM** (not FHE)
+* mainnet deferred
+
+### Step 3 — Live chain ping
+
+> Call `veya_ping_chain`.
+
+Confirm `expectedChainId` / chain id is **46630** and a recent block number appears.
+
+### Step 4 — Verify a transaction
+
+> Call `veya_verify_transaction` with tx  
+> `0xd68ab19671f0a3be63651cb6d6e24f5decf591da981708502827bca3689d31d8`
+
+Expect a parsed Veya event (e.g. `CommitmentStored`) and digest hex. Cross-check the hash on the Robinhood testnet explorer.
+
+### Step 5 — Optional API health
+
+> Call `veya_api_health`.
+
+The product API may return `degraded` if validators/sealed are down. That is honest status from `api.veyanet.tech`, not a requirement that MCP itself is broken.
+
+---
+
+## Part 2 — Developer (local)
+
+### Prerequisites
+* Node.js ≥ 20
+* Network access to Robinhood testnet RPC
+
+### Install and run
+
+```bash
+cd robinhood/sdk
+npm install
+npm run build
+
+cd ../hosted-mcp
+npm install
+npm run build
+cp .env.example .env
+npm start
+```
+
+Local paste URL:
+
+```text
+http://127.0.0.1:8788/mcp
+```
+
+```bash
+claude mcp add veya-local --transport http http://127.0.0.1:8788/mcp
+```
+
+### Verify locally
+
+```bash
+npm run lint
+npm test
+npm run smoke
+curl -s http://127.0.0.1:8788/health
+```
+
+Smoke must print `PASS` after `veya_describe` and `veya_ping_chain`.
+
+---
+
+## Part 3 — Operator writes (optional)
+
+Only if you intend authenticated on-chain tools on testnet:
+
+1. Generate a long random `MCP_API_KEY`.
+2. Fund a Robinhood **testnet** key; set `VEYA_RELAYER_PRIVATE_KEY`.
+3. Restart; `/health` must show `"writesEnabled": true`.
+4. Call write tools only with `Authorization: Bearer <MCP_API_KEY>`.
+5. Confirm returned `txHash` on the explorer.
+
+Do not enable writes on a public server without rate limits, key rotation, and a dedicated relayer wallet.
+
+---
+
+## Next reading
+
+* [TOOLS.md](./TOOLS.md) — full argument lists
+* [VERIFICATION.md](./VERIFICATION.md) — audit-grade verify path
+* [DEPLOYMENT.md](./DEPLOYMENT.md) — `mcp.veyanet.tech` TLS
+* [AUTHENTICATION.md](./AUTHENTICATION.md) — Bearer model

package/docs/README.md

@@ -0,0 +1,54 @@
+# VEYA MCP — Documentation Hub
+
+This directory is the documentation set for `@veyanet/mcp`, the Streamable HTTP Model Context Protocol server for VEYA on Robinhood Chain. The root [README.md](../README.md) is the publish-facing entry (same role as `@veyanet/sdk`’s README). Use the table below for depth.
+
+## Reading paths
+
+### Stranger / agent client
+1. [QUICKSTART.md](./QUICKSTART.md) — paste `https://mcp.veyanet.tech/mcp`
+2. [TOOLS.md](./TOOLS.md) — what each `veya_*` tool does
+3. [NETWORK_PIN.md](./NETWORK_PIN.md) — chain id, contract, explorer
+4. [VERIFICATION.md](./VERIFICATION.md) — prove a commitment without trusting UI screenshots
+
+### Operator / deployer
+1. [DEPLOYMENT.md](./DEPLOYMENT.md) — TLS, nginx, systemd, env
+2. [CONFIGURATION.md](./CONFIGURATION.md) — every environment variable
+3. [AUTHENTICATION.md](./AUTHENTICATION.md) — Bearer write gate
+4. [TRANSPORT.md](./TRANSPORT.md) — Streamable HTTP details
+
+### Integrator / security reviewer
+1. [ARCHITECTURE.md](./ARCHITECTURE.md) — trust boundaries
+2. [SDK_BRIDGE.md](./SDK_BRIDGE.md) — what MCP calls in `@veyanet/sdk`
+3. [../SECURITY.md](../SECURITY.md) — disclosure
+
+## Package identity
+
+| Item | Value |
+|------|-------|
+| npm / service name | `@veyanet/mcp` |
+| Monorepo directory | `robinhood/hosted-mcp/` |
+| Public URL | `https://mcp.veyanet.tech/mcp` |
+| Sibling SDK | `robinhood/sdk` (`@veyanet/sdk`) |
+| Stdio MCP (operators) | `veya-anchor/packages/mcp/` |
+
+## Honesty (always)
+
+* Settlement today: Robinhood Chain **testnet** chain id **46630**
+* Protocol contract: `Veya.sol` (not an ERC-20)
+* Sealed execution elsewhere: **AES-256-GCM** (not FHE; not SGX/Nitro product path)
+* Mainnet: Phase 3 — not a current VEYA settlement claim
+
+## Catalog
+
+| Document | Description |
+|----------|-------------|
+| [NETWORK_PIN.md](./NETWORK_PIN.md) | Network constants and pins |
+| [QUICKSTART.md](./QUICKSTART.md) | First connect and first tools |
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | Trust model and component map |
+| [TOOLS.md](./TOOLS.md) | Full tool reference |
+| [VERIFICATION.md](./VERIFICATION.md) | Audit / stranger verify flow |
+| [DEPLOYMENT.md](./DEPLOYMENT.md) | Production deploy for `mcp.veyanet.tech` |
+| [CONFIGURATION.md](./CONFIGURATION.md) | Environment variable reference |
+| [TRANSPORT.md](./TRANSPORT.md) | HTTP / MCP transport |
+| [AUTHENTICATION.md](./AUTHENTICATION.md) | Write auth and key custody |
+| [SDK_BRIDGE.md](./SDK_BRIDGE.md) | SDK methods used by tools |

package/docs/SDK_BRIDGE.md

@@ -0,0 +1,67 @@
+# SDK Bridge — VEYA MCP ↔ `@veyanet/sdk`
+
+This document lists exactly what `@veyanet/mcp` imports from `@veyanet/sdk` and what it deliberately does not re-implement.
+
+## Dependency
+
+```json
+"@veyanet/sdk": "file:../sdk"
+```
+
+Build the SDK before installing MCP:
+
+```bash
+cd ../sdk && npm install && npm run build
+cd ../hosted-mcp && npm install
+```
+
+## Factories (`src/sdk.ts`)
+
+| Helper | SDK usage |
+|--------|-----------|
+| `createReadClient(cfg)` | `new VeyaClient({ rpcUrl, contractAddress, chainId, explorerUrl })` — no payer |
+| `createWriteClient(cfg)` | same + `payerPrivateKey: cfg.relayerPrivateKey` |
+| `parseHexBytes` | local helper (not SDK) for tool hex args |
+
+## Public tools → SDK methods
+
+| MCP tool | SDK call |
+|----------|----------|
+| `veya_describe` | none (config honesty JSON) |
+| `veya_ping_chain` | `client.pingChain()`, `client.describe()` |
+| `veya_hash_blake3` | `client.hashBlake3(data)` |
+| `veya_verify_transaction` | `client.verifyTransaction(txHash)` |
+| `veya_api_health` | `fetch(apiUrl/health)` — not SDK |
+
+## Write tools → SDK methods
+
+| MCP tool | SDK call |
+|----------|----------|
+| `veya_store_commitment` | `client.requireEvm().storeCommitment(uuid16, commitment32)` |
+| `veya_attest_execution` | `client.requireEvm().attestExecution(...)` |
+| `veya_register_environment` | `client.requireEvm().registerEnvironment(...)` |
+
+`EvmAnchor` enforces `ensureRobinhoodChain()` before submit.
+
+## Not exposed via MCP (use SDK or product API)
+
+* `runConsensus` / validator fleet orchestration
+* `protectedExecute` / sealed-node AES session
+* Kyber session establishment
+* In-memory `recordLocalSpend` ledger
+* Full product guest/wallet JWT auth
+* `initSpendingLimit` / `recordSpend` / `flagMemoryNullifier` (backend request path; not currently MCP tools)
+
+If you need those, import `@veyanet/sdk` in your own process or use the product API — do not assume MCP mirrors the entire SDK surface.
+
+## Version alignment
+
+MCP honesty and docs assume SDK **1.2.x** honesty (`SDK_SURFACE`: AES-256-GCM, not FHE, testnet 46630). After upgrading the SDK, re-run:
+
+```bash
+npm run lint && npm test && npm run smoke
+```
+
+## Why a bridge exists
+
+Agents should not embed relayer keys. MCP lets them call read/verify tools over HTTPS. Operators who need full cryptographic control stay on the SDK.

package/docs/TOOLS.md

@@ -0,0 +1,148 @@
+# Tools Reference — VEYA MCP
+
+Complete catalog of MCP tools registered by `@veyanet/mcp`. Argument schemas are enforced with Zod on the server.
+
+---
+
+## Public tools (no Bearer required)
+
+### `veya_describe`
+
+**Purpose:** Honesty card for clients and diligence.
+
+**Args:** none
+
+**Returns (JSON text):** package name/version, `publicUrl`, settlement object (network, chainId, contract, explorer, rpc), product API URL, sealed claim (AES-256-GCM, not FHE), mainnet deferral, write policy string, stdio sibling path.
+
+**When to use:** First call after connecting. Always safe.
+
+---
+
+### `veya_ping_chain`
+
+**Purpose:** Live RPC connectivity and chain id check via `@veyanet/sdk`.
+
+**Args:** none
+
+**Returns:** ping fields including `chainId` (stringified bigint), block metadata, `expectedChainId`, resolved client config summary.
+
+**Failure:** RPC unreachable or chain id mismatch throws / errors in tool result.
+
+---
+
+### `veya_hash_blake3`
+
+**Purpose:** Compute BLAKE3-256 hex digest.
+
+**Args:**
+
+| Name | Type | Constraint |
+|------|------|------------|
+| `data` | string | min length 1 |
+
+**Returns:** `{ "hash": "<64 hex chars>" }`
+
+**Notes:** Commitment helper. Does not write on-chain.
+
+---
+
+### `veya_verify_transaction`
+
+**Purpose:** Parse Veya.sol events from a mined transaction.
+
+**Args:**
+
+| Name | Type | Constraint |
+|------|------|------------|
+| `txHash` | string | min length 66 (0x-prefixed hash) |
+
+**Returns:** Parsed proof object from SDK `verifyTransaction` (event name, digest, explorer URL, etc.) or nullish if no Veya event.
+
+**Notes:** Transaction `to` must be the configured `Veya.sol` address or SDK raises mismatch.
+
+---
+
+### `veya_api_health`
+
+**Purpose:** Probe product API honesty endpoint.
+
+**Args:** none
+
+**Returns:** `{ httpStatus, body }` from `GET {VEYA_API_URL}/health`.
+
+**Notes:** `degraded` on the API is allowed and informative. Does not imply MCP process failure.
+
+---
+
+### `veya_writes_status`
+
+**Purpose:** Explicit “writes off” tool when keys are not configured.
+
+**Args:** none
+
+**Returns:** `{ writesEnabled: false, reason: "..." }`
+
+**Notes:** Not registered when writes are enabled; write tools are registered instead.
+
+---
+
+## Authenticated write tools
+
+**Server requirements:** `MCP_API_KEY` and `VEYA_RELAYER_PRIVATE_KEY` (or `VEYA_DEPLOYER_PRIVATE_KEY`) both set.
+
+**Request requirement:**
+
+```http
+Authorization: Bearer <MCP_API_KEY>
+```
+
+All write tools call `assertWriteAuthorized` then SDK `EvmAnchor` methods (chain id guard on submit).
+
+### `veya_store_commitment`
+
+| Arg | Type | Meaning |
+|-----|------|---------|
+| `environmentUuidHex` | string | 16-byte UUID as hex |
+| `commitmentHex` | string | 32-byte commitment as hex |
+
+**On-chain:** `storeCommitment`  
+**Returns:** `{ txHash, explorer }`
+
+---
+
+### `veya_attest_execution`
+
+| Arg | Type | Meaning |
+|-----|------|---------|
+| `environmentUuidHex` | string | 16-byte env UUID hex |
+| `blake3HashHex` | string | 32-byte execution hash hex |
+| `mldsaSigHex` | string | ML-DSA signature bytes as hex |
+
+**On-chain:** `attestExecution`  
+**Returns:** `{ txHash, explorer }`
+
+---
+
+### `veya_register_environment`
+
+| Arg | Type | Meaning |
+|-----|------|---------|
+| `environmentUuidHex` | string | 16-byte UUID hex |
+| `pqPubkeyHashHex` | string | 32-byte PQ pubkey hash hex |
+| `envType` | number | `0` Execution, `1` SecureEnclave, `2` Governance (Veya.sol enum) |
+
+**On-chain:** `registerEnvironment`  
+**Returns:** `{ txHash, explorer }`
+
+---
+
+## Tool surface vs product API
+
+| Concern | Prefer |
+|---------|--------|
+| Guest Use stamp / UI verify | Product site + `api.veyanet.tech` |
+| Agent paste-URL read/verify | This MCP |
+| Full Build rooms / spend in product | Product API + wallet session |
+| Library integration in your backend | `@veyanet/sdk` directly |
+
+MCP write tools are an operator/agent convenience over the same contract methods; they are not a replacement for product auth (guest JWT / wallet SIWE).