tollbooth-x402 0.2.0

package/README.md

@@ -0,0 +1,42 @@
+# tollbooth-x402
+
+Free **MCP server** for [x402toll.com](https://x402toll.com) — a toll plaza of **verified,
+pay-per-call calculators for AI agents**. Discover the catalog, run free coarse previews, verify any
+paid response's provenance hash, and learn how to pay. The paid endpoints charge a few cents of USDC
+per call over the **x402** protocol on Base — no account, no API key.
+
+Why agents pay: the answers depend on exact **2026** data (tax brackets, contribution limits, state
+fees) a model can't reliably know, every answer is checked against hand-verified reference values,
+and each ships with a formula trace and a reproducible SHA-256 hash.
+
+## Install
+
+```bash
+npx -y tollbooth-x402
+```
+
+Add to an MCP client (e.g. Claude Desktop / Cursor):
+
+```json
+{
+  "mcpServers": {
+    "tollbooth": { "command": "npx", "args": ["-y", "tollbooth-x402"] }
+  }
+}
+```
+
+## Tools (all free, no wallet)
+
+- **`tollbooth_catalog`** — every endpoint with prices, input schemas, methods, and golden-vector evidence.
+- **`tollbooth_preview`** — a free rounded preview of a tool (paycheck, self-employment tax, capital gains, mortgage affordability, LLC cost, debt plan, impermanent loss).
+- **`tollbooth_verify_hash`** — re-derive a paid response's hash to confirm it wasn't altered.
+- **`tollbooth_how_to_pay`** — the x402 payment flow for the paid endpoints.
+
+Paid calls are made directly against `https://x402toll.com` by an x402-capable wallet/client. Set
+`TOLLBOOTH_URL` to point at a different gateway.
+
+## Categories
+
+Tax & payroll · Crypto & DeFi · Lending · Real estate · Retirement · Business.
+
+MIT licensed. Estimates only — not financial, legal, or tax advice.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "tollbooth-x402",
+  "version": "0.2.0",
+  "description": "Free MCP server for x402toll.com — discover and preview verified pay-per-call calculators (tax, crypto/DeFi, lending, retirement) that AI agents pay for in USDC on Base via x402.",
+  "type": "module",
+  "bin": {
+    "tollbooth-x402": "src/server.js"
+  },
+  "main": "src/server.js",
+  "mcpName": "io.github.solomonblack/tollbooth-x402",
+  "files": ["src", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["mcp", "modelcontextprotocol", "x402", "agent", "agentic-payments", "usdc", "base", "calculator", "tax", "crypto", "defi", "ai-agents"],
+  "homepage": "https://x402toll.com",
+  "repository": { "type": "git", "url": "git+https://github.com/solomonblack/tollbooth-x402.git" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "license": "MIT"
+}

package/src/server.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// tollbooth-x402 — the FREE discovery MCP for the Tollbooth toll plaza (x402toll.com).
+// A thin client: it calls the gateway's free HTTP endpoints (catalog, preview, verify-hash) —
+// it does NOT bundle the calculation engine, so the exact paid math stays server-side. No wallet
+// needed for these tools; the paid endpoints charge USDC per call over x402.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const BASE = (process.env.TOLLBOOTH_URL || 'https://x402toll.com').replace(/\/+$/, '');
+const text = obj => ({ content: [{ type: 'text', text: typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2) }] });
+
+async function api(path, init) {
+  const res = await fetch(BASE + path, { ...init, headers: { 'Content-Type': 'application/json', ...(init?.headers) } });
+  const body = await res.json().catch(() => ({ error: `non-JSON response (${res.status})` }));
+  return { ok: res.ok, status: res.status, body };
+}
+
+const server = new McpServer({ name: 'tollbooth', version: '0.2.0' });
+
+server.registerTool('tollbooth_catalog', {
+  description: 'List every Tollbooth paid endpoint at x402toll.com — verified calculators for tax, crypto/DeFi, lending, real estate, retirement, and business — with x402 prices, input schemas, methods, and golden-vector evidence. Free.',
+  inputSchema: {}
+}, async () => {
+  const { ok, body } = await api('/v1/catalog', { method: 'GET' });
+  return text(ok ? body : { error: 'catalog unavailable', detail: body });
+});
+
+server.registerTool('tollbooth_preview', {
+  description: 'Free coarse preview of a Tollbooth tool (rounded headline figure only; the paid endpoint returns the full verified breakdown). Previewable tools include paycheck, self-employment-tax, capital-gains-tax, mortgage-affordability, llc-cost, debt-plan, impermanent-loss.',
+  inputSchema: {
+    tool: z.string().describe('The tool id, e.g. "paycheck" (see tollbooth_catalog for ids)'),
+    inputs: z.record(z.any()).describe('Tool inputs per the catalog inputSchema')
+  }
+}, async ({ tool, inputs }) => {
+  const { ok, body } = await api(`/v1/preview/${encodeURIComponent(tool)}`, { method: 'POST', body: JSON.stringify(inputs ?? {}) });
+  return text(ok ? body : { error: body.error ?? 'preview failed', status: body });
+});
+
+server.registerTool('tollbooth_verify_hash', {
+  description: 'Free provenance check: re-derives the SHA-256 response hash of a previous Tollbooth paid response from its inputs and reports whether it matches (detects tampering).',
+  inputSchema: {
+    response: z.record(z.any()).describe('The full JSON response from a paid Tollbooth call'),
+    inputs: z.record(z.any()).describe('The exact inputs sent with that call')
+  }
+}, async ({ response, inputs }) => {
+  const { ok, body } = await api('/v1/verify-hash', { method: 'POST', body: JSON.stringify({ response, inputs }) });
+  return text(ok ? body : { error: body.error ?? 'verification failed' });
+});
+
+server.registerTool('tollbooth_how_to_pay', {
+  description: 'How an agent pays a Tollbooth endpoint with x402 (v2) on Base: the 402 flow, the PAYMENT-SIGNATURE header, and client library pointers. Free.',
+  inputSchema: {}
+}, async () => text({
+  gateway: BASE, protocol: 'x402 v2 · USDC on Base (eip155:8453)',
+  flow: [
+    '1. POST the tool inputs (JSON) to the paid endpoint with no payment.',
+    '2. Receive HTTP 402; the PAYMENT-REQUIRED response header is base64 JSON with accepts[] (scheme, network, amount in 6-decimal USDC units, asset, payTo).',
+    '3. Sign a USDC transfer authorization for that amount and retry with the PAYMENT-SIGNATURE header.',
+    '4. Receive 200 with the full verified result + a provenance block (formula, data vintage, reproducible hash); the PAYMENT-RESPONSE header carries the settlement receipt.'
+  ],
+  clients: [
+    'JS/TS: @x402/fetch wrapFetchWithPaymentFromConfig + @x402/evm ExactEvmScheme + a funded Base wallet',
+    'MCP wallet servers let Claude/Cursor agents pay without custom code',
+    'Cloudflare Agents SDK has first-class x402 support'
+  ],
+  note: 'Idempotent: retrying the same signed payment on the same endpoint returns the identical cached response with no second charge.'
+}));
+
+const transport = new StdioServerTransport();
+await server.connect(transport);