cryptopunks-mcp-server

Instructions

Implementation Reference

• src/handlers.ts:219-231 (handler)

  The handler for "get_punk_image_url", which calls the API helper and returns the constructed URL.

  case "get_punk_image_url": {
    const url = api.getPunkImageUrl(args.punk_index, {
      transparent: args.transparent,
      bg: args.bg,
      forSale: args.for_sale_overlay,
      hasBid: args.has_bid_overlay,
    });
    return ok({
      punk_index: args.punk_index,
      image_url: url,
      note: "1024×1024 PNG. Fetch this URL to retrieve the image binary.",
    });
  }

• src/tools.ts:52-66 (schema)

  The schema definition for "get_punk_image_url".

  get_punk_image_url: {
    description:
      "Get the URL for a 1024×1024 PNG image of a specific CryptoPunk. Supports transparent background, custom hex background color, and optional overlays (for-sale, has-bid, transfer indicators). Returns a URL string — fetch it to retrieve the image binary.",
    inputSchema: z.object({
      punk_index: punkIndex,
      transparent: z.boolean().optional().describe("Use transparent background"),
      bg: z
        .string()
        .regex(/^[0-9a-fA-F]{6}$/, "6-digit hex color without #")
        .optional()
        .describe("Background hex color, e.g. FF0000 for red"),
      for_sale_overlay: z.boolean().optional().describe("Add for-sale indicator overlay"),
      has_bid_overlay: z.boolean().optional().describe("Add bid indicator overlay"),
    }),
  },

• src/api.ts:96-113 (helper)

  The implementation of the image URL generator in the API layer.

  export function getPunkImageUrl(
    punkIndex: number,
    options?: {
      transparent?: boolean;
      bg?: string;
      forSale?: boolean;
      hasBid?: boolean;
      transfer?: boolean;
    },
  ): string {
    const url = new URL(`${DATA_BASE}/api/punks/${punkIndex}/image`);
    if (options?.transparent) url.searchParams.set("transparent", "true");
    if (options?.bg) url.searchParams.set("bg", options.bg);
    if (options?.forSale) url.searchParams.set("forSale", "true");
    if (options?.hasBid) url.searchParams.set("hasBid", "true");
    if (options?.transfer) url.searchParams.set("transfer", "true");
    return url.toString();
  }