QR for Agent

Instructions

Implementation Reference

• packages/mcp/src/tools.ts:9-108 (handler)

  The 'create_qr_code' tool definition and its handler. The handler makes a POST request to '/api/qr' using the provided input data.

  create_qr_code: {
    description:
      "Create a new managed QR code with optional custom styling. The QR code points to a short URL that redirects to your target URL. You can change the target URL later without regenerating the QR image. Supports custom colors, dot shapes, corner shapes, and logo embedding.",
    inputSchema: z.object({
      target_url: z
        .string()
        .url()
        .describe("The destination URL the QR code should redirect to."),
      label: z
        .string()
        .optional()
        .describe("An optional label to identify this QR code."),
      format: z
        .enum(["svg", "png"])
        .default("svg")
        .describe(
          'Image format. "svg" is recommended (smaller, scalable, text-parseable). Use "png" only if a bitmap is required.'
        ),
      foreground_color: z
        .string()
        .regex(/^#[0-9A-Fa-f]{6}$/)
        .optional()
        .describe("Hex color for QR code dots. Default: #000000 (black)."),
      background_color: z
        .string()
        .regex(/^#[0-9A-Fa-f]{6}$/)
        .optional()
        .describe("Hex color for QR code background. Default: #ffffff (white)."),
      width: z
        .number()
        .min(200)
        .max(2000)
        .optional()
        .describe("QR code width in pixels. Default: 400."),
      margin: z
        .number()
        .min(0)
        .max(10)
        .optional()
        .describe("Quiet zone margin in modules. Default: 2."),
      error_correction: z
        .enum(["L", "M", "Q", "H"])
        .optional()
        .describe("Error correction level. L=7%, M=15% (default), Q=25%, H=30%. Auto-set to H when logo is provided."),
      dot_style: z
        .enum(["square", "rounded", "dots", "classy-rounded"])
        .optional()
        .describe("Shape of data modules. square=classic, rounded=soft corners, dots=circles, classy-rounded=organic."),
      corner_style: z
        .enum(["square", "extra-rounded", "dot"])
        .optional()
        .describe("Shape of finder patterns (corner squares). square=classic, extra-rounded=smooth, dot=circular."),
      logo_url: z
        .string()
        .optional()
        .describe("URL to a logo image (PNG/JPG/SVG) or data:base64 URI. Centered on the QR code."),
      logo_size: z
        .number()
        .min(0.15)
        .max(0.3)
        .optional()
        .describe("Logo size as ratio of QR width (0.15-0.3). Default: 0.2."),
      gradient: z.object({
        type: z.enum(["linear", "radial"]).describe("Gradient type."),
        colors: z.array(z.string().regex(/^#[0-9A-Fa-f]{6}$/)).min(2).describe("2+ hex colors, evenly distributed."),
        angle: z.number().min(0).max(360).optional().describe("Angle in degrees (linear only). 0=left-to-right, 90=top-to-bottom."),
      }).optional().describe("Apply a gradient to QR dots and corners instead of solid foreground_color."),
      frame_style: z.enum(["none", "banner_bottom", "banner_top", "rounded"]).optional()
        .describe("Decorative frame around QR. 'banner_bottom': text below, 'banner_top': text above, 'rounded': rounded border with text."),
      frame_text: z.string().max(30).optional()
        .describe("CTA text on the frame (e.g. 'Scan Me!', 'View Menu'). Max 30 chars. Requires frame_style."),
      frame_color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional()
        .describe("Hex color for frame background. Default: #000000."),
      frame_text_color: z.string().regex(/^#[0-9A-Fa-f]{6}$/).optional()
        .describe("Hex color for frame text. Default: #ffffff."),
      frame_border_radius: z.number().min(0).max(20).optional()
        .describe("Frame corner radius. Only for 'rounded' style."),
      expires_at: z
        .string()
        .optional()
        .describe("ISO 8601 date-time. After this date, scanning returns 410 Gone instead of redirecting."),
      scheduled_url: z
        .string()
        .url()
        .optional()
        .describe("Replacement URL that activates at scheduled_at."),
      scheduled_at: z
        .string()
        .optional()
        .describe("ISO 8601 date-time when target automatically switches to scheduled_url."),
      gtm_container_id: z
        .string()
        .regex(/^GTM-[A-Z0-9]+$/)
        .optional()
        .describe("Google Tag Manager container ID (e.g. 'GTM-ABC123'). Enables GTM tracking on QR scans via an intermediate HTML page."),
    }),
    handler: async (input: Record<string, unknown>) => {
      return apiRequest("/api/qr", { method: "POST", body: input });
    },
  },