set_utm_params

Instructions

Implementation Reference

• packages/mcp/src/tools.ts:755-769 (handler)

  The handler function for set_utm_params. Builds a body with utm_params (or null to clear) and PATCHes the QR code via the API.

  handler: async (input: { short_id: string; source?: string; medium?: string; campaign?: string; term?: string; content?: string; clear?: boolean }) => {
    const body: Record<string, unknown> = {};
    if (input.clear) {
      body.utm_params = null;
    } else {
      const utm: Record<string, string> = {};
      if (input.source) utm.source = input.source;
      if (input.medium) utm.medium = input.medium;
      if (input.campaign) utm.campaign = input.campaign;
      if (input.term) utm.term = input.term;
      if (input.content) utm.content = input.content;
      body.utm_params = utm;
    }
    return apiRequest(`/api/qr/${input.short_id}`, { method: "PATCH", body });
  },

• packages/mcp/src/tools.ts:746-754 (schema)

  Zod schema defining the input: short_id (required), source/medium/campaign/term/content (optional strings), clear (optional boolean).

  inputSchema: z.object({
    short_id: z.string().describe("The short ID of the QR code (must be type='url')."),
    source: z.string().optional().describe("utm_source value (e.g. 'flyer', 'email', 'poster')."),
    medium: z.string().optional().describe("utm_medium value (e.g. 'print', 'qr', 'social')."),
    campaign: z.string().optional().describe("utm_campaign value (e.g. 'summer_2026')."),
    term: z.string().optional().describe("utm_term value (paid search keyword)."),
    content: z.string().optional().describe("utm_content value (A/B test variant)."),
    clear: z.boolean().optional().describe("Set to true to remove all UTM parameters from this QR code."),
  }),

• packages/mcp/src/server.ts:21-53 (registration)

  All tools (including set_utm_params) are registered via server.tool() in a loop over the tools object.

  for (const [name, tool] of Object.entries(tools)) {
    server.tool(
      name,
      tool.description,
      tool.inputSchema.shape,
      async (input: Record<string, unknown>) => {
        try {
          const result = await tool.handler(input as any);
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify(result, null, 2),
              },
            ],
          };
        } catch (error) {
          const message = error instanceof Error ? error.message : String(error);
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify({
                  error: message,
                  hint: "Check the input parameters and try again. Use list_qr_codes to verify available QR codes.",
                }),
              },
            ],
            isError: true,
          };
        }
      }
    );

• packages/mcp/src/tools.ts:743-770 (registration)

  The tool definition object set_utm_params is part of the exported 'tools' object, which is imported and registered in server.ts.

  set_utm_params: {
    description:
      "Set UTM tracking parameters on a URL QR code. These parameters are automatically appended to the target URL on every scan redirect. Use this to track QR code scans in Google Analytics or other analytics tools. Set 'clear' to true to remove all UTM parameters.",
    inputSchema: z.object({
      short_id: z.string().describe("The short ID of the QR code (must be type='url')."),
      source: z.string().optional().describe("utm_source value (e.g. 'flyer', 'email', 'poster')."),
      medium: z.string().optional().describe("utm_medium value (e.g. 'print', 'qr', 'social')."),
      campaign: z.string().optional().describe("utm_campaign value (e.g. 'summer_2026')."),
      term: z.string().optional().describe("utm_term value (paid search keyword)."),
      content: z.string().optional().describe("utm_content value (A/B test variant)."),
      clear: z.boolean().optional().describe("Set to true to remove all UTM parameters from this QR code."),
    }),
    handler: async (input: { short_id: string; source?: string; medium?: string; campaign?: string; term?: string; content?: string; clear?: boolean }) => {
      const body: Record<string, unknown> = {};
      if (input.clear) {
        body.utm_params = null;
      } else {
        const utm: Record<string, string> = {};
        if (input.source) utm.source = input.source;
        if (input.medium) utm.medium = input.medium;
        if (input.campaign) utm.campaign = input.campaign;
        if (input.term) utm.term = input.term;
        if (input.content) utm.content = input.content;
        body.utm_params = utm;
      }
      return apiRequest(`/api/qr/${input.short_id}`, { method: "PATCH", body });
    },
  },

• packages/mcp/src/api-client.ts:13-40 (helper)

  The apiRequest helper function used by the handler to call the backend API.

  export async function apiRequest(path: string, options: RequestOptions = {}) {
    const { method = "GET", body, query } = options;
  
    let url = `${BASE_URL}${path}`;
    if (query) {
      const params = new URLSearchParams();
      for (const [key, value] of Object.entries(query)) {
        params.set(key, String(value));
      }
      url += `?${params.toString()}`;
    }
  
    const headers: Record<string, string> = {
      "X-API-Key": API_KEY,
    };
  
    if (body) {
      headers["Content-Type"] = "application/json";
    }
  
    const res = await fetch(url, {
      method,
      headers,
      body: body ? JSON.stringify(body) : undefined,
    });
  
    return res.json();
  }