fix: paginate large Moodle course lists

Author: pythonIsFast

README.md

@@ -113,7 +113,8 @@ The Moodle server signs in through Moodle's regular login page and keeps an auth
 ### Features
 
 - Log in through a local GUI or terminal setup
-- List courses and inspect sections and activities
+- List and search courses with pagination for accounts with many enrolments
+- Inspect course sections and activities
 - Create courses
 - Rename, move, show, hide, duplicate, and delete course content
 - Create and update pages, URLs, labels, folders, forums, assignments, resources, and basic quizzes

moodle_mcp_server.py

@@ -407,45 +407,148 @@ def ajax(self, methodname, args):
 
     # -- Kurse --
 
-    def list_courses(self):
+    def list_courses(self, search="", limit=25, offset=0):
         try:
+            limit = int(limit)
+            offset = int(offset)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("limit und offset muessen ganze Zahlen sein.") from exc
+        if not 1 <= limit <= 100:
+            raise ValueError("limit muss zwischen 1 und 100 liegen.")
+        if offset < 0:
+            raise ValueError("offset darf nicht negativ sein.")
+        search = str(search or "").strip()
+
+        try:
+            args = {
+                "offset": offset,
+                "limit": limit,
+                "classification": "all",
+                "sort": "fullname",
+            }
+            if search:
+                args["searchvalue"] = search
             data = self.ajax(
                 "core_course_get_enrolled_courses_by_timeline_classification",
-                {"offset": 0, "limit": 0, "classification": "all", "sort": "fullname"},
+                args,
             )
             if isinstance(data, dict):
-                out = [{"id": c.get("id"), "fullname": c.get("fullname"),
+                raw_courses = data.get("courses", [])
+                out = [
+                    {
+                        "id": c.get("id"),
+                        "fullname": c.get("fullname"),
                         "shortname": c.get("shortname"),
                         "kategorie": c.get("coursecategory"),
-                        "sichtbar": c.get("visible")}
-                       for c in data.get("courses", [])]
-                if out:
-                    return {"kurse": out, "quelle": "AJAX (Timeline)"}
+                        "sichtbar": c.get("visible"),
+                    }
+                    for c in raw_courses
+                    if isinstance(c, dict)
+                ]
+                next_offset = data.get("nextoffset")
+                if isinstance(next_offset, int):
+                    next_offset = next_offset if next_offset > offset else None
+                else:
+                    next_offset = (
+                        offset + len(out) if len(out) >= limit else None
+                    )
+                result = {
+                    "kurse": out,
+                    "anzahl": len(out),
+                    "offset": offset,
+                    "limit": limit,
+                    "naechster_offset": next_offset,
+                    "weitere_vorhanden": next_offset is not None,
+                    "suche": search or None,
+                    "quelle": "AJAX (Timeline, paginiert)",
+                }
+                if next_offset is not None:
+                    result["hinweis"] = (
+                        "Weitere Kurse sind vorhanden. moodle_list_courses "
+                        f"mit offset={next_offset} aufrufen."
+                    )
+                return result
         except Exception as e:
             log(f"Kursliste via AJAX fehlgeschlagen: {e}")
 
-        return {"kurse": self._courses_html(),
-                "quelle": "HTML-Fallback (/course/index.php)",
-                "hinweis": "Als Admin sind nicht eingeschriebene Kurse nur "
-                           "hier sichtbar."}
+        courses = self._courses_html(search=search)
+        page = courses[offset:offset + limit]
+        next_offset = offset + len(page) if offset + len(page) < len(courses) else None
+        return {
+            "kurse": page,
+            "anzahl": len(page),
+            "offset": offset,
+            "limit": limit,
+            "naechster_offset": next_offset,
+            "weitere_vorhanden": next_offset is not None,
+            "suche": search or None,
+            "quelle": "HTML-Fallback (Meine Kurse/Dashboard)",
+            "hinweis": (
+                "Der AJAX-Endpunkt war nicht verfuegbar. Der HTML-Fallback "
+                "kann bei dynamisch geladenen Moodle-Dashboards unvollstaendig "
+                "sein."
+            ),
+        }
 
