From 1c980c6b5462d5ba330676058ac1642b5afb94ea Mon Sep 17 00:00:00 2001 From: Mabolla <133767935+Mabolla@users.noreply.github.com> Date: Thu, 1 Oct 2026 09:46:47 +0300 Subject: [PATCH 1/2] feat: add read-only MCP tools for agents --- README.md | 23 +++ package-lock.json | 382 +++++++++++++++++++++++++++++++++++++--------- package.json | 5 +- src/mcp.ts | 89 +++++++++++ src/server.ts | 19 ++- test/mcp.test.ts | 41 +++++ 6 files changed, 481 insertions(+), 78 deletions(-) create mode 100644 src/mcp.ts create mode 100644 test/mcp.test.ts diff --git a/README.md b/README.md index 1830c51..2de8860 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,29 @@ npm run check -- https://api.example.com/paid-resource --method POST --body '{"q The CLI prints JSON. `FAIL` exits with code 1 and invalid input exits with code 2. `PASS` and `WARN` exit successfully so teams can choose their warning policy. The same workflow is available through `POST /api/check`. Public DNS resolution is checked and private, loopback, link-local, and carrier-grade NAT targets are rejected. +## Agent interface (MCP) + +Base Agent Meter exposes a remote MCP Streamable HTTP endpoint at `/mcp`. It publishes two read-only tools that agents can discover through the MCP protocol: + +| Tool | Purpose | +| --- | --- | +| `check_x402_endpoint` | Inspect a public seller endpoint's x402 v2 challenge, Base USDC terms, Bazaar metadata, Builder Code declaration, and optional pinned expectations. | +| `verify_base_settlement` | Verify an existing Base transaction's successful receipt and USDC transfer, with optional payer and Builder Code checks. | + +Neither tool can create a payment, sign a transaction, or access payer credentials. The endpoint uses stateless Streamable HTTP; there is no MCP session state. Requests to `/mcp` are limited to 30 per minute per client IP. The older JSON endpoints remain available for scripts and CI. Once deployed, connect an MCP client to `https:///mcp`. + +Example tool inputs: + +```json +{"url":"https://seller.example/paid","expectations":{"network":"eip155:8453","payTo":"0xYourExpectedRecipient","amount":"1000"}} +``` + +```json +{"transactionHash":"0x...","expectedPayTo":"0xYourExpectedRecipient","expectedAmount":"1000","expectedPayer":"0xOptionalExpectedPayer"} +``` + +`expectedAmount` is the integer amount in USDC's 6-decimal atomic units. A challenge can declare a Builder Code, but the tool only reports attribution as verified when it observes the configured code in the completed transaction. + ## 2. Live paid canary The canary follows the real buyer path: diff --git a/package-lock.json b/package-lock.json index 5dce610..7834cca 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,6 +9,7 @@ "version": "0.1.0", "dependencies": { "@coinbase/cdp-sdk": "1.54.0", + "@modelcontextprotocol/sdk": "^1.31.0", "@x402/core": "2.20.0", "@x402/evm": "2.20.0", "@x402/express": "2.20.0", @@ -17,8 +18,10 @@ "@x402/svm": "2.20.0", "dotenv": "^16.4.7", "express": "^5.1.0", + "express-rate-limit": "^8.7.0", "ox": "^1.6.2", - "viem": "^2.45.0" + "viem": "^2.45.0", + "zod": "^4.6.5" }, "devDependencies": { "@types/express": "^5.0.3", @@ -101,6 +104,27 @@ "url": "https://paulmillr.com/funding/" } }, + "node_modules/@coinbase/cdp-sdk/node_modules/abitype": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/abitype/-/abitype-1.0.6.tgz", + "integrity": "sha512-MMSqYh4+C/aVqI2RQaWqbvI4Kxo5cQV40WQ4QFtDnNzCkqChm8MuENhElmynZlO0qUy/ObkEUaXtKqYnx1Kp3A==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/wevm" + }, + "peerDependencies": { + "typescript": ">=5.0.4", + "zod": "^3 >=3.22.0" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + }, + "zod": { + "optional": true + } + } + }, "node_modules/@coinbase/cdp-sdk/node_modules/ox": { "version": "0.14.33", "resolved": "https://registry.npmjs.org/ox/-/ox-0.14.33.tgz", @@ -224,6 +248,15 @@ } } }, + "node_modules/@coinbase/cdp-sdk/node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, "node_modules/@esbuild/aix-ppc64": { "version": "0.28.2", "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", @@ -666,6 +699,18 @@ "node": ">=18" } }, + "node_modules/@hono/node-server": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.3.tgz", + "integrity": "sha512-TA//nWMqPhbfdfneACk6t5a9eqbS9lABEPyKn0/xZTah3H3U2XaVg85rJFl0/Fyit0I552YDHgXGVSf3GwqbUw==", + "license": "MIT", + "engines": { + "node": ">=20" + }, + "peerDependencies": { + "hono": "^4" + } + }, "node_modules/@jridgewell/sourcemap-codec": { "version": "1.5.5", "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz", @@ -673,6 +718,46 @@ "dev": true, "license": "MIT" }, + "node_modules/@modelcontextprotocol/sdk": { + "version": "1.31.0", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.31.0.tgz", + "integrity": "sha512-UvTMgnNlnIBO/22ob2RcVGDlcvOslQs8T59+FTGdA0L27a39fdGF/EDETNtDVK4DZGpwomlsYpRdA8UXcVL/pw==", + "license": "MIT", + "dependencies": { + "@hono/node-server": "^1.19.9 || ^2.0.5", + "ajv": "^8.17.1", + "ajv-formats": "^3.0.1", + "content-type": "^1.0.5", + "cors": "^2.8.5", + "cross-spawn": "^7.0.5", + "eventsource": "^3.0.2", + "eventsource-parser": "^3.0.0", + "express": "^5.2.1", + "express-rate-limit": "^8.2.1", + "hono": "^4.11.4", + "jose": "^6.1.3", + "json-schema-typed": "^8.0.2", + "pkce-challenge": "^5.0.0", + "raw-body": "^3.0.0", + "zod": "^3.25 || ^4.0", + "zod-to-json-schema": "^3.25.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@cfworker/json-schema": "^4.1.1", + "zod": "^3.25 || ^4.0" + }, + "peerDependenciesMeta": { + "@cfworker/json-schema": { + "optional": true + }, + "zod": { + "optional": false + } + } + }, "node_modules/@napi-rs/lzma-linux-x64-gnu": { "version": "1.5.1", "resolved": "https://registry.npmjs.org/@napi-rs/lzma-linux-x64-gnu/-/lzma-linux-x64-gnu-1.5.1.tgz", @@ -681,9 +766,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -880,9 +962,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -897,9 +976,6 @@ "arm" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -914,9 +990,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -931,9 +1004,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -948,9 +1018,6 @@ "loong64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -965,9 +1032,6 @@ "loong64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -982,9 +1046,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -999,9 +1060,6 @@ "ppc64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1016,9 +1074,6 @@ "riscv64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1033,9 +1088,6 @@ "riscv64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1050,9 +1102,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1067,9 +1116,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1084,9 +1130,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -2456,6 +2499,15 @@ "zod": "^3.24.2" } }, + "node_modules/@x402/core/node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, "node_modules/@x402/evm": { "version": "2.20.0", "resolved": "https://registry.npmjs.org/@x402/evm/-/evm-2.20.0.tgz", @@ -2617,6 +2669,15 @@ } } }, + "node_modules/@x402/evm/node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, "node_modules/@x402/express": { "version": "2.20.0", "resolved": "https://registry.npmjs.org/@x402/express/-/express-2.20.0.tgz", @@ -2812,6 +2873,15 @@ } } }, + "node_modules/@x402/extensions/node_modules/zod": { + "version": "3.25.76", + "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", + "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, "node_modules/@x402/fetch": { "version": "2.20.0", "resolved": "https://registry.npmjs.org/@x402/fetch/-/fetch-2.20.0.tgz", @@ -2836,27 +2906,6 @@ "@solana/kit": ">=5.1.0" } }, - "node_modules/abitype": { - "version": "1.0.6", - "resolved": "https://registry.npmjs.org/abitype/-/abitype-1.0.6.tgz", - "integrity": "sha512-MMSqYh4+C/aVqI2RQaWqbvI4Kxo5cQV40WQ4QFtDnNzCkqChm8MuENhElmynZlO0qUy/ObkEUaXtKqYnx1Kp3A==", - "license": "MIT", - "funding": { - "url": "https://github.com/sponsors/wevm" - }, - "peerDependencies": { - "typescript": ">=5.0.4", - "zod": "^3 >=3.22.0" - }, - "peerDependenciesMeta": { - "typescript": { - "optional": true - }, - "zod": { - "optional": true - } - } - }, "node_modules/accepts": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz", @@ -2886,6 +2935,23 @@ "url": "https://github.com/sponsors/epoberezkin" } }, + "node_modules/ajv-formats": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz", + "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==", + "license": "MIT", + "dependencies": { + "ajv": "^8.0.0" + }, + "peerDependencies": { + "ajv": "^8.0.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, "node_modules/apg-js": { "version": "4.4.0", "resolved": "https://registry.npmjs.org/apg-js/-/apg-js-4.4.0.tgz", @@ -3140,6 +3206,37 @@ "node": ">=6.6.0" } }, + "node_modules/cors": { + "version": "2.8.6", + "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz", + "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==", + "license": "MIT", + "dependencies": { + "object-assign": "^4", + "vary": "^1" + }, + "engines": { + "node": ">= 0.10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/crypt": { "version": "0.0.2", "resolved": "https://registry.npmjs.org/crypt/-/crypt-0.0.2.tgz", @@ -3360,6 +3457,27 @@ "integrity": "sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==", "license": "MIT" }, + "node_modules/eventsource": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz", + "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==", + "license": "MIT", + "dependencies": { + "eventsource-parser": "^3.0.1" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/eventsource-parser": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.1.1.tgz", + "integrity": "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ==", + "license": "MIT", + "engines": { + "node": ">=18.0.0" + } + }, "node_modules/expect-type": { "version": "1.4.0", "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz", @@ -3413,6 +3531,25 @@ "url": "https://opencollective.com/express" } }, + "node_modules/express-rate-limit": { + "version": "8.7.0", + "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.7.0.tgz", + "integrity": "sha512-hOwV7WOxXfjRpAM1DSJWZDXx3GhplwD8IfwuwvogD8i1Qnkgosw/H45s4ZnFAUHDAhPjlY9hLBvJhKmGMyY26g==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.3", + "ip-address": "^10.2.0" + }, + "engines": { + "node": ">= 16" + }, + "funding": { + "url": "https://github.com/sponsors/express-rate-limit" + }, + "peerDependencies": { + "express": ">= 4.11" + } + }, "node_modules/fast-deep-equal": { "version": "3.1.3", "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", @@ -3661,6 +3798,15 @@ "node": ">= 0.4" } }, + "node_modules/hono": { + "version": "4.13.12", + "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.12.tgz", + "integrity": "sha512-6E2QDAc9Ick9Sq77ZrGS/dk2WUYni91aufTw6LJKpV7w8kW5/GxVUc650FOADOmlwg3K+f7Pun6XlV+pYmW6gw==", + "license": "MIT", + "engines": { + "node": ">=16.9.0" + } + }, "node_modules/http-errors": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", @@ -3703,6 +3849,15 @@ "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", "license": "ISC" }, + "node_modules/ip-address": { + "version": "10.7.2", + "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.2.tgz", + "integrity": "sha512-7H/2gFSIitxc0hG3nOI1glS8QLo/EHBFFLk8vEUjXY/xu0AdL8jZ9U1IzO2PUm0d2D/ofQcAifb0g6OBkt8U7w==", + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, "node_modules/ipaddr.js": { "version": "1.9.1", "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", @@ -3736,6 +3891,12 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, "node_modules/isows": { "version": "1.0.7", "resolved": "https://registry.npmjs.org/isows/-/isows-1.0.7.tgz", @@ -3773,6 +3934,12 @@ "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", "license": "MIT" }, + "node_modules/json-schema-typed": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz", + "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==", + "license": "BSD-2-Clause" + }, "node_modules/loupe": { "version": "3.2.1", "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz", @@ -3894,6 +4061,15 @@ "node": ">= 0.6" } }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/object-inspect": { "version": "1.13.4", "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", @@ -4042,15 +4218,6 @@ } } }, - "node_modules/ox/node_modules/zod": { - "version": "4.4.3", - "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz", - "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", - "license": "MIT", - "funding": { - "url": "https://github.com/sponsors/colinhacks" - } - }, "node_modules/parseurl": { "version": "1.3.3", "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", @@ -4060,6 +4227,15 @@ "node": ">= 0.8" } }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/path-to-regexp": { "version": "8.4.2", "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", @@ -4107,6 +4283,15 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/pkce-challenge": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz", + "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==", + "license": "MIT", + "engines": { + "node": ">=16.20.0" + } + }, "node_modules/postcss": { "version": "8.5.26", "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz", @@ -4330,6 +4515,27 @@ "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", "license": "ISC" }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/side-channel": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.1.tgz", @@ -4925,6 +5131,21 @@ } } }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, "node_modules/why-is-node-running": { "version": "2.3.0", "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz", @@ -4970,13 +5191,22 @@ } }, "node_modules/zod": { - "version": "3.25.76", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", - "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "version": "4.6.5", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.5.tgz", + "integrity": "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q==", "license": "MIT", "funding": { "url": "https://github.com/sponsors/colinhacks" } + }, + "node_modules/zod-to-json-schema": { + "version": "3.25.2", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz", + "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==", + "license": "ISC", + "peerDependencies": { + "zod": "^3.25.28 || ^4" + } } } } diff --git a/package.json b/package.json index 5f326e4..139b3b8 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,7 @@ }, "dependencies": { "@coinbase/cdp-sdk": "1.54.0", + "@modelcontextprotocol/sdk": "^1.31.0", "@x402/core": "2.20.0", "@x402/evm": "2.20.0", "@x402/express": "2.20.0", @@ -23,8 +24,10 @@ "@x402/svm": "2.20.0", "dotenv": "^16.4.7", "express": "^5.1.0", + "express-rate-limit": "^8.7.0", "ox": "^1.6.2", - "viem": "^2.45.0" + "viem": "^2.45.0", + "zod": "^4.6.5" }, "devDependencies": { "@types/express": "^5.0.3", diff --git a/src/mcp.ts b/src/mcp.ts new file mode 100644 index 0000000..738505f --- /dev/null +++ b/src/mcp.ts @@ -0,0 +1,89 @@ +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { isAddress, isHash } from "viem"; +import { z } from "zod"; +import { checkX402Endpoint, type CheckRequest } from "./assurance.js"; +import { verifyBaseSettlement } from "./proof.js"; + +interface McpDependencies { + checkEndpoint?: typeof checkX402Endpoint; + verifySettlement?: typeof verifyBaseSettlement; + rpcUrl: string; + builderCode: string; +} + +function jsonResult(value: unknown) { + return { content: [{ type: "text" as const, text: JSON.stringify(value) }] }; +} + +function errorResult(error: unknown) { + return { + content: [{ type: "text" as const, text: error instanceof Error ? error.message : "The requested check failed." }], + isError: true, + }; +} + +export function createMeterMcpServer(dependencies: McpDependencies) { + const server = new McpServer( + { name: "base-agent-meter", version: "0.2.0" }, + { instructions: "Read-only Base x402 assurance tools. These tools never sign, submit, or pay for transactions." }, + ); + const checkEndpoint = dependencies.checkEndpoint ?? checkX402Endpoint; + const verifySettlement = dependencies.verifySettlement ?? verifyBaseSettlement; + + server.registerTool( + "check_x402_endpoint", + { + title: "Check an x402 endpoint", + description: "Read a public HTTP endpoint and report whether its x402 v2 challenge advertises Base Mainnet USDC, stable payment details, Bazaar metadata, and Builder Code attribution. No payment is made. Private, loopback, link-local, and carrier-grade NAT destinations are rejected.", + inputSchema: { + url: z.string().url(), + method: z.enum(["GET", "POST"]).optional(), + body: z.unknown().optional(), + expectations: z.object({ + network: z.string().optional(), + asset: z.string().optional(), + payTo: z.string().optional(), + amount: z.string().optional(), + }).optional(), + }, + annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true }, + }, + async (input) => { + try { + return jsonResult(await checkEndpoint(input as CheckRequest)); + } catch (error) { + return errorResult(error); + } + }, + ); + + server.registerTool( + "verify_base_settlement", + { + title: "Verify a Base settlement", + description: "Read a Base Mainnet transaction and verify its successful receipt and exact USDC transfer to the expected recipient, amount, and optional payer. Also reports whether the configured Builder Code appears in the transaction calldata. This does not submit or modify transactions.", + inputSchema: { + transactionHash: z.string().refine(isHash, "must be a 32-byte transaction hash"), + expectedPayTo: z.string().refine(isAddress, "must be a valid EVM address"), + expectedAmount: z.string().regex(/^[1-9]\d*$/, "must be a positive atomic-unit amount"), + expectedPayer: z.string().refine(isAddress, "must be a valid EVM address").optional(), + }, + annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, + }, + async (input) => { + try { + return jsonResult({ + verifiedAt: new Date().toISOString(), + proof: await verifySettlement(dependencies.rpcUrl, { + ...input, + declaredBuilderCode: dependencies.builderCode, + }), + }); + } catch (error) { + return errorResult(error); + } + }, + ); + + return server; +} diff --git a/src/server.ts b/src/server.ts index ae093b2..c3831b1 100644 --- a/src/server.ts +++ b/src/server.ts @@ -1,12 +1,15 @@ import express from "express"; +import { rateLimit } from "express-rate-limit"; import { createCdpFacilitatorClient } from "@coinbase/cdp-sdk/x402"; import { ExactEvmScheme } from "@x402/evm/exact/server"; import { paymentMiddleware, x402ResourceServer } from "@x402/express"; import { declareDiscoveryExtension } from "@x402/extensions/bazaar"; import { BUILDER_CODE, builderCodeResourceServerExtension, declareBuilderCodeExtension } from "@x402/extensions/builder-code"; import { isAddress, isHash } from "viem"; +import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; import { checkX402Endpoint, CheckInputError, type CheckRequest } from "./assurance.js"; import { loadConfig } from "./config.js"; +import { createMeterMcpServer } from "./mcp.js"; import { renderHomePage } from "./page.js"; import { verifyBaseSettlement } from "./proof.js"; import { getBaseSnapshot } from "./snapshot.js"; @@ -16,10 +19,24 @@ const app = express(); app.disable("x-powered-by"); app.use(express.json({ limit: "128kb" })); const baseAppId = "6a81d256b92232d481b384bc"; +const mcpLimiter = rateLimit({ windowMs: 60_000, limit: 30, standardHeaders: "draft-8", legacyHeaders: false }); app.get("/", (_req, res) => res.type("html").send(renderHomePage().replace("", `\n `))); app.get("/health", (_req, res) => res.json({ ok: true, service: "base-agent-meter", product: "x402-production-assurance", network: config.network })); -app.get("/api/meta", (_req, res) => res.json({ service: "base-agent-meter", product: "x402-production-assurance", network: config.network, asset: "USDC", workflows: { preDeployCheck: "POST /api/check", settlementProof: "POST /api/proof/verify", paidCanary: "npm run canary -- " }, sellerFixture: { enabled: Boolean(config.payTo && config.cdpConfigured), path: "/api/base-snapshot", builderAttribution: config.payTo ? { status: "declared", code: config.builderCode } : { status: "not_configured" } } })); +app.get("/api/meta", (_req, res) => res.json({ service: "base-agent-meter", product: "x402-production-assurance", network: config.network, asset: "USDC", workflows: { mcp: { transport: "Streamable HTTP", endpoint: "/mcp", tools: ["check_x402_endpoint", "verify_base_settlement"], readOnly: true }, preDeployCheck: "POST /api/check", settlementProof: "POST /api/proof/verify", paidCanary: "npm run canary -- " }, sellerFixture: { enabled: Boolean(config.payTo && config.cdpConfigured), path: "/api/base-snapshot", builderAttribution: config.payTo ? { status: "declared", code: config.builderCode } : { status: "not_configured" } } })); +app.post("/mcp", mcpLimiter, async (req, res) => { + const server = createMeterMcpServer({ rpcUrl: config.rpcUrl, builderCode: config.builderCode }); + const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true }); + try { + await server.connect(transport); + await transport.handleRequest(req, res, req.body); + } catch (error) { + console.error("mcp_request_failed", error); + if (!res.headersSent) res.status(500).json({ error: "mcp_request_failed" }); + await transport.close().catch(() => undefined); + await server.close().catch(() => undefined); + } +}); app.post("/api/check", async (req, res) => { try { const report = await checkX402Endpoint(req.body as CheckRequest); res.status(report.status === "FAIL" ? 422 : 200).json(report); } catch (error) { if (error instanceof CheckInputError || error instanceof SyntaxError) { res.status(400).json({ status: "FAIL", error: "invalid_check_request", message: error.message }); return; } console.error("assurance_check_failed", error); res.status(500).json({ status: "FAIL", error: "assurance_check_failed" }); } }); app.post("/api/proof/verify", async (req, res) => { const { transactionHash, expectedPayer, expectedPayTo, expectedAmount, declaredBuilderCode } = req.body ?? {}; if (!isHash(transactionHash) || !isAddress(expectedPayTo) || typeof expectedAmount !== "string" || !/^\d+$/.test(expectedAmount)) { res.status(400).json({ error: "invalid_proof_request", message: "transactionHash, expectedPayTo, and atomic-unit expectedAmount are required." }); return; } if (expectedPayer !== undefined && !isAddress(expectedPayer)) { res.status(400).json({ error: "invalid_proof_request", message: "expectedPayer must be a valid EVM address when supplied." }); return; } try { res.json({ verifiedAt: new Date().toISOString(), proof: await verifyBaseSettlement(config.rpcUrl, { transactionHash, expectedPayer, expectedPayTo, expectedAmount, declaredBuilderCode }) }); } catch (error) { console.error("settlement_proof_failed", error); res.status(502).json({ error: "base_proof_unavailable", message: error instanceof Error ? error.message : "Base RPC verification failed." }); } }); diff --git a/test/mcp.test.ts b/test/mcp.test.ts new file mode 100644 index 0000000..d68ee29 --- /dev/null +++ b/test/mcp.test.ts @@ -0,0 +1,41 @@ +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; +import { describe, expect, it, vi } from "vitest"; +import { createMeterMcpServer } from "../src/mcp.js"; +import { verifyBaseSettlement } from "../src/proof.js"; + +describe("Base Agent Meter MCP server", () => { + it("publishes read-only assurance tools and verifies a supplied transaction", async () => { + const verifySettlement = vi.fn(async (_rpcUrl: string, input: Parameters[1]) => ({ + network: "eip155:8453", + transactionHash: input.transactionHash, + settlementVerified: true, + builderAttribution: { declared: "bc_h2oqnbbh", verified: true }, + })) as unknown as typeof verifyBaseSettlement; + const server = createMeterMcpServer({ rpcUrl: "https://rpc.example", builderCode: "bc_h2oqnbbh", verifySettlement }); + const client = new Client({ name: "meter-test", version: "1.0.0" }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + + await server.connect(serverTransport); + await client.connect(clientTransport); + const listed = await client.listTools(); + expect(listed.tools.map(tool => tool.name)).toEqual(["check_x402_endpoint", "verify_base_settlement"]); + expect(listed.tools.every(tool => tool.annotations?.readOnlyHint)).toBe(true); + + const result = await client.callTool({ + name: "verify_base_settlement", + arguments: { + transactionHash: `0x${"1".repeat(64)}`, + expectedPayTo: "0x0000000000000000000000000000000000000001", + expectedAmount: "10000", + }, + }); + + expect(result.isError).not.toBe(true); + const resultContent = result.content as Array<{ type: string; text?: string }>; + expect(JSON.parse(resultContent[0].text ?? "{}").proof.settlementVerified).toBe(true); + expect(verifySettlement).toHaveBeenCalledOnce(); + await client.close(); + await server.close(); + }); +}); From be31b966c34fd3493cb18e574f70aeb94cd13af3 Mon Sep 17 00:00:00 2001 From: Mabolla <133767935+Mabolla@users.noreply.github.com> Date: Thu, 1 Oct 2026 11:22:00 +0300 Subject: [PATCH 2/2] test: cover MCP HTTP transport lifecycle --- src/mcp.ts | 22 ++++++++++++++++++ src/server.ts | 17 +++----------- test/mcp.test.ts | 59 ++++++++++++++++++++++++++++-------------------- 3 files changed, 60 insertions(+), 38 deletions(-) diff --git a/src/mcp.ts b/src/mcp.ts index 738505f..e4dfed6 100644 --- a/src/mcp.ts +++ b/src/mcp.ts @@ -1,4 +1,6 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; +import type { IncomingMessage, ServerResponse } from "node:http"; import { isAddress, isHash } from "viem"; import { z } from "zod"; import { checkX402Endpoint, type CheckRequest } from "./assurance.js"; @@ -87,3 +89,23 @@ export function createMeterMcpServer(dependencies: McpDependencies) { return server; } + +export async function handleMeterMcpRequest( + req: IncomingMessage & { body?: unknown }, + res: ServerResponse, + dependencies: McpDependencies, +) { + const server = createMeterMcpServer(dependencies); + const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true }); + try { + await server.connect(transport); + await transport.handleRequest(req, res, req.body); + } catch (error) { + console.error("mcp_request_failed", error); + if (!res.headersSent) res.statusCode = 500; + if (!res.writableEnded) res.end(JSON.stringify({ error: "mcp_request_failed" })); + } finally { + await transport.close().catch(() => undefined); + await server.close().catch(() => undefined); + } +} diff --git a/src/server.ts b/src/server.ts index c3831b1..06abc85 100644 --- a/src/server.ts +++ b/src/server.ts @@ -6,10 +6,9 @@ import { paymentMiddleware, x402ResourceServer } from "@x402/express"; import { declareDiscoveryExtension } from "@x402/extensions/bazaar"; import { BUILDER_CODE, builderCodeResourceServerExtension, declareBuilderCodeExtension } from "@x402/extensions/builder-code"; import { isAddress, isHash } from "viem"; -import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; import { checkX402Endpoint, CheckInputError, type CheckRequest } from "./assurance.js"; import { loadConfig } from "./config.js"; -import { createMeterMcpServer } from "./mcp.js"; +import { handleMeterMcpRequest } from "./mcp.js"; import { renderHomePage } from "./page.js"; import { verifyBaseSettlement } from "./proof.js"; import { getBaseSnapshot } from "./snapshot.js"; @@ -24,18 +23,8 @@ const mcpLimiter = rateLimit({ windowMs: 60_000, limit: 30, standardHeaders: "dr app.get("/", (_req, res) => res.type("html").send(renderHomePage().replace("", `\n `))); app.get("/health", (_req, res) => res.json({ ok: true, service: "base-agent-meter", product: "x402-production-assurance", network: config.network })); app.get("/api/meta", (_req, res) => res.json({ service: "base-agent-meter", product: "x402-production-assurance", network: config.network, asset: "USDC", workflows: { mcp: { transport: "Streamable HTTP", endpoint: "/mcp", tools: ["check_x402_endpoint", "verify_base_settlement"], readOnly: true }, preDeployCheck: "POST /api/check", settlementProof: "POST /api/proof/verify", paidCanary: "npm run canary -- " }, sellerFixture: { enabled: Boolean(config.payTo && config.cdpConfigured), path: "/api/base-snapshot", builderAttribution: config.payTo ? { status: "declared", code: config.builderCode } : { status: "not_configured" } } })); -app.post("/mcp", mcpLimiter, async (req, res) => { - const server = createMeterMcpServer({ rpcUrl: config.rpcUrl, builderCode: config.builderCode }); - const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true }); - try { - await server.connect(transport); - await transport.handleRequest(req, res, req.body); - } catch (error) { - console.error("mcp_request_failed", error); - if (!res.headersSent) res.status(500).json({ error: "mcp_request_failed" }); - await transport.close().catch(() => undefined); - await server.close().catch(() => undefined); - } +app.post("/mcp", mcpLimiter, (req, res) => { + void handleMeterMcpRequest(req, res, { rpcUrl: config.rpcUrl, builderCode: config.builderCode }); }); app.post("/api/check", async (req, res) => { try { const report = await checkX402Endpoint(req.body as CheckRequest); res.status(report.status === "FAIL" ? 422 : 200).json(report); } catch (error) { if (error instanceof CheckInputError || error instanceof SyntaxError) { res.status(400).json({ status: "FAIL", error: "invalid_check_request", message: error.message }); return; } console.error("assurance_check_failed", error); res.status(500).json({ status: "FAIL", error: "assurance_check_failed" }); } }); app.post("/api/proof/verify", async (req, res) => { const { transactionHash, expectedPayer, expectedPayTo, expectedAmount, declaredBuilderCode } = req.body ?? {}; if (!isHash(transactionHash) || !isAddress(expectedPayTo) || typeof expectedAmount !== "string" || !/^\d+$/.test(expectedAmount)) { res.status(400).json({ error: "invalid_proof_request", message: "transactionHash, expectedPayTo, and atomic-unit expectedAmount are required." }); return; } if (expectedPayer !== undefined && !isAddress(expectedPayer)) { res.status(400).json({ error: "invalid_proof_request", message: "expectedPayer must be a valid EVM address when supplied." }); return; } try { res.json({ verifiedAt: new Date().toISOString(), proof: await verifyBaseSettlement(config.rpcUrl, { transactionHash, expectedPayer, expectedPayTo, expectedAmount, declaredBuilderCode }) }); } catch (error) { console.error("settlement_proof_failed", error); res.status(502).json({ error: "base_proof_unavailable", message: error instanceof Error ? error.message : "Base RPC verification failed." }); } }); diff --git a/test/mcp.test.ts b/test/mcp.test.ts index d68ee29..19c896d 100644 --- a/test/mcp.test.ts +++ b/test/mcp.test.ts @@ -1,7 +1,9 @@ +import express from "express"; import { Client } from "@modelcontextprotocol/sdk/client/index.js"; -import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; +import type { Server } from "node:http"; import { describe, expect, it, vi } from "vitest"; -import { createMeterMcpServer } from "../src/mcp.js"; +import { handleMeterMcpRequest } from "../src/mcp.js"; import { verifyBaseSettlement } from "../src/proof.js"; describe("Base Agent Meter MCP server", () => { @@ -12,30 +14,39 @@ describe("Base Agent Meter MCP server", () => { settlementVerified: true, builderAttribution: { declared: "bc_h2oqnbbh", verified: true }, })) as unknown as typeof verifyBaseSettlement; - const server = createMeterMcpServer({ rpcUrl: "https://rpc.example", builderCode: "bc_h2oqnbbh", verifySettlement }); + const app = express(); + app.use(express.json()); + app.post("/mcp", (req, res) => { + void handleMeterMcpRequest(req, res, { rpcUrl: "https://rpc.example", builderCode: "bc_h2oqnbbh", verifySettlement }); + }); + let listener: Server | undefined; + listener = app.listen(0, "127.0.0.1"); + await new Promise(resolve => listener?.once("listening", resolve)); + const address = listener.address(); + if (!address || typeof address === "string") throw new Error("HTTP test server did not bind to a TCP port"); const client = new Client({ name: "meter-test", version: "1.0.0" }); - const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); - - await server.connect(serverTransport); - await client.connect(clientTransport); - const listed = await client.listTools(); - expect(listed.tools.map(tool => tool.name)).toEqual(["check_x402_endpoint", "verify_base_settlement"]); - expect(listed.tools.every(tool => tool.annotations?.readOnlyHint)).toBe(true); + try { + await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${address.port}/mcp`))); + const listed = await client.listTools(); + expect(listed.tools.map(tool => tool.name)).toEqual(["check_x402_endpoint", "verify_base_settlement"]); + expect(listed.tools.every(tool => tool.annotations?.readOnlyHint)).toBe(true); - const result = await client.callTool({ - name: "verify_base_settlement", - arguments: { - transactionHash: `0x${"1".repeat(64)}`, - expectedPayTo: "0x0000000000000000000000000000000000000001", - expectedAmount: "10000", - }, - }); + const result = await client.callTool({ + name: "verify_base_settlement", + arguments: { + transactionHash: `0x${"1".repeat(64)}`, + expectedPayTo: "0x0000000000000000000000000000000000000001", + expectedAmount: "10000", + }, + }); - expect(result.isError).not.toBe(true); - const resultContent = result.content as Array<{ type: string; text?: string }>; - expect(JSON.parse(resultContent[0].text ?? "{}").proof.settlementVerified).toBe(true); - expect(verifySettlement).toHaveBeenCalledOnce(); - await client.close(); - await server.close(); + expect(result.isError).not.toBe(true); + const resultContent = result.content as Array<{ type: string; text?: string }>; + expect(JSON.parse(resultContent[0].text ?? "{}").proof.settlementVerified).toBe(true); + expect(verifySettlement).toHaveBeenCalledOnce(); + } finally { + await client.close(); + await new Promise((resolve, reject) => listener?.close(error => error ? reject(error) : resolve())); + } }); });