run402

Instructions

Implementation Reference

• src/tools/generate-image.ts:15-77 (handler)

  Main handler function that implements the generate_image tool. Calls the API endpoint /v1/generate-image, handles 402 payment required responses with x402 payment details, and returns the generated image as base64 data.

  export async function handleGenerateImage(args: {
    prompt: string;
    aspect?: string;
  }): Promise<{
    content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
    isError?: boolean;
  }> {
    const aspect = args.aspect || "square";
  
    const res = await apiRequest("/v1/generate-image", {
      method: "POST",
      body: { prompt: args.prompt, aspect },
    });
  
    if (res.is402) {
      const body = res.body as Record<string, unknown>;
      const lines = [
        `## Payment Required`,
        ``,
        `To generate an image, an x402 payment of **$0.03 USDC** is needed.`,
        ``,
      ];
      if (body.x402) {
        lines.push(`**Payment details:**`);
        lines.push("```json");
        lines.push(JSON.stringify(body.x402, null, 2));
        lines.push("```");
      } else {
        lines.push(`**Server response:**`);
        lines.push("```json");
        lines.push(JSON.stringify(body, null, 2));
        lines.push("```");
      }
      lines.push(``);
      lines.push(
        `The user's wallet or payment agent must send the required amount. ` +
          `Once payment is confirmed, retry this tool call.`,
      );
      return { content: [{ type: "text", text: lines.join("\n") }] };
    }
  
    if (!res.ok) return formatApiError(res, "generating image");
  
    const body = res.body as {
      image: string;
      content_type: string;
      aspect: string;
    };
  
    return {
      content: [
        {
          type: "text",
          text: `Generated ${body.aspect} image (${body.content_type})`,
        },
        {
          type: "image",
          data: body.image,
          mimeType: body.content_type || "image/png",
        },
      ],
    };
  }

• src/tools/generate-image.ts:5-13 (schema)

  Input schema definition for generate_image tool using Zod. Defines 'prompt' (string, max 1000 chars) and 'aspect' (enum: square/landscape/portrait, defaults to square).

  export const generateImageSchema = {
    prompt: z
      .string()
      .describe("Image description. Max 1000 characters."),
    aspect: z
      .enum(["square", "landscape", "portrait"])
      .default("square")
      .describe("Aspect ratio: square (1:1), landscape (16:9), portrait (9:16)"),
  };

• src/index.ts:335-340 (registration)

  Registration of the generate_image tool with the MCP server. Specifies tool name, description mentioning $0.03 USDC cost, schema, and handler function.

  server.tool(
    "generate_image",
    "Generate a PNG image from a text prompt. Costs $0.03 USDC via x402. Aspect ratios: square (1:1), landscape (16:9), portrait (9:16).",
    generateImageSchema,
    async (args) => handleGenerateImage(args),
  );