-    def _courses_html(self):
+    def _courses_html(self, search=""):
         found, seen = [], set()
-        for path in ("/course/index.php", "/course/management.php"):
+        search_folded = search.casefold()
+        pages = (
+            (
+                "/my/courses.php",
+                (
+                    '[data-region="course-content"]',
+                    '[data-region="courses-view"]',
+                    ".block_myoverview",
+                    "main",
+                ),
+            ),
+            ("/my/", (".block_myoverview", '[data-region="course-content"]')),
+            ("/course/index.php", ("main",)),
+            ("/course/management.php", ("main",)),
+        )
+        for path, scope_selectors in pages:
             try:
                 r = self.s.get(self.base + path, timeout=30)
+                r.raise_for_status()
             except Exception:
                 continue
             soup = BeautifulSoup(r.text, "html.parser")
-            for a in soup.select('a[href*="/course/view.php?id="]'):
-                m = re.search(r"id=(\d+)", a.get("href", ""))
-                name = a.get_text(strip=True)
-                if m and name and m.group(1) not in seen and m.group(1) != "1":
+            scopes = []
+            for selector in scope_selectors:
+                scopes.extend(soup.select(selector))
+            if not scopes and path == "/my/courses.php":
+                scopes = [soup]
+
+            before = len(found)
+            for scope in scopes:
+                for a in scope.select('a[href*="/course/view.php?id="]'):
+                    m = re.search(r"[?&]id=(\d+)", a.get("href", ""))
+                    name = " ".join(a.get_text(" ", strip=True).split())
+                    if (
+                        not m
+                        or not name
+                        or m.group(1) in seen
+                        or m.group(1) == "1"
+                        or (search_folded and search_folded not in name.casefold())
+                    ):
+                        continue
                     seen.add(m.group(1))
-                    found.append({"id": int(m.group(1)), "fullname": name,
-                                  "shortname": "", "kategorie": ""})
+                    found.append(
+                        {
+                            "id": int(m.group(1)),
+                            "fullname": name,
+                            "shortname": "",
+                            "kategorie": "",
+                        }
+                    )
             if found:
-                break
+                # Dashboard pages contain enrolled courses. Do not mix them
+                # with the site-wide public course catalogue.
+                if path.startswith("/my/") and len(found) > before:
+                    break
+                if path.startswith("/course/"):
+                    break
         return found
 
     # -- Struktur --
@@ -1159,10 +1262,18 @@ def moodle_logout() -> dict:
 
 
 @mcp.tool()
