list_documents

Instructions

Implementation Reference

• src/tools.ts:156-173 (handler)

  The async handler function that executes the list_documents tool logic. It builds query parameters (folder, limit, cursor), sends a GET request to /v1/documents via the API client, and returns the JSON result.

    async ({ folder, limit, cursor }) => {
      try {
        const query: Record<string, string> = {};
        if (folder) query.folder = folder;
        if (limit) query.limit = String(limit);
        if (cursor) query.cursor = cursor;
        const result = await client.request(
          "GET",
          "/v1/documents",
          undefined,
          query,
        );
        return jsonResult(result);
      } catch (err) {
        return errorResult(err);
      }
    },
  );

• src/tools.ts:132-148 (schema)

  Zod schema defining the input parameters for list_documents: optional folder (string), limit (number, 1-100, int), and cursor (string for pagination).

  {
    folder: z
      .string()
      .optional()
      .describe("Optional. Filter by folder name (case-insensitive) or folder ID."),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe("Max results per page (default: 20, max: 100)"),
    cursor: z
      .string()
      .optional()
      .describe("Pagination cursor from a previous response"),
  },

• src/tools.ts:129-173 (registration)

  Registration of the list_documents tool via server.tool(), which is called from the registerTools function in src/tools.ts, which in turn is called from createServerInstance in src/index.ts.

  server.tool(
    "list_documents",
    "List your saved documents with pagination. Optionally filter by folder name or ID.",
    {
      folder: z
        .string()
        .optional()
        .describe("Optional. Filter by folder name (case-insensitive) or folder ID."),
      limit: z
        .number()
        .int()
        .min(1)
        .max(100)
        .optional()
        .describe("Max results per page (default: 20, max: 100)"),
      cursor: z
        .string()
        .optional()
        .describe("Pagination cursor from a previous response"),
    },
    {
      title: "List Documents",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
    async ({ folder, limit, cursor }) => {
      try {
        const query: Record<string, string> = {};
        if (folder) query.folder = folder;
        if (limit) query.limit = String(limit);
        if (cursor) query.cursor = cursor;
        const result = await client.request(
          "GET",
          "/v1/documents",
          undefined,
          query,
        );
        return jsonResult(result);
      } catch (err) {
        return errorResult(err);
      }
    },
  );

• src/tools.ts:24-29 (helper)

  The jsonResult helper function used by the list_documents handler to format the API response as JSON text content.

  function jsonResult(data: unknown) {
    return {
      content: [
        { type: "text" as const, text: JSON.stringify(data, null, 2) },
      ],
    };

• src/tools.ts:5-22 (helper)

  The errorResult helper function used by the list_documents handler to format API errors into error content.

  function errorResult(err: unknown) {
    if (err instanceof ApiError) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error ${err.status} (${err.code}): ${err.message}`,
          },
        ],
        isError: true,
      };
    }
    const message = err instanceof Error ? err.message : String(err);
    return {
      content: [{ type: "text" as const, text: `Error: ${message}` }],
      isError: true,
    };
  }