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..e4dfed6 --- /dev/null +++ b/src/mcp.ts @@ -0,0 +1,111 @@ +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"; +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; +} + +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 ae093b2..06abc85 100644 --- a/src/server.ts +++ b/src/server.ts @@ -1,4 +1,5 @@ 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"; @@ -7,6 +8,7 @@ import { BUILDER_CODE, builderCodeResourceServerExtension, declareBuilderCodeExt import { isAddress, isHash } from "viem"; import { checkX402Endpoint, CheckInputError, type CheckRequest } from "./assurance.js"; import { loadConfig } from "./config.js"; +import { handleMeterMcpRequest } from "./mcp.js"; import { renderHomePage } from "./page.js"; import { verifyBaseSettlement } from "./proof.js"; import { getBaseSnapshot } from "./snapshot.js"; @@ -16,10 +18,14 @@ 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, (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 new file mode 100644 index 0000000..19c896d --- /dev/null +++ b/test/mcp.test.ts @@ -0,0 +1,52 @@ +import express from "express"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"; +import type { Server } from "node:http"; +import { describe, expect, it, vi } from "vitest"; +import { handleMeterMcpRequest } 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 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" }); + 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", + }, + }); + + 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())); + } + }); +});