Add limit/offset pagination to unbounded list tools (#35)

Author: bigcat88

.github/workflows/tests-integration.yml

@@ -81,6 +81,9 @@ jobs:
           echo "::add-mask::$APP_PASS"
           echo "NC_APP_PASSWORD=$APP_PASS" >> "$GITHUB_ENV"
 
+      - name: Seed pagination test data
+        run: python scripts/seed_pagination_data.py http://localhost:8080 admin "$NC_APP_PASSWORD"
+
       - name: Run integration tests
         env:
           NEXTCLOUD_URL: http://localhost:8080

pyproject.toml

@@ -93,6 +93,7 @@ lint.extend-ignore = [
   "SIM117",
   "TRY003",
 ]
+lint.extend-per-file-ignores."scripts/**/*.py" = [ "S314", "T201" ]
 lint.extend-per-file-ignores."src/nc_mcp_server/client.py" = [ "S314" ]
 lint.extend-per-file-ignores."src/nc_mcp_server/config.py" = [ "S104" ]
 lint.extend-per-file-ignores."tests/**/*.py" = [ "E402", "S", "UP" ]
@@ -105,6 +106,7 @@ pythonVersion = "3.12"
 typeCheckingMode = "strict"
 venvPath = "."
 venv = "venv"
+exclude = [ "scripts" ]
 reportUnusedFunction = false
 reportPrivateUsage = false
 executionEnvironments = [

scripts/seed_pagination_data.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Seed synthetic data for pagination integration tests.
+
+Creates bulk test data across multiple Nextcloud apps to verify
+pagination behavior with limit/offset parameters.
+
+Usage: python scripts/seed_pagination_data.py <NC_URL> <USER> <PASSWORD>
+
+Seeded data uses the "mcp-pagtest" prefix and lives outside the
+regular test cleanup path (mcp-test-suite), so it persists across
+individual test runs but is ephemeral in CI (container destroyed).
+"""
+
+import sys
+import xml.etree.ElementTree as ET
+
+import niquests
+
+COUNT = 55
+PREFIX = "mcp-pagtest"
+PAGINATION_DIR = "mcp-pagination-data"
+
+
+def _ocs_data(resp: niquests.Response) -> object:
+    """Extract data from an OCS JSON response."""
+    return resp.json()["ocs"]["data"]
+
+
+def seed_files(s: niquests.Session, url: str, user: str) -> None:
+    """Create files in a dedicated pagination test directory."""
+    dav = f"{url}/remote.php/dav/files/{user}"
+    s.request("MKCOL", f"{dav}/{PAGINATION_DIR}/")
+    for i in range(1, COUNT + 1):
+        s.put(
+            f"{dav}/{PAGINATION_DIR}/pagtest-{i:03d}.txt",
+            data=f"Pagination test file {i:03d}",
+            headers={"Content-Type": "text/plain"},
+        )
+    print(f"  {COUNT} files in {PAGINATION_DIR}/")
+
+
+def seed_conversations(s: niquests.Session, url: str) -> None:
+    """Create Talk group conversations."""
+    api = f"{url}/ocs/v2.php/apps/spreed/api/v4/room"
+    existing = {r["name"] for r in _ocs_data(s.get(api))}
+    created = 0
+    for i in range(1, COUNT + 1):
+        name = f"{PREFIX}-conv-{i:03d}"
+        if name not in existing:
+            s.post(api, json={"roomType": 2, "roomName": name})
+            created += 1
+    print(f"  {created} conversations (skipped {COUNT - created})")
+
+
+def seed_calendar_events(s: niquests.Session, url: str, user: str) -> None:
+    """Create calendar events via CalDAV PUT."""
+    cal = f"{url}/remote.php/dav/calendars/{user}/personal"
+    for i in range(1, COUNT + 1):
+        uid = f"{PREFIX}-event-{i:03d}"
+        hour = i % 24
+        ical = (
+            "BEGIN:VCALENDAR\r\n"
+            "VERSION:2.0\r\n"
+            "PRODID:-//NC MCP//Pagination Test//EN\r\n"
+            "BEGIN:VEVENT\r\n"
+            f"UID:{uid}\r\n"
+            f"SUMMARY:Pagination Test Event {i:03d}\r\n"
+            f"DTSTART:20270601T{hour:02d}0000Z\r\n"
+            f"DTEND:20270601T{hour:02d}3000Z\r\n"
+            f"DESCRIPTION:Seeded event {i:03d} for pagination testing\r\n"
+            "DTSTAMP:20270101T000000Z\r\n"
+            "END:VEVENT\r\n"
+            "END:VCALENDAR\r\n"
+        )
+        s.put(f"{cal}/{uid}.ics", data=ical, headers={"Content-Type": "text/calendar; charset=utf-8"})
+    print(f"  {COUNT} calendar events")
+
+
+def seed_trash(s: niquests.Session, url: str, user: str) -> None:
+    """Create files then delete them to populate the trash bin."""
+    dav = f"{url}/remote.php/dav/files/{user}"
+    trash_dir = f"{PREFIX}-trash"
+    s.request("MKCOL", f"{dav}/{trash_dir}/")
+    for i in range(1, COUNT + 1):
+        path = f"{dav}/{trash_dir}/trash-{i:03d}.txt"
+        s.put(path, data=f"Trash item {i:03d}", headers={"Content-Type": "text/plain"})
+    for i in range(1, COUNT + 1):
+        s.delete(f"{dav}/{trash_dir}/trash-{i:03d}.txt")
+    s.delete(f"{dav}/{trash_dir}/")
+    print(f"  {COUNT} items in trash")
+
+
+def seed_collective_pages(s: niquests.Session, url: str) -> None:
+    """Create a collective with many pages for pagination testing."""
+    api = f"{url}/ocs/v2.php/apps/collectives/api/v1.0"
+    coll_name = f"{PREFIX}-collective"
+
+    collectives = _ocs_data(s.get(f"{api}/collectives"))
+    coll = next((c for c in collectives["collectives"] if c["name"] == coll_name), None)
+    if not coll:
+        resp = s.post(
+            f"{api}/collectives",
+            json={"name": coll_name},
+            headers={"Content-Type": "application/json"},
+        )
+        coll = _ocs_data(resp)["collective"]
+    coll_id = coll["id"]
+
+    pages_data = _ocs_data(s.get(f"{api}/collectives/{coll_id}/pages"))
+    pages = pages_data["pages"]
+    landing_id = pages[0]["id"]
+    existing_titles = {p["title"] for p in pages}
+
+    created = 0
+    for i in range(1, COUNT + 1):
+        title = f"pagtest-page-{i:03d}"
+        if title not in existing_titles:
+            s.post(
+                f"{api}/collectives/{coll_id}/pages/{landing_id}",
+                json={"title": title},
+                headers={"Content-Type": "application/json"},
+            )
+            created += 1
+    # total = created + existing (minus landing page)
+    print(f"  {created} pages in collective '{coll_name}' (skipped {COUNT - created})")
+
+
+def seed_comments(s: niquests.Session, url: str, user: str) -> None:
+    """Create a dedicated file and add many comments to it."""
+    dav = f"{url}/remote.php/dav/files/{user}"
+    comment_file = f"{PAGINATION_DIR}/comment-target.txt"
+    s.put(f"{dav}/{comment_file}", data="File with many comments", headers={"Content-Type": "text/plain"})
+
+    resp = s.request(
+        "PROPFIND",
+        f"{dav}/{comment_file}",
+        data=(
+            '<?xml version="1.0"?>'
+            '<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">'
+            "<d:prop><oc:fileid/></d:prop>"
+            "</d:propfind>"
+        ),
+        headers={"Content-Type": "text/xml", "Depth": "0"},
+    )
+    root = ET.fromstring(resp.text)
+    fileid_el = root.find(".//{http://owncloud.org/ns}fileid")
+    if fileid_el is None or not fileid_el.text:
+        print("  WARNING: could not resolve file ID for comments, skipping")
+        return
+    file_id = fileid_el.text
+
+    for i in range(1, COUNT + 1):
+        s.post(
+            f"{url}/remote.php/dav/comments/files/{file_id}",
+            json={"actorType": "users", "verb": "comment", "message": f"Pagination test comment {i:03d}"},
+            headers={"Content-Type": "application/json"},
+        )
+    print(f"  {COUNT} comments on file {file_id}")
+
+
+def main() -> None:
+    if len(sys.argv) != 4:
+        print(f"Usage: {sys.argv[0]} <NC_URL> <USER> <PASSWORD>")
+        sys.exit(1)
+
+    url = sys.argv[1].rstrip("/")
+    user = sys.argv[2]
+    password = sys.argv[3]
+
+    s = niquests.Session()
+    s.auth = (user, password)
+    s.headers.update({"OCS-APIRequest": "true", "Accept": "application/json"})
+
+    print(f"=== Seeding pagination test data ({COUNT} items per app) ===")
+
+    print("Files...")
+    seed_files(s, url, user)
+
+    print("Talk conversations...")
+    seed_conversations(s, url)
+
+    print("Calendar events...")
+    seed_calendar_events(s, url, user)
+
+    print("Trash items...")
+    seed_trash(s, url, user)
+
+    print("Collective pages...")
+    seed_collective_pages(s, url)
+
+    print("Comments...")
+    seed_comments(s, url, user)
+
+    print("=== Seed complete ===")
+    s.close()
+
+
+if __name__ == "__main__":
+    main()

src/nc_mcp_server/tools/calendar.py

@@ -366,6 +366,8 @@ async def get_events(
         calendar_id: str = "personal",
         start: str = "",
         end: str = "",
+        limit: int = 50,
+        offset: int = 0,
     ) -> str:
         """Get events from a calendar, optionally filtered by time range.
 
@@ -379,13 +381,17 @@ async def get_events(
                    Required if end is provided.
             end: Optional range end in ISO 8601 UTC format: "2026-04-30T23:59:59Z".
                  Required if start is provided.
+            limit: Maximum number of events to return (1-500, default 50).
+            offset: Number of events to skip for pagination (default 0).
 
         Returns:
-            JSON list of event objects with: uid, summary, dtstart, dtend, location,
-            description, status, all_day, and optionally rrule and categories.
+            JSON with "data" (list of event objects) and "pagination"
+            (count, offset, limit, has_more).
         """
         if bool(start) != bool(end):
             raise ValueError("Both start and end are required for time-range filtering, or omit both.")
+        limit = max(1, min(500, limit))
+        offset = max(0, offset)
         caldav_start = start.replace("-", "").replace(":", "").replace(".", "") if start else None
         caldav_end = end.replace("-", "").replace(":", "").replace(".", "") if end else None
         if caldav_start:
@@ -405,12 +411,21 @@ async def get_events(
             context=f"Get events from '{calendar_id}'",
         )
         results = _parse_report_xml(response.text or "")
-        events = []
+        all_events = []
         for _href, etag, ical_data in results:
             event = _format_event(ical_data)
             event["etag"] = etag
-            events.append(event)
-        return json.dumps(events)
+            all_events.append(event)
+        page = all_events[offset : offset + limit]
+        has_more = offset + limit < len(all_events)
+
+        return json.dumps(
+            {
+                "data": page,
+                "pagination": {"count": len(page), "offset": offset, "limit": limit, "has_more": has_more},
+            },
+            default=str,
+        )
 
     @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)

src/nc_mcp_server/tools/collectives.py

@@ -42,38 +42,66 @@ def _format_page(p: dict[str, Any]) -> dict[str, Any]:
 def _register_read_tools(mcp: FastMCP) -> None:
     @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
-    async def list_collectives() -> str:
-        """List all collectives the current user has access to.
+    async def list_collectives(limit: int = 50, offset: int = 0) -> str:
+        """List collectives the current user has access to.
 
         Collectives are shared knowledge bases with wiki-style pages.
-        Each collective has a landing page and may contain nested subpages.
+
+        Args:
+            limit: Maximum number of collectives to return (1-200, default 50).
+            offset: Number of collectives to skip for pagination (default 0).
 
         Returns:
-            JSON list of collectives with id, name, emoji, permissions.
+            JSON with "data" (list of collectives with id, name, emoji, permissions)
+            and "pagination" (count, offset, limit, has_more).
         """
+        limit = max(1, min(200, limit))
+        offset = max(0, offset)
         client = get_client()
         data = await client.ocs_get(f"{API}/collectives")
-        collectives = [_format_collective(c) for c in data["collectives"]]
-        return json.dumps(collectives, default=str)
+        all_collectives = [_format_collective(c) for c in data["collectives"]]
+        page = all_collectives[offset : offset + limit]
+        has_more = offset + limit < len(all_collectives)
+
+        return json.dumps(
+            {
+                "data": page,
+                "pagination": {"count": len(page), "offset": offset, "limit": limit, "has_more": has_more},
+            },
+            default=str,
+        )
 
     @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)
-    async def get_collective_pages(collective_id: int) -> str:
-        """List all pages in a collective.
+    async def get_collective_pages(collective_id: int, limit: int = 50, offset: int = 0) -> str:
+        """List pages in a collective.
 
-        Returns the full page tree including the landing page and all subpages.
-        Each page has a title, emoji, timestamp, size, and file path.
+        Returns the page tree including the landing page and all subpages.
 
         Args:
             collective_id: The numeric collective ID. Use list_collectives to find IDs.
+            limit: Maximum number of pages to return (1-200, default 50).
+            offset: Number of pages to skip for pagination (default 0).
 
         Returns:
-            JSON list of pages with id, title, emoji, timestamp, size, file_name, file_path.
+            JSON with "data" (list of pages with id, title, emoji, timestamp, size)
+            and "pagination" (count, offset, limit, has_more).
         """
+        limit = max(1, min(200, limit))
+        offset = max(0, offset)
         client = get_client()
         data = await client.ocs_get(f"{API}/collectives/{collective_id}/pages")
-        pages = [_format_page(p) for p in data["pages"]]
-        return json.dumps(pages, default=str)
+        all_pages = [_format_page(p) for p in data["pages"]]
+        page = all_pages[offset : offset + limit]
+        has_more = offset + limit < len(all_pages)
+
+        return json.dumps(
+            {
+                "data": page,
+                "pagination": {"count": len(page), "offset": offset, "limit": limit, "has_more": has_more},
+            },
+            default=str,
+        )
 
     @mcp.tool(annotations=READONLY)
     @require_permission(PermissionLevel.READ)

src/nc_mcp_server/tools/comments.py

@@ -112,7 +112,7 @@ async def list_comments(file_id: int, limit: int = 20, offset: int = 0) -> str:
 
         Returns:
             JSON object with "data" (list of comments) and "pagination"
-            (count, offset, has_more).
+            (count, offset, limit, has_more).
         """
         limit = max(1, min(100, limit))
         offset = max(0, offset)
@@ -131,6 +131,7 @@ async def list_comments(file_id: int, limit: int = 20, offset: int = 0) -> str:
             "pagination": {
                 "count": len(comments),
                 "offset": offset,
+                "limit": limit,
                 "has_more": len(comments) == limit,
             },
         }