list_qr_codes

Instructions

Implementation Reference

• src/modules/qr/qr.service.ts:246-268 (handler)

  The core handler function `listQrCodes` that queries the database for QR codes owned by the API key, with pagination (limit/offset). Returns data, total count, offset, and limit.

  export function listQrCodes(limit: number = 20, offset: number = 0, apiKeyId: number) {
    const rows = db
      .select()
      .from(qrCodes)
      .where(eq(qrCodes.apiKeyId, apiKeyId))
      .limit(limit)
      .offset(offset)
      .all();
  
    const [{ total }] = db
      .select({ total: count() })
      .from(qrCodes)
      .where(eq(qrCodes.apiKeyId, apiKeyId))
      .all();
  
    const customDomain = getCustomDomain(apiKeyId);
    return {
      data: rows.map((row) => formatQrResponse(row, customDomain)),
      total,
      offset,
      limit,
    };
  }

• packages/mcp/src/tools.ts:170-180 (handler)

  The MCP tool definition for 'list_qr_codes' with input schema (limit/offset) and handler that calls the HTTP API endpoint GET /api/qr via apiRequest.

  list_qr_codes: {
    description:
      "List all managed QR codes with pagination. Returns short IDs, target URLs, labels, and timestamps. Use this to browse or search for existing QR codes.",
    inputSchema: z.object({
      limit: z.number().min(1).max(100).default(20).describe("Max results to return."),
      offset: z.number().min(0).default(0).describe("Number of results to skip."),
    }),
    handler: async (input: { limit: number; offset: number }) => {
      return apiRequest("/api/qr", { query: { limit: input.limit, offset: input.offset } });
    },
  },

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

  Registration of all tools (including list_qr_codes) into the MCP server by iterating over the tools object and calling server.tool().

  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,
          };
        }
      }
    );
  }

• src/modules/qr/qr.schemas.ts:473-492 (schema)

  JSON Schema (qrListSchema) defining the query parameters limit (integer, 1-100, default 20) and offset (integer, min 0, default 0) for the list endpoint.

  export const qrListSchema = {
    querystring: {
      type: "object" as const,
      properties: {
        limit: {
          type: "integer",
          default: 20,
          minimum: 1,
          maximum: 100,
          description: "Maximum number of QR codes to return. Defaults to 20, max 100.",
        },
        offset: {
          type: "integer",
          default: 0,
          minimum: 0,
          description: "Number of records to skip for pagination.",
        },
      },
    },
  };

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

  The apiRequest helper function used by the MCP tool handler to make HTTP requests to the backend API, converting query params and returning JSON.

  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();
  }