create_qurl

Instructions

Implementation Reference

• src/tools/create-qurl.ts:73-92 (handler)

  The createQurlTool factory function that returns the 'create_qurl' MCP tool with its handler. The handler receives validated input, calls client.createQURL(), and returns the result (including the ephemeral qurl_link).

  export function createQurlTool(client: IQURLClient) {
    return {
      name: "create_qurl",
      description:
        "Create a qURL - a secure, policy-bound link to a protected resource. " +
        "The returned qurl_link is ephemeral (shown once) and should be shared immediately.",
      inputSchema: createQurlSchema,
      handler: async (input: z.infer<typeof createQurlSchema>) => {
        const result = await client.createQURL(input);
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(result.data),
            },
          ],
        };
      },
    };
  }

• src/tools/create-qurl.ts:44-71 (schema)

  Zod schema for create_qurl input validation. Defines the shape of parameters: target_url (required URL), label, expires_in, one_time_use, max_sessions, session_duration, custom_domain, and access_policy (nested).

  export const createQurlSchema = z.object({
    target_url: z.string().url().describe("The URL to protect with qURL"),
    label: z
      .string()
      .max(500)
      .optional()
      .describe("Human-readable label identifying who this qURL is for (max 500 chars)"),
    expires_in: z
      .string()
      .min(1)
      .optional()
      .describe('Duration string (e.g., "1h", "24h", "7d")'),
    one_time_use: z.boolean().optional().describe("Whether the link can only be used once"),
    max_sessions: z
      .number()
      .int()
      .min(0)
      .max(1000)
      .optional()
      .describe("Maximum concurrent sessions (0 = unlimited, max 1000)"),
    session_duration: z
      .string()
      .min(1)
      .optional()
      .describe('How long access lasts after clicking (e.g., "1h")'),
    custom_domain: z.string().optional().describe("Custom domain to assign to the auto-created resource"),
    access_policy: accessPolicySchema.optional().describe("Access control policy for the qURL"),
  });

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

  The 'create_qurl' tool is registered in the MCP server via the createQurlTool factory. It's listed in toolFactories array (line 40) and registered with server.tool() in the loop at line 53.

  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:43-50 (schema)

  CreateQURLData interface defining the shape of the create_qurl response data (qurl_id, resource_id, qurl_link, qurl_site, expires_at, label).

  export interface CreateQURLData {
    qurl_id: string;
    resource_id: string;
    qurl_link: string;
    qurl_site: string;
    expires_at: string;
    label?: string;
  }

• src/client.ts:328-330 (helper)

  The createQURL method on the QURLClient class that makes the actual HTTP POST request to /v1/qurls.

  async createQURL(input: CreateQURLInput): Promise<{ data: CreateQURLData }> {
    return this.request("POST", "/v1/qurls", input);
  }