list_qurls

Instructions

Implementation Reference

• src/tools/list-qurls.ts:42-61 (handler)

  The main tool factory function. Creates the MCP tool definition with name 'list_qurls', description, Zod inputSchema, and the async handler that calls client.listQURLs() and returns the JSON result.

  export function listQurlsTool(client: IQURLClient) {
    return {
      name: "list_qurls",
      description:
        "List qURLs with optional filtering by status, date ranges, and search query.",
      inputSchema: listQurlsSchema,
      handler: async (input: z.infer<typeof listQurlsSchema>) => {
        const result = await client.listQURLs(input);
        return {
          content: [
            {
              type: "text" as const,
              // Full result (not .data) — includes meta.next_cursor for pagination
              text: JSON.stringify(result),
            },
          ],
        };
      },
    };
  }

• src/tools/list-qurls.ts:4-40 (schema)

  Zod schema for the list_qurls tool input. Defines optional parameters: limit (1-100), cursor (pagination), status (comma-separated), created_after/before, expires_before/after (RFC 3339 dates), sort (created_at|expires_at with :asc/:desc), and q (free-text search).

  export const listQurlsSchema = z.object({
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe("Maximum number of qURLs to return (default: 20)"),
    cursor: z.string().optional().describe("Pagination cursor from a previous response"),
    // Plain string (not z.enum) because the API accepts comma-separated values like "active,revoked"
    status: z
      .string()
      .min(1)
      .optional()
      .describe("Filter by status (comma-separated, e.g., 'active,revoked')"),
    created_after: z.string().datetime().optional().describe("Filter: created after this date (RFC 3339)"),
    created_before: z.string().datetime().optional().describe("Filter: created before this date (RFC 3339)"),
    expires_before: z.string().datetime().optional().describe("Filter: expires before this date (RFC 3339)"),
    expires_after: z.string().datetime().optional().describe("Filter: expires after this date (RFC 3339)"),
    sort: z
      .string()
      .regex(
        /^(created_at|expires_at)(:(asc|desc))?$/,
        "sort must be 'created_at' or 'expires_at', optionally followed by ':asc' or ':desc'",
      )
      .optional()
      .describe(
        "Sort field and direction as 'field:direction'. " +
          "Valid fields: created_at, expires_at. Valid directions: asc, desc (default desc). " +
          "Example: 'created_at:desc'.",
      ),
    q: z
      .string()
      .min(1)
      .optional()
      .describe("Search query (searches description and target_url)"),
  });

• src/server.ts:39-54 (registration)

  Registration of list_qurlsTool in the MCP server. The tool factory is included in the toolFactories array, instantiated with the client, and registered via server.tool() with its name, description, schema shape, and handler.

  const toolFactories = [
    createQurlTool,
    resolveQurlTool,
    listQurlsTool,
    getQurlTool,
    deleteQurlTool,
    extendQurlTool,
    updateQurlTool,
    mintLinkTool,
    batchCreateTool,
  ] satisfies ToolFactory[];
  
  for (const factory of toolFactories) {
    const tool = factory(client);
    server.tool(tool.name, tool.description, tool.inputSchema.shape, tool.handler);
  }

• src/client.ts:336-349 (helper)

  The QURLClient.listQURLs() method that makes the actual HTTP GET request to /v1/qurls with query parameters for pagination, filtering, and search.

  async listQURLs(input?: ListQURLsInput): Promise<ListQURLsOutput> {
    const params = new URLSearchParams();
    if (input?.limit !== undefined) params.set("limit", String(input.limit));
    if (input?.cursor) params.set("cursor", input.cursor);
    if (input?.status) params.set("status", input.status);
    if (input?.created_after) params.set("created_after", input.created_after);
    if (input?.created_before) params.set("created_before", input.created_before);
    if (input?.expires_before) params.set("expires_before", input.expires_before);
    if (input?.expires_after) params.set("expires_after", input.expires_after);
    if (input?.sort) params.set("sort", input.sort);
    if (input?.q) params.set("q", input.q);
    const query = params.toString();
    return this.request("GET", `/v1/qurls${query ? `?${query}` : ""}`);
  }

• src/client.ts:81-98 (schema)

  TypeScript interface defining the input shape for listQURLs, matching the Zod schema fields.

  export interface ListQURLsInput {
    limit?: number;
    cursor?: string;
    /** Filter by status. Accepts comma-separated values, e.g. `"active,revoked"`. */
    status?: string;
    /** RFC 3339 timestamp. */
    created_after?: string;
    /** RFC 3339 timestamp. */
    created_before?: string;
    /** RFC 3339 timestamp. */
    expires_before?: string;
    /** RFC 3339 timestamp. */
    expires_after?: string;
    /** Sort field and direction, e.g. `"created_at:desc"`. */
    sort?: string;
    /** Free-text search over description and target_url. */
    q?: string;
  }