CleanPage MCP server

CleanPage

A paid MCP tool that turns any URL into clean, structured, agent-optimized content. Agents pay $0.02 USDC per successful call via x402 on Base — no accounts, no API keys, no subscriptions.

clean_page(url) → { title, clean_markdown, plain_text, structured_facts,
                     metadata, links, images, quality_score, extraction_notes }

Built for Cloudflare Workers. Full TypeScript. No paid infra required beyond a domain and a Base wallet address.

How agents use this

1. Discover the service for free — no payment needed for any of this:

• GET /.well-known/agent.json — machine-readable capability card
• GET /.well-known/mcp.json — MCP connection + pricing manifest
• GET /llms.txt — plain-text summary for LLM crawlers
• MCP tools health, list_capabilities, pricing (all free)

1. Connect an MCP client to https:///mcp over Streamable HTTP:

{
     "mcpServers": {
       "cleanpage": { "url": "https://<your-domain>/mcp", "transport": "streamable-http" }
     }
   }

1. Call cleanpage** with no payment attached first:

POST /mcp
   { "jsonrpc": "2.0", "id": 1, "method": "tools/call",
     "params": { "name": "clean_page", "arguments": { "url": "https://example.com/article" } } }

The response is HTTP 402 with an accepts array describing exactly what payment is required (amount, network, asset, payee address).

1. Sign and retry. Construct a USDC transferWithAuthorization (EIP-3009) payment payload for the requested amount, base64-encode it, and retry the same request with an X-PAYMENT header. Most x402 client libraries (e.g. x402-fetch, x402-axios) do steps 3–4 for you automatically.

1. Get the result. On success, the response carries the full JSON result plus an X-PAYMENT-RESPONSE header with the settlement transaction hash. Failed extractions (paywalls, bot-blocks, empty pages) are never charged — settlement only happens after a successful extraction.

Full protocol details: see /llms.txt and /.well-known/mcp.json once deployed, or the "For agents" section of the landing page.

Project structure

cleanpage/
├── src/
│   ├── index.ts                # Hono app: routes, x402 payment gate, static asset fallback
│   ├── types.ts                # Shared types (Env, CleanPageResult, etc.)
│   ├── config.ts                # Reads env vars into a typed config object
│   ├── mcp/
│   │   ├── server.ts            # JSON-RPC 2.0 / MCP method dispatcher (stateless)
│   │   └── tools.ts             # Tool schemas + descriptions (clean_page, health, ...)
│   ├── extraction/
│   │   ├── extractor.ts         # Core pipeline: fetch → Readability → markdown/links/metadata
│   │   └── enrichment.ts        # Optional cheap LLM pass for structured_facts
│   ├── payments/
│   │   └── x402.ts              # x402 payment requirements, facilitator verify/settle
│   └── middleware/
│       └── limits.ts            # KV-backed rate limiting + call/revenue analytics
├── public/                       # Static assets served at the Worker's root
│   ├── index.html                # Landing page (live demo, pricing, docs, for-agents)
│   ├── robots.txt                 # Explicitly welcomes agent/LLM crawlers
│   ├── llms.txt                   # Plain-text agent-facing summary
│   └── .well-known/
│       ├─

Architecture notes

Shortened. The full README is on GitHub.