@celorodrigues/x402-conformance 2.0.0 → 2.1.0

package/README.md

@@ -29,6 +29,30 @@ npx @celorodrigues/x402-conformance https://your-service.com/v1/paid --svg > bad
 
 ---
 
+## 🤖 MCP Server (Claude Desktop, Cursor)
+
+The same package runs as an MCP stdio server:
+
+```json
+{
+  "mcpServers": {
+    "automaton-x402": {
+      "command": "npx",
+      "args": ["-y", "@celorodrigues/x402-conformance", "--mcp"]
+    }
+  }
+}
+```
+
+- Claude Desktop: Settings → Developer → Edit Config (`claude_desktop_config.json`), then restart.
+- Cursor: `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json`.
+
+Tools: `x402_conformance_check` (free, runs locally), `security_scan` (Base token honeypot / mint-trap / contract risk), `oracle_base`, `sentiment_analysis`, `attest`, `merkle_prove`, plus free `verify_attestation`, `read_ledger`, `merkle_verify`, `pricing`, `health`. Paid tools cost 0.001 USDC on Base (3 free calls/day/IP).
+
+Optional env: `VALUE_API_BASE` (default `https://api.automaton-sovereign.workers.dev`), `VALUE_API_PAYMENT` (payment tx hash attached to paid calls).
+
+---
+
 ## 🧪 Battery of Checks
 
 | Code | Level | Check | Requirement |

package/bin/cli.js

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 'use strict';
-const engine = require('../index.js');
-
 const args = process.argv.slice(2);
+
+// MCP stdio server mode: npx -y @celorodrigues/x402-conformance --mcp
+if (args.includes('--mcp')) {
+  require('../mcp-server.js');
+  return;
+}
+
+const engine = require('../index.js');
 const target = args.find(a => !a.startsWith('--'));
 const jsonMode = args.includes('--json');
 const svgMode = args.includes('--svg');
 
 if (!target) {
   console.error('\nUsage: npx @celorodrigues/x402-conformance <endpoint-url> [--json] [--svg]');
+  console.error('       npx -y @celorodrigues/x402-conformance --mcp   (run as an MCP stdio server)');
   console.error('Example: npx @celorodrigues/x402-conformance https://api.myservice.com/v1/paid --json\n');
   process.exit(2);
 }

package/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * x402-conformance  v2.0.0 -- Autonomous x402 Protocol Conformance Linter & Certification Engine
+ * x402-conformance -- Autonomous x402 Protocol Conformance Linter & Certification Engine
  * Conforms strictly to official Coinbase x402 specifications (v1 and v2 CAIP-2) & EIP-3009.
  * Author: Automaton-Sovereign (Base: 0x71DEAc098914A009E3720524642A6bE6F65EE528)
  * 
@@ -23,6 +23,7 @@
 const https = require('https');
 const http = require('http');
 const { URL } = require('url');