-def moodle_list_courses() -> dict:
+def moodle_list_courses(search: str = "", limit: int = 25,
+                        offset: int = 0) -> dict:
     """Listet die Kurse der Moodle-Instanz mit ID, Name, Kurzname und
-    Kategorie. Die ID brauchst du fuer alle kursbezogenen Werkzeuge."""
-    return with_retry(lambda s: s.list_courses())
+    Kategorie. Die ID brauchst du fuer alle kursbezogenen Werkzeuge.
+
+    Die Ausgabe ist paginiert, damit auch Konten mit vielen Kursen stabil
+    funktionieren. Standardmaessig werden 25 Kurse geliefert. Falls
+    'weitere_vorhanden' wahr ist, rufe das Werkzeug erneut mit dem Wert aus
+    'naechster_offset' auf. Mit search kann serverseitig nach Kursnamen
+    gesucht werden; limit darf zwischen 1 und 100 liegen.
+    """
+    return with_retry(lambda s: s.list_courses(search, limit, offset))
 
 
 @mcp.tool()
@@ -1492,4 +1603,4 @@ def run_setup_cli():
     else:
         log(f"Starte MCP-Server ({_MCP_FLAVOR}), "
             f"Keyring: {'ja' if _HAS_KEYRING else 'nein'}")
-        mcp.run()
+        mcp.run()

tests/test_moodle_courses.py

@@ -0,0 +1,124 @@
+import sys
+import types
+import unittest
+
+
+class _FakeFastMCP:
+    def __init__(self, _name):
+        pass
+
+    def tool(self):
+        return lambda function: function
+
+    def run(self):
+        pass
+
+
+fake_fastmcp = types.ModuleType("fastmcp")
+fake_fastmcp.FastMCP = _FakeFastMCP
+sys.modules.setdefault("fastmcp", fake_fastmcp)
+
+from moodle_mcp_server import MoodleSession
+
+
+class MoodleCoursePaginationTests(unittest.TestCase):
+    def setUp(self):
+        self.client = MoodleSession("https://moodle.example")
+        self.courses = [
+            {
+                "id": index,
+                "fullname": f"Course {index:02d}",
+                "shortname": f"C{index:02d}",
+                "coursecategory": "Test",
+                "visible": 1,
+                "summary": "Large field that must not reach the MCP result",
+            }
+            for index in range(1, 61)
+        ]
+        self.ajax_calls = []
+
+        def fake_ajax(method, args):
+            self.ajax_calls.append((method, args))
+            filtered = self.courses
+            search = args.get("searchvalue", "").casefold()
+            if search:
+                filtered = [
+                    course for course in filtered
+                    if search in course["fullname"].casefold()
+                ]
+            offset = args["offset"]
+            limit = args["limit"]
+            page = filtered[offset:offset + limit]
+            next_offset = offset + len(page)
+            if next_offset >= len(filtered):
+                next_offset = 0
+            return {"courses": page, "nextoffset": next_offset}
+
+        self.client.ajax = fake_ajax
+
+    def test_large_course_list_is_paginated(self):
+        first = self.client.list_courses()
+        second = self.client.list_courses(offset=first["naechster_offset"])
+        third = self.client.list_courses(offset=second["naechster_offset"])
+
+        self.assertEqual(len(first["kurse"]), 25)
+        self.assertEqual(first["naechster_offset"], 25)
+        self.assertEqual(len(second["kurse"]), 25)
+        self.assertEqual(second["naechster_offset"], 50)
+        self.assertEqual(len(third["kurse"]), 10)
+        self.assertFalse(third["weitere_vorhanden"])
+        self.assertIsNone(third["naechster_offset"])
+
+    def test_search_is_sent_to_moodle_and_result_is_compact(self):
+        result = self.client.list_courses(search="Course 42", limit=10)
+
+        self.assertEqual(result["anzahl"], 1)
+        self.assertEqual(result["kurse"][0]["id"], 42)
+        self.assertNotIn("summary", result["kurse"][0])
+        _, args = self.ajax_calls[-1]
+        self.assertEqual(args["searchvalue"], "Course 42")
+        self.assertEqual(args["limit"], 10)
+
+    def test_invalid_pagination_is_rejected(self):
+        with self.assertRaises(ValueError):
+            self.client.list_courses(limit=0)
+        with self.assertRaises(ValueError):
+            self.client.list_courses(limit=101)
+        with self.assertRaises(ValueError):
+            self.client.list_courses(offset=-1)
+
+
+class MoodleCourseHtmlFallbackTests(unittest.TestCase):
+    def test_dashboard_fallback_is_filtered_and_paginated(self):
+        client = MoodleSession("https://moodle.example")
+        client.ajax = lambda *_args: (_ for _ in ()).throw(
+            RuntimeError("AJAX unavailable")
+        )
+
+        class Response:
+            text = """
+                <main>
+                  <div data-region="course-content">
+                    <a href="/course/view.php?id=10">Math Basics</a>
+                    <a href="/course/view.php?id=11">Advanced Math</a>
+                    <a href="/course/view.php?id=12">English</a>
+                  </div>
+                </main>
+            """
+
+            @staticmethod
+            def raise_for_status():
+                return None
+
+        client.s.get = lambda *_args, **_kwargs: Response()
+
+        result = client.list_courses(search="math", limit=1, offset=1)
+
+        self.assertEqual(result["quelle"], "HTML-Fallback (Meine Kurse/Dashboard)")
+        self.assertEqual(result["anzahl"], 1)
+        self.assertEqual(result["kurse"][0]["id"], 11)
+        self.assertFalse(result["weitere_vorhanden"])
+
+
+if __name__ == "__main__":
+    unittest.main()