@arcpaylabs/somnia-mcp 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# ArcPay Somnia MCP
+
+Local MCP server for ArcPay Somnia. It exposes safe developer tools for Somnia Testnet deployments, x402 payment gates, invoice IDs, claim hashes, privacy commitments, and repeatable demo paths.
+
+## Install
+
+```bash
+npm install -g @arcpaylabs/somnia-mcp
+```
+
+## Claude Desktop
+
+Add this to your Claude Desktop MCP config:
+
+```json
+{
+  "mcpServers": {
+    "arcpay-somnia": {
+      "command": "arcpay-somnia-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing the config.
+
+## Tools
+
+- `get_deployment`
+- `derive_agent_id`
+- `derive_invoice_id`
+- `derive_claim_hash`
+- `derive_privacy_commitment`
+- `privacy_intent_guide`
+- `invoice_guide`
+- `x402_guide`
+- `demo_path`
+- `smoke_commands`
+
+## Hosted Surfaces
+
+- App: https://arcpay-somnia.vercel.app
+- Docs: https://arcpay-somnia.vercel.app/docs/overview
+- OpenAPI: https://arcpay-somnia.vercel.app/openapi.json
+- llms.txt: https://arcpay-somnia.vercel.app/llms.txt
+- x402: https://x402.20.208.46.195.nip.io
+
+The MCP server does not sign transactions or mutate treasury state. It only returns deterministic IDs, integration guidance, and public deployment metadata.

package/deployment.json

@@ -0,0 +1,22 @@
+{
+  "network": "somnia-testnet",
+  "chainId": 50312,
+  "deployer": "0xB883e76A4f6841E72cAF1C28ba00f78df974f448",
+  "deployedAt": "2026-05-23T07:20:15.023Z",
+  "contracts": {
+    "AgentRegistry": "0x350F8f29a5A10eE4d85642CE3AB72497982ee09D",
+    "TreasuryPolicy": "0x4c0f962e6555399f45C628DC7F77d4cC6171BB2A",
+    "AgentTreasury": "0x9dB9477D068A58154A54d10D1E5711A9E1fD9EA0",
+    "AgentOrderBook": "0x6A07886d465Bd64ED3264F4e824C1dF2884a7B45",
+    "OperatorControls": "0xb7b26AD2cCBf6613A43f2Db4a550eDF1D7dB8b32",
+    "SomniaAgentRiskOracle": "0xA5Ec905B95E5b166EF846849eaB8FDD1dB134D0C",
+    "AgentSpendCardVault": "0x0480E467bA12E33DA163FeA45a20C30133F84B93",
+    "SomniaPrivacyVault": "0x6948a15dED7F6708BD4DfD8c3Ee5314bC5B53D14",
+    "AgentInvoiceBook": "0x643De19f32B1d0c396Cf8B5cD677549c442Fbbf7",
+    "AgentReputationBook": "0xBB9aB7d9e2ad5205F390580119b139bce84C8096"
+  },
+  "somniaAgentPlatform": "0x037Bb9C718F3f7fe5eCBDB0b600D607b52706776",
+  "somniaRiskAgentId": "13174292974160097713",
+  "somUsdToken": "0x02b8316775057e2096471473663d51ceafbe3e3b",
+  "updatedAt": "2026-05-27T15:08:18.032Z"
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@arcpaylabs/somnia-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "MCP server for ArcPay Somnia contracts, x402, privacy intents, invoices, and demo flows.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Henry Sammarfo <jasonneil4040@gmail.com>",
+  "homepage": "https://arcpay-somnia.vercel.app/docs/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArcPayLabs/arcpay-somnia.git",
+    "directory": "apps/mcp"
+  },
+  "bin": {
+    "arcpay-somnia-mcp": "server.mjs"
+  },
+  "files": [
+    "README.md",
+    "server.mjs",
+    "deployment.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node server.mjs",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.2",
+    "ethers": "^6.13.5",
+    "zod": "^3.25.76"
+  },
+  "overrides": {
+    "ws": "^8.20.1"
+  }
+}

package/server.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { id, keccak256, toUtf8Bytes } from "ethers";
+import { z } from "zod";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, "../..");
+const deploymentPath = path.join(root, "deployments", "somnia-testnet.json");
+const packagedDeploymentPath = path.join(__dirname, "deployment.json");
+
+function readDeployment() {
+  const file = fs.existsSync(deploymentPath) ? deploymentPath : packagedDeploymentPath;
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+const server = new McpServer({
+  name: "arcpay-somnia",
+  version: "0.1.0",
+});
+
+server.tool("get_deployment", "Return Somnia testnet contract addresses and network metadata.", {}, async () => ({
+  content: [{ type: "text", text: JSON.stringify(readDeployment(), null, 2) }],
+}));
+
+server.tool("derive_agent_id", "Derive the bytes32 agent id used by AgentRegistry.", {
+  slug: z.string().min(1),
+}, async ({ slug }) => ({
+  content: [{ type: "text", text: id(slug) }],
+}));
+
+server.tool("derive_invoice_id", "Derive the bytes32 invoice id used by AgentInvoiceBook.", {
+  publicId: z.string().min(1),
+}, async ({ publicId }) => ({
+  content: [{ type: "text", text: keccak256(toUtf8Bytes(publicId)) }],
+}));
+
+server.tool("derive_claim_hash", "Derive the on-chain claim-code hash for OperatorControls.", {
+  code: z.string().min(1),
+}, async ({ code }) => ({
+  content: [{ type: "text", text: keccak256(toUtf8Bytes(code)) }],
+}));
+
+server.tool("derive_privacy_commitment", "Derive a Privacy Intent commitment or nullifier from secret text.", {
+  secret: z.string().min(1),
+}, async ({ secret }) => ({
+  content: [{ type: "text", text: keccak256(toUtf8Bytes(secret)) }],
+}));
+
+server.tool("privacy_intent_guide", "Return builder instructions for integrating ArcPay Privacy Intents on Somnia.", {}, async () => {
+  const deployment = readDeployment();
+  return {
+    content: [{
+      type: "text",
+      text: [
+        "ArcPay Privacy Intents for Somnia",
+        `Vault: ${deployment.contracts.SomniaPrivacyVault}`,
+        `SOMUSD: ${deployment.somUsdToken}`,
+        "commitment = keccak256(secret)",
+        "nullifier = keccak256(releaseSecret)",
+        "SOMUSD flow: approve vault, then createTokenIntent(commitment, SOMUSD, amount, encryptedMemoUri).",
+        "STT flow: createNativeIntent(commitment, encryptedMemoUri) with msg.value.",
+        "Release: releaseIntent(commitment, nullifier, recipient).",
+        "Boundary: this hides metadata/recipient during intent phase, not a full shielded pool.",
+      ].join("\n"),
+    }],
+  };
+});
+
+server.tool("invoice_guide", "Return builder instructions for ArcPay STT/SOMUSD invoices on Somnia.", {}, async () => {
+  const deployment = readDeployment();
+  return {
+    content: [{
+      type: "text",
+      text: [
+        "ArcPay Somnia Invoices",
+        `InvoiceBook: ${deployment.contracts.AgentInvoiceBook}`,
+        `SOMUSD: ${deployment.somUsdToken}`,
+        "invoiceId = keccak256(publicInvoiceId)",
+        "Create STT invoice: createInvoice(invoiceId, payerOrZero, address(0), amountWei, metadataUri).",
+        "Create SOMUSD invoice: createInvoice(invoiceId, payerOrZero, SOMUSD, amountBaseUnits, metadataUri).",
+        "Pay STT: payNativeInvoice(invoiceId) with exact msg.value.",
+        "Pay SOMUSD: approve InvoiceBook, then payTokenInvoice(invoiceId).",
+        "Cancel unpaid: issuer calls cancelInvoice(invoiceId).",
+        "Proof: npm run smoke:live includes on-chain invoice settlement.",
+      ].join("\n"),
+    }],
+  };
+});
+
+server.tool("x402_guide", "Return builder instructions for the ArcPay Somnia x402 payment-gated agent server.", {}, async () => {
+  const deployment = readDeployment();
+  return {
+    content: [{
+      type: "text",
+      text: [
+        "ArcPay Somnia x402",
+        `OrderBook: ${deployment.contracts.AgentOrderBook}`,
+        `Registry: ${deployment.contracts.AgentRegistry}`,
+        "Run: npm run x402",
+        "Protected resource: GET /agent/:slug/work",
+        "No order returns HTTP 402 with exact STT payment requirements.",
+        "Pay by calling AgentOrderBook.createOrder(agentId, requestUri) with quoted msg.value.",
+        "Verify: POST /x402/verify with { orderId, agentSlug }.",
+        "Unlock: GET /agent/:slug/work?orderId=... after Fulfilled or Settled.",
+        "Proof: npm run smoke:x402.",
+      ].join("\n"),
+    }],
+  };
+});
+
+server.tool("demo_path", "Return the operator demo path for ArcPay Somnia.", {}, async () => ({
+  content: [{
+    type: "text",
+    text: [
+      "Connect an EVM wallet to Somnia Testnet.",
+      "Register an agent on /agents.",
+      "Set policy and allowlist the agent on /policies.",
+      "Create and settle an escrowed agent order on /orders.",
+      "Create/redeem claim codes and trigger webhook breaker on /operator.",
+      "Request and fulfill risk oracle result on /oracle.",
+      "Create and release encrypted Privacy Intents with nullifiers on /privacy.",
+      "Create, pay, cancel, and sync STT/SOMUSD invoices on /invoices.",
+      "Show /audit and /proofs.",
+    ].join("\n"),
+  }],
+}));
+
+server.tool("smoke_commands", "Return the verification commands operators can run locally and against Somnia testnet.", {}, async () => ({
+  content: [{
+    type: "text",
+    text: [
+      "npm run build:frontend",
+      "npm test",
+      "npm run check:worker",
+      "npm run check:x402",
+      "npm run smoke:auth",
+      "npm run smoke:live",
+      "npm run smoke:x402",
+    ].join("\n"),
+  }],
+}));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);