+const VERSION = require('./package.json').version;
 
 function fetchUrl(targetUrl, options = {}) {
   return new Promise((resolve, reject) => {
@@ -30,7 +31,7 @@ function fetchUrl(targetUrl, options = {}) {
       const u = new URL(targetUrl);
       const lib = u.protocol === 'http:' ? http : https;
       const headers = Object.assign({
-        'User-Agent': 'Automaton-x402-Conformance-Linter/2.0.0',
+        'User-Agent': 'Automaton-x402-Conformance-Linter/' + VERSION,
         'Accept': 'application/json, text/plain, */*'
       }, options.headers || {});
 
@@ -271,7 +272,7 @@ function finish(results, targetUrl) {
 
   return {
     suite: '@celorodrigues/x402-conformance',
-    version: '2.0.0',
+    version: VERSION,
     target: targetUrl,
     timestamp: new Date().toISOString(),
     verdict: isConformant ? 'CONFORMANT' : 'NON_CONFORMANT',

package/mcp-server.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * Automaton-Sovereign Value API — MCP server (stdio transport, zero deps, JSON-RPC 2.0)
+ *
+ * Exposes the x402-paid Value API as native MCP tools so any MCP-capable agent
+ * can call it directly. Paid tools forward the caller's X-PAYMENT tx hash;
+ * free tools need nothing.
+ *
+ * Also exposes the local x402 conformance linter (index.js) as a free tool.
+ *
+ * Config via env:
+ *   VALUE_API_BASE      base URL of the API (default https://api.automaton-sovereign.workers.dev)
+ *   VALUE_API_PAYMENT   default X-PAYMENT tx hash to attach to paid calls (optional)
+ *
+ * Usage (Claude Desktop / Cursor MCP config):
+ *   { "mcpServers": { "automaton-x402": { "command": "npx",
+ *       "args": ["-y", "@celorodrigues/x402-conformance", "--mcp"] } } }
+ */
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+const PKG = require('./package.json');
+const linter = require('./index.js');
+
+const BASE = (process.env.VALUE_API_BASE || 'https://api.automaton-sovereign.workers.dev').replace(/\/+$/, '');
+const PAYMENT = process.env.VALUE_API_PAYMENT || '';
+
+function httpJson(method, urlStr, headers, body) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(urlStr);
+    const lib = u.protocol === 'http:' ? http : https;
+    const payload = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : null;
+    const h = Object.assign({ 'Accept': 'application/json', 'User-Agent': 'automaton-mcp/1.0' }, headers || {});
+    if (payload) { h['Content-Type'] = 'application/json'; h['Content-Length'] = Buffer.byteLength(payload); }
+    const req = lib.request({ hostname: u.hostname, port: u.port || (u.protocol === 'http:' ? 80 : 443), path: u.pathname + u.search, method, headers: h }, (res) => {
+      let d = ''; res.on('data', c => d += c);
+      res.on('end', () => {
+        let parsed = null; try { parsed = JSON.parse(d); } catch (e) {}
+        resolve({ status: res.statusCode, headers: res.headers, body: parsed !== null ? parsed : d });
+      });
+    });
+    req.on('error', reject); req.setTimeout(30000, () => req.destroy(new Error('timeout')));
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+const TOOLS = [
+  { name: 'x402_conformance_check', description: 'FREE, runs locally. Lint any x402 paid endpoint for protocol conformance: HTTP 402 challenge, x402Version, accepts[] (exact scheme), Base network and addresses, EIP-712 domain, and rejection of malformed, forged, expired, underpaid and wrong-recipient EIP-3009 payments. Returns verdict, grade and per-check results.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'Full URL of the x402-protected endpoint to check.' } }, required: ['url'] } },
+  { name: 'security_scan', description: 'PAID 0.001 USDC/call, or free trial (3/day/IP). Base token safety analysis: honeypot detection, mint traps, selfdestruct/delegatecall, proxy and tax risks from contract bytecode, with a risk score and signed verdict. On 402, pay the accepts[] terms then retry with the payment tx hash.',
+    inputSchema: { type: 'object', properties: { address: { type: 'string', description: 'Token or contract address on Base (0x...).' }, payment: { type: 'string', description: 'Optional X-PAYMENT base tx hash of the USDC payment.' } }, required: ['address'] } },
+  { name: 'attest', description: 'Create a SIGNED, hash-chained, append-only attestation (verifiable proof-of-existence) for a payload. PAID: 0.001 USDC/call, or free trial (3/day/IP). On 402, pay the accepts[] terms then retry with the payment tx hash.',
+    inputSchema: { type: 'object', properties: { data: { type: 'string', description: 'Payload to attest (any string).' }, payment: { type: 'string', description: 'Optional X-PAYMENT base tx hash of the USDC payment.' } }, required: ['data'] } },
+  { name: 'verify_attestation', description: 'FREE. Verify a ledger entry by index or by data hash: recomputes hash, checks ECDSA signature and chain link.',
+    inputSchema: { type: 'object', properties: { index: { type: 'integer' }, dataHash: { type: 'string' } } } },
+  { name: 'attestation_pubkey', description: 'FREE. Get the ECDSA P-256 public key (PEM) and keyId used to sign ledger entries.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'read_ledger', description: 'FREE. Read the attestation ledger (paginated).',
+    inputSchema: { type: 'object', properties: { from: { type: 'integer' }, limit: { type: 'integer' } } } },
+  { name: 'oracle_base', description: 'PAID 0.001 USDC/call. Get real-time Base L2 gas estimates and asset prices (ETH, USDC, cbBTC, AERO, VIRTUAL) with an ECDSA P-256 digital signature from the sovereign agent.',
+    inputSchema: { type: 'object', properties: { payment: { type: 'string', description: 'Optional X-PAYMENT base tx hash of the USDC payment.' } } } },
+  { name: 'merkle_prove', description: 'PAID 0.001 USDC/call. Generate a cryptographic Merkle inclusion proof for a list of items and target element.',
+    inputSchema: { type: 'object', properties: { items: { type: 'array', items: { type: 'string' }, description: 'Array of items' }, target: { type: 'string', description: 'Target item or index' }, payment: { type: 'string' } }, required: ['items'] } },
+  { name: 'merkle_verify', description: 'FREE. Verify a cryptographic Merkle inclusion proof against a root.',
+    inputSchema: { type: 'object', properties: { item: { type: 'string' }, proof: { type: 'array', items: { type: 'object' } }, root: { type: 'string' } }, required: ['item', 'proof', 'root'] } },
+  { name: 'sentiment_analysis', description: 'PAID 0.001 USDC/call. Web3 token risk, security checks, and sentiment scoring with signed verdict.',
+    inputSchema: { type: 'object', properties: { asset: { type: 'string', description: 'Asset symbol (e.g. ETH, AERO, VIRTUAL)' }, payment: { type: 'string' } }, required: ['asset'] } },
+  { name: 'hash_sha256', description: 'PAID 0.001 USDC/call. SHA-256 hex of a string.',
+    inputSchema: { type: 'object', properties: { input: { type: 'string' }, payment: { type: 'string' } }, required: ['input'] } },
+  { name: 'uuid', description: 'PAID 0.001 USDC/call. Generate a UUIDv4.', inputSchema: { type: 'object', properties: { payment: { type: 'string' } } } },
+  { name: 'pricing', description: 'FREE. Full pricing terms, endpoints, and payment mechanics.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'health', description: 'FREE. Service liveness and version.', inputSchema: { type: 'object', properties: {} } }
+];
+
+function q(o) { return Object.entries(o || {}).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => k + '=' + encodeURIComponent(v)).join('&'); }
+
+async function callTool(name, args) {
+  args = args || {};
+  const payHeader = (args.payment || PAYMENT) ? { 'X-PAYMENT': args.payment || PAYMENT } : {};
+  switch (name) {
+    case 'x402_conformance_check': {
+      if (!/^https?:\/\//i.test(args.url || '')) throw new Error('url must be an absolute http(s) URL');
+      return { status: 200, body: await linter.run(args.url) };
+    }
+    case 'security_scan': return httpJson('GET', BASE + '/v2/security/scan?' + q({ address: args.address }), payHeader);
+    case 'attest': return httpJson('POST', BASE + '/v2/attest', payHeader, { data: args.data });
+    case 'verify_attestation': return httpJson('GET', BASE + '/v2/verify?' + q({ index: args.index, dataHash: args.dataHash }));
+    case 'attestation_pubkey': return httpJson('GET', BASE + '/v2/pubkey');
+    case 'read_ledger': return httpJson('GET', BASE + '/v2/ledger?' + q({ from: args.from, limit: args.limit }));
+    case 'oracle_base': return httpJson('GET', BASE + '/v2/oracle/base', payHeader);
+    case 'merkle_prove': return httpJson('POST', BASE + '/v2/merkle/prove', payHeader, { items: args.items, target: args.target });
+    case 'merkle_verify': return httpJson('POST', BASE + '/v2/merkle/verify', {}, { item: args.item, proof: args.proof, root: args.root });
+    case 'sentiment_analysis': return httpJson('GET', BASE + '/v2/sentiment?' + q({ asset: args.asset }), payHeader);
+    case 'hash_sha256': return httpJson('GET', BASE + '/v1/hash?' + q({ input: args.input }), payHeader);
+    case 'uuid': return httpJson('GET', BASE + '/v1/uuid', payHeader);
+    case 'pricing': return httpJson('GET', BASE + '/pricing');
+    case 'health': return httpJson('GET', BASE + '/health');
+    default: throw new Error('unknown tool: ' + name);
+  }
+}
+
+function reply(id, result) { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n'); }
+function replyErr(id, code, message, data) { process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message, data } }) + '\n'); }
+
+let buf = '';
+process.stdin.on('data', (chunk) => {
+  buf += chunk.toString('utf8');
+  let nl;
+  while ((nl = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, nl).trim(); buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg; try { msg = JSON.parse(line); } catch (e) { continue; }
+    if (msg.method === 'initialize') {
+      reply(msg.id, { protocolVersion: '2024-11-05', capabilities: { tools: {} },
+        serverInfo: { name: 'automaton-x402', version: PKG.version } });
+    } else if (msg.method === 'ping') {
+      reply(msg.id, {});
+    } else if (msg.method === 'notifications/initialized') {
+      // no reply
+    } else if (msg.method === 'tools/list') {
+      reply(msg.id, { tools: TOOLS });
+    } else if (msg.method === 'tools/call') {
+      const { name, arguments: a } = msg.params || {};
+      Promise.resolve().then(() => callTool(name, a)).then((r) => {
+        const isClosedError = r.status >= 400;
+        // MCP expects content[]; surface status + body, and mark 402 as error with actionable text
+        const text = typeof r.body === 'string' ? r.body : JSON.stringify(r.body, null, 2);
+        const prefix = isClosedError ? ('HTTP ' + r.status + '\n') : '';
+        reply(msg.id, { content: [{ type: 'text', text: prefix + text }], isError: isClosedError });
+      }).catch((e) => reply(msg.id, { content: [{ type: 'text', text: 'error: ' + e.message }], isError: true }));
+    } else if (msg.id !== undefined) {
+      replyErr(msg.id, -32601, 'method not found: ' + msg.method);
+    }
+  }
+});
+process.stdin.on('end', () => process.exit(0));

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@celorodrigues/x402-conformance",
-  "version": "2.0.0",
-  "description": "Zero-dependency CLI & testing suite for official x402 AI agent micropayment protocol & EIP-3009 compliance",
+  "version": "2.1.0",
+  "description": "Zero-dependency CLI, MCP server and testing suite for x402 AI agent micropayment protocol & EIP-3009 compliance",
   "main": "index.js",
   "bin": {
     "x402-conformance": "bin/cli.js"
   },
   "files": [
     "index.js",
+    "mcp-server.js",
     "bin/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "smithery.yaml"
   ],
   "keywords": [
     "x402",
@@ -21,7 +23,10 @@
     "micropayments",
     "usdc",
     "linter",
-    "conformance"
+    "conformance",
+    "mcp",
+    "model-context-protocol",
+    "claude"
   ],
   "author": "Automaton-Sovereign (0x71DEAc098914A009E3720524642A6bE6F65EE528)",
   "license": "MIT",

package/smithery.yaml

@@ -0,0 +1,26 @@
+# Smithery configuration: https://smithery.ai/docs/config#smitheryyaml
+# MCP stdio server shipped in the npm package (`x402-conformance --mcp`).
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      valueApiBase:
+        type: string
+        default: https://api.automaton-sovereign.workers.dev
+        description: Base URL of the Automaton-Sovereign Value API used by the paid/free API tools.
+      valueApiPayment:
+        type: string
+        description: Optional x402 payment (Base USDC tx hash) attached as X-PAYMENT to paid tool calls.
+  commandFunction:
+    |-
+    (config) => ({
+      command: 'npx',
+      args: ['-y', '@celorodrigues/x402-conformance', '--mcp'],
+      env: Object.assign(
+        { VALUE_API_BASE: config.valueApiBase || 'https://api.automaton-sovereign.workers.dev' },
+        config.valueApiPayment ? { VALUE_API_PAYMENT: config.valueApiPayment } : {}
+      )
+    })
+  exampleConfig:
+    valueApiBase: https://api.automaton-sovereign.workers.dev