x402 MCP Server

Instructions

Implementation Reference

• src/index.ts:618-640 (handler)

  The implementation of the tool, handling either paid API calls or free test return based on configuration.

  async (params) => {
    const base = APIS.conversion.baseUrl;
    try {
      const usePaid = !!PRIVATE_KEY;
      if (usePaid) {
        const payload: Record<string, unknown> = { type: params.type, url: params.url };
        if (params.format !== undefined) payload.format = params.format;
        if (params.width !== undefined) payload.width = params.width;
        if (params.height !== undefined) payload.height = params.height;
        const data = await apiPost(base, "/convert", payload, true);
        return textResult({ mode: "paid", cost: "$0.02", ...data });
      } else {
        const data = await apiGet(base, "/convert/test");
        return textResult({
          mode: "free_test",
          note: "Free test — returns fixture data. Set X402_PRIVATE_KEY for live conversion.",
          ...data,
        });
      }
    } catch (err: any) {
      return errorResult(err.message);
    }
  }

• src/index.ts:592-641 (registration)

  Registration of the x402_convert_file tool, including its schema and description.

  server.tool(
    "x402_convert_file",
    `Convert files between formats — image resize/reformat, CSV to JSON, HTML to PDF, or DOCX to PDF.
  Price: $0.02 USDC per conversion (paid mode) | Free test: returns fixture data.
  
  Supported conversions:
  - image: resize/reformat an image from a URL (Pillow) — outputs base64-encoded bytes
  - csv: convert a CSV URL to JSON array
  - html_pdf: render HTML from a URL to PDF — outputs base64-encoded bytes
  - docx: convert a DOCX document URL to PDF — outputs base64-encoded bytes (mammoth + WeasyPrint, content-fidelity not layout-preserving)
  
  Input limit: 10MB source file. Output limit: 8MB (before base64 encoding).
  Without X402_PRIVATE_KEY, only the free test endpoint is available.
  
  Returns: base64-encoded output bytes with MIME type, or JSON array for csv type.`,
    {
      url: z.string().url().describe("URL of the file to convert (public, http/https, max 10MB)"),
      type: z.enum(["image", "csv", "html_pdf", "docx"])
        .describe("Conversion type: image (resize/reformat), csv (CSV to JSON), html_pdf (HTML to PDF), docx (DOCX to PDF)"),
      format: z.enum(["jpeg", "png", "webp", "gif"]).optional()
        .describe("Output image format (only for type='image', default: jpeg)"),
      width: z.number().int().min(1).max(8000).optional()
        .describe("Target width in pixels (only for type='image', preserves aspect ratio if height omitted)"),
      height: z.number().int().min(1).max(8000).optional()
        .describe("Target height in pixels (only for type='image', preserves aspect ratio if width omitted)"),
    },
    async (params) => {
      const base = APIS.conversion.baseUrl;
      try {
        const usePaid = !!PRIVATE_KEY;
        if (usePaid) {
          const payload: Record<string, unknown> = { type: params.type, url: params.url };
          if (params.format !== undefined) payload.format = params.format;
          if (params.width !== undefined) payload.width = params.width;
          if (params.height !== undefined) payload.height = params.height;
          const data = await apiPost(base, "/convert", payload, true);
          return textResult({ mode: "paid", cost: "$0.02", ...data });
        } else {
          const data = await apiGet(base, "/convert/test");
          return textResult({
            mode: "free_test",
            note: "Free test — returns fixture data. Set X402_PRIVATE_KEY for live conversion.",
            ...data,
          });
        }
      } catch (err: any) {
        return errorResult(err.message);
      }
    }
  );