@crawlpay/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# @crawlpay/mcp-server
+
+CrawlPay MCP server for Claude Desktop, Cursor, Windsurf.
+
+Automatically pays $0.001 USDC per page when an AI agent 
+encounters a CrawlPay-protected paywall.
+
+## Setup
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "crawlpay-server": {
+      "command": "npx",
+      "args": ["-y", "@crawlpay/mcp-server"],
+      "env": {
+        "CRAWLPAY_API_KEY": "cr_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+Config file location:
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+## Get API key
+
+1. Go to crawl-pay.com/connect/api-keys
+2. Sign in with Google or GitHub
+3. Fund your wallet with USDC on Base
+4. Generate API key
+5. Paste it into config above
+
+## Tool
+
+`handle_payment_required`
+- url: URL that returned 402
+- amount: USDC amount (default "0.001")
+
+## How it works
+
+```
+Agent reads a CrawlPay-protected page
+→ Gets HTTP 402 Payment Required
+→ MCP server intercepts
+→ Pays $0.001 USDC on Base automatically
+→ Content unlocked
+```
+
+## Links
+
+- [crawl-pay.com](https://crawl-pay.com)
+- [github.com/divergenttt/CrawlPay-Vault](https://github.com/divergenttt/CrawlPay-Vault)
+- npm: coming soon
+
+*Built on Base · Circle · Privy*

package/crawlpay.md

@@ -0,0 +1,31 @@
+# CrawlPay Plugin
+
+## Description
+CrawlPay enables AI agents to automatically pay for paywalled web content 
+using USDC on Base. When an agent encounters HTTP 402 Payment Required, 
+this plugin handles the payment flow automatically.
+
+## Tools
+
+### handle_payment_required
+Handles HTTP 402 responses from CrawlPay-protected pages.
+
+**When to use:** Call this tool whenever you receive a 402 Payment Required 
+error while trying to read a webpage. The site is protected by CrawlPay 
+and requires $0.001 USDC payment per page.
+
+**Inputs:**
+- url: The URL that returned 402
+- amount: Payment amount in USDC (usually "0.001")
+
+**Flow:**
+1. If CRAWLPAY_API_KEY is set: pays automatically via API key, returns content
+2. If no API key: returns Base MCP approval link for manual payment
+
+## Setup
+Set CRAWLPAY_API_KEY=cr_live_... in your environment for automatic payments.
+Get your API key at https://crawl-pay.com/connect/api-keys
+
+## Example
+User: "Read this article: example.com/premium/article"
+Agent: fetches URL → gets 402 → calls handle_payment_required → pays → returns content

package/dist/crawlpay-fetch.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveCrawlPayApiKey(): string | undefined;
+export declare function buildAgentHeaders(base?: Record<string, string>): Record<string, string>;
+export declare function fetchPaidPage(url: string): Promise<Response>;

package/dist/crawlpay-fetch.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCrawlPayApiKey = resolveCrawlPayApiKey;
+exports.buildAgentHeaders = buildAgentHeaders;
+exports.fetchPaidPage = fetchPaidPage;
+function resolveCrawlPayApiKey() {
+    const key = process.env.CRAWLPAY_API_KEY?.trim() ||
+        process.env.CRAWLPAY_AGENT_API_KEY?.trim();
+    return key?.startsWith("cr_live_") ? key : undefined;
+}
+function buildAgentHeaders(base = {}) {
+    const headers = {
+        "User-Agent": process.env.CRAWLPAY_BOT_USER_AGENT ??
+            "GPTBot (CrawlPay-MCP/1.0)",
+        ...base,
+    };
+    const apiKey = resolveCrawlPayApiKey();
+    if (apiKey) {
+        headers.Authorization = `Bearer ${apiKey}`;
+    }
+    return headers;
+}
+async function fetchPaidPage(url) {
+    const apiKey = resolveCrawlPayApiKey();
+    const first = await fetch(url, {
+        headers: buildAgentHeaders(),
+        cache: "no-store",
+    });
+    if (apiKey || first.status !== 402) {
+        return first;
+    }
+    const botAddress = process.env.NEXT_PUBLIC_SELLER_ADDRESS?.trim() ?? "";
+    return fetch(url, {
+        headers: {
+            ...buildAgentHeaders(),
+            "payment-signature": "0xsimulated",
+            "payment-bot-address": botAddress,
+            ...(first.headers.get("x-crawlpay-vault")
+                ? { "x-crawlpay-vault": first.headers.get("x-crawlpay-vault") }
+                : {}),
+        },
+        cache: "no-store",
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const viem_1 = require("viem");
+const crawlpay_fetch_1 = require("./crawlpay-fetch");
+const TOOL_NAME = "handle_payment_required";
+const server = new index_js_1.Server({
+    name: "crawlpay-server",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+const SELLER_ADDRESS = process.env.NEXT_PUBLIC_SELLER_ADDRESS?.trim() ||
+    process.env.SELLER_ADDRESS?.trim() ||
+    "0x80B6173DD42a787BbFF2B2617652885a3dE9b05B"; // CrawlPay default
+/** Base App deep link — triggers USDC transfer via wallet_sendCalls flow. */
+function buildApprovalLink(amount) {
+    const params = new URLSearchParams({
+        to: SELLER_ADDRESS,
+        amount,
+        token: "USDC",
+        chainId: "8453",
+    });
+    return `https://www.base.org/send?${params.toString()}`;
+}
+function validateArgs(args) {
+    if (!args || typeof args !== "object") {
+        throw new Error("Invalid arguments: object expected");
+    }
+    const { url, amount } = args;
+    if (typeof url !== "string" || url.trim().length === 0) {
+        throw new Error("Invalid arguments: `url` must be a non-empty string");
+    }
+    if (typeof amount !== "string" || amount.trim().length === 0) {
+        throw new Error("Invalid arguments: `amount` must be a non-empty string");
+    }
+    // Validate numeric amount format in USDC precision.
+    (0, viem_1.parseUnits)(amount, 6);
+    return { url: url.trim(), amount: amount.trim() };
+}
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    console.error("[crawlpay-mcp] Listing tools");
+    return {
+        tools: [
+            {
+                name: TOOL_NAME,
+                description: "Handle HTTP 402 Payment Required from CrawlPay-protected pages. " +
+                    "Call when a webpage returns 402 — pays automatically if CRAWLPAY_API_KEY is set, " +
+                    "otherwise returns a Base App USDC approval link.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        url: {
+                            type: "string",
+                            description: "URL of the protected page/resource that returned 402",
+                        },
+                        amount: {
+                            type: "string",
+                            description: 'Requested USDC amount (example: "0.001")',
+                        },
+                    },
+                    required: ["url", "amount"],
+                    additionalProperties: false,
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    console.error(`[crawlpay-mcp] Tool call received: ${name}`);
+    if (name !== TOOL_NAME) {
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    const { url, amount } = validateArgs(args);
+    console.error(`[crawlpay-mcp] 402 context parsed. url=${url} amount=${amount}`);
+    const apiKey = (0, crawlpay_fetch_1.resolveCrawlPayApiKey)();
+    if (apiKey) {
+        console.error("[crawlpay-mcp] Retrying with CrawlPay API key (Base wallet)");
+        const res = await (0, crawlpay_fetch_1.fetchPaidPage)(url);
+        const body = await res.text();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `CrawlPay fetch (${res.status})\n` +
+                        `URL: ${url}\n` +
+                        `Amount: ${amount} USDC\n` +
+                        `Auth: API key (cr_live_…)\n\n` +
+                        body.slice(0, 4000),
+                },
+            ],
+        };
+    }
+    const approvalLink = buildApprovalLink(amount);
+    console.error("[crawlpay-mcp] No API key — returning Base App approval link");
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Payment required — set CRAWLPAY_API_KEY=cr_live_… for automatic Base wallet billing,\n" +
+                    "or approve USDC payment via Base App:\n\n" +
+                    `Protected URL: ${url}\n` +
+                    `Amount: ${amount} USDC\n` +
+                    `Base approval link: ${approvalLink}`,
+            },
+        ],
+    };
+});
+async function main() {
+    console.error("[crawlpay-mcp] Starting stdio server...");
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("[crawlpay-mcp] Server connected on stdio");
+}
+main().catch((error) => {
+    console.error("[crawlpay-mcp] Fatal startup error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crawlpay/mcp-server",
+  "version": "0.1.0",
+  "description": "Official CrawlPay MCP server for payment-required (402) flows",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/divergenttt/CrawlPay-MCP"
+  },
+  "homepage": "https://crawl-pay.com",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "crawlpay-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "crawlpay.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "viem": "^2.50.4"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "crawlpay",
+    "x402",
+    "base",
+    "usdc",
+    "ai-agents"
+  ]
+}