x402 MCP Server

Instructions

Implementation Reference

• src/index.ts:240-315 (handler)

  The handler for 'x402_screenshot' which implements the MCP tool registration, schema definition, and the logic to call the screenshot API (with optional X402 payment handling).

  // ─── Tool: x402_screenshot ──────────────────────────────────────────────────
  
  server.tool(
    "x402_screenshot",
    `Capture a screenshot of any URL and return it as a base64-encoded image.
  Price: $0.01 USDC per capture (paid mode) | Free test: example.com, example.org, httpbin.org only.
  
  Without X402_PRIVATE_KEY, only test domains are available.
  With a wallet key, any URL can be captured via the paid endpoint.
  
  Returns: base64 PNG/JPEG/WebP image data.`,
    {
      url: z.string().url().describe("URL to capture (full URL including https://)"),
      width: z
        .number()
        .int()
        .min(320)
        .max(3840)
        .default(1280)
        .describe("Viewport width in pixels (default: 1280)"),
      height: z
        .number()
        .int()
        .min(240)
        .max(2160)
        .default(720)
        .describe("Viewport height in pixels (default: 720)"),
      full_page: z
        .boolean()
        .default(false)
        .describe("Capture the full scrollable page (default: false)"),
      format: z
        .enum(["png", "jpeg", "webp"])
        .default("png")
        .describe("Image format (default: png)"),
    },
    async (params) => {
      const base = APIS.screenshot.baseUrl;
  
      try {
        const usePaid = !!PRIVATE_KEY;
        const query = new URLSearchParams({
          url: params.url,
          width: String(params.width),
          height: String(params.height),
          full_page: String(params.full_page),
          format: params.format,
        });
  
        if (usePaid) {
          // x402 paid mode — GET /screenshot returns 402, x402-fetch handles payment
          const data = await apiGet(base, `/screenshot?${query}`, true);
          return textResult({
            mode: "paid",
            cost: "$0.01",
            ...data,
          });
        } else {
          // Free test mode — limited to example.com, example.org, httpbin.org
          const testQuery = new URLSearchParams({
            url: params.url,
            width: String(params.width),
            height: String(params.height),
          });
          const data = await apiGet(base, `/test/screenshot?${testQuery}`);
          return textResult({
            mode: "free_test",
            note: "Free test — limited to example.com, example.org, httpbin.org. Set X402_PRIVATE_KEY for any URL.",
            ...data,
          });
        }
      } catch (err: any) {
        return errorResult(err.message);
      }
    }
  );