mcp-moodle 0.1.0__tar.gz

mcp_moodle-0.1.0/.env.example

@@ -0,0 +1,2 @@
+MOODLE_URL=https://moodle.epita.fr
+MOODLE_TOKEN=

mcp_moodle-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-moodle
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_moodle-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+.env.local
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+*.token
+dist/
+build/
+*.egg-info/

mcp_moodle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arthur Lefebvre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_moodle-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: mcp-moodle
+Version: 0.1.0
+Summary: MCP server exposing Moodle Web Services to AI assistants (Claude, Cursor, etc.)
+Project-URL: Homepage, https://github.com/Snaw80/moodle-mcp
+Project-URL: Repository, https://github.com/Snaw80/moodle-mcp
+Project-URL: Issues, https://github.com/Snaw80/moodle-mcp/issues
+Author-email: Arthur Lefebvre <arthurloup.lefebvre@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,llm,mcp,moodle
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.2.0
+Provides-Extra: token
+Requires-Dist: playwright>=1.40; extra == 'token'
+Description-Content-Type: text/markdown
+
+# mcp-moodle
+
+An [MCP](https://modelcontextprotocol.io) server that exposes
+[Moodle Web Services](https://docs.moodle.org/dev/Web_services) to any
+MCP-compatible AI assistant — Claude Code, Claude Desktop, Cursor, Codex,
+and others.
+
+Ask your assistant things like _"what's due this week?"_, _"list my courses"_,
+_"download the slides from CS101 week 3"_ — without leaving the chat.
+
+## Features
+
+- **`site_info`** — verify the token and get the authenticated user
+- **`list_my_courses`** — courses you're enrolled in
+- **`get_course_contents`** — sections, modules, file URLs
+- **`search_courses`** — search the public catalog
+- **`list_assignments`** — assignments across one or all courses
+- **`upcoming_events`** — calendar deadlines and sessions
+- **`get_user_grades`** — your grades for a course
+- **`download_file`** — save any Moodle file locally (token appended automatically)
+
+Works with any Moodle 3.5+ instance that has Web Services enabled.
+
+## Install
+
+The recommended way is [`uv`](https://docs.astral.sh/uv/) — no virtualenv to manage:
+
+```bash
+# One-off run (no install)
+uvx mcp-moodle
+
+# Or persist as a tool
+uv tool install mcp-moodle
+```
+
+Plain pip works too:
+
+```bash
+pip install mcp-moodle
+```
+
+## Get a token
+
+Moodle Web Services require a personal token. The package ships a helper that
+handles every common login flow — native accounts, SSO (Microsoft, Google,
+SAML, OAuth), or manual paste:
+
+```bash
+# Default: opens a Chromium window, you complete SSO, token is captured
+uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org
+
+# Native (non-SSO) account
+uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org \
+  --method local --user jdoe
+
+# Headless server fallback (paste the moodlemobile:// URL by hand)
+uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org \
+  --method manual-mobile
+```
+
+The token is written to `./.env` (chmod 600) as `MOODLE_URL` and `MOODLE_TOKEN`.
+Pass `--stdout` to print it to stdout instead.
+
+> The `[token]` extra pulls in Playwright. First run downloads Chromium
+> (~150 MB, one-time). Skip the extra if you only ever use `--method local`,
+> `--method web`, or `--method manual-mobile`.
+
+## Configure your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add moodle \
+  --env MOODLE_URL=https://moodle.example.org \
+  --env MOODLE_TOKEN=your_token_here \
+  -- uvx mcp-moodle
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "moodle": {
+      "command": "uvx",
+      "args": ["mcp-moodle"],
+      "env": {
+        "MOODLE_URL": "https://moodle.example.org",
+        "MOODLE_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor / other clients
+
+Any MCP client that supports stdio servers works the same way: command
+`uvx`, args `["mcp-moodle"]`, env `MOODLE_URL` and `MOODLE_TOKEN`.
+
+## Verify it works
+
+In your MCP client, ask: _"call the moodle site_info tool"_. You should see
+your name, username, and the site URL.
+
+## Development
+
+```bash
+git clone git@github.com:Snaw80/moodle-mcp.git
+cd moodle-mcp
+uv sync --all-extras
+uv run mcp-moodle
+```
+
+## Security notes
+
+- Your token is the equivalent of a password for Moodle Web Services — keep
+  `.env` out of version control (the included `.gitignore` already does this).
+- The server reads `MOODLE_TOKEN` from the environment and never logs it.
+- `download_file` appends the token to the URL; that URL is not logged either,
+  but be mindful if your client echoes tool arguments.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_moodle-0.1.0/README.md

@@ -0,0 +1,128 @@
+# mcp-moodle
+
+An [MCP](https://modelcontextprotocol.io) server that exposes
+[Moodle Web Services](https://docs.moodle.org/dev/Web_services) to any
+MCP-compatible AI assistant — Claude Code, Claude Desktop, Cursor, Codex,
+and others.
+
+Ask your assistant things like _"what's due this week?"_, _"list my courses"_,
+_"download the slides from CS101 week 3"_ — without leaving the chat.
+
+## Features
+
+- **`site_info`** — verify the token and get the authenticated user
+- **`list_my_courses`** — courses you're enrolled in
+- **`get_course_contents`** — sections, modules, file URLs
+- **`search_courses`** — search the public catalog
+- **`list_assignments`** — assignments across one or all courses
+- **`upcoming_events`** — calendar deadlines and sessions
+- **`get_user_grades`** — your grades for a course
+- **`download_file`** — save any Moodle file locally (token appended automatically)
+
+Works with any Moodle 3.5+ instance that has Web Services enabled.
+
+## Install
+
+The recommended way is [`uv`](https://docs.astral.sh/uv/) — no virtualenv to manage:
+
+```bash
+# One-off run (no install)
+uvx mcp-moodle
+
+# Or persist as a tool
+uv tool install mcp-moodle
+```
+
+Plain pip works too:
+
+```bash
+pip install mcp-moodle
+```
+
+## Get a token
+
+Moodle Web Services require a personal token. The package ships a helper that
+handles every common login flow — native accounts, SSO (Microsoft, Google,
+SAML, OAuth), or manual paste:
+
+```bash
+# Default: opens a Chromium window, you complete SSO, token is captured
+uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org
+
+# Native (non-SSO) account
+uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org \
+  --method local --user jdoe
+
+# Headless server fallback (paste the moodlemobile:// URL by hand)
+uvx --from "mcp-moodle[token]" mcp-moodle-token https://moodle.example.org \
+  --method manual-mobile
+```
+
+The token is written to `./.env` (chmod 600) as `MOODLE_URL` and `MOODLE_TOKEN`.
+Pass `--stdout` to print it to stdout instead.
+
+> The `[token]` extra pulls in Playwright. First run downloads Chromium
+> (~150 MB, one-time). Skip the extra if you only ever use `--method local`,
+> `--method web`, or `--method manual-mobile`.
+
+## Configure your MCP client
+
+### Claude Code
+
+```bash
+claude mcp add moodle \
+  --env MOODLE_URL=https://moodle.example.org \
+  --env MOODLE_TOKEN=your_token_here \
+  -- uvx mcp-moodle
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "moodle": {
+      "command": "uvx",
+      "args": ["mcp-moodle"],
+      "env": {
+        "MOODLE_URL": "https://moodle.example.org",
+        "MOODLE_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor / other clients
+
+Any MCP client that supports stdio servers works the same way: command
+`uvx`, args `["mcp-moodle"]`, env `MOODLE_URL` and `MOODLE_TOKEN`.
+
+## Verify it works
+
+In your MCP client, ask: _"call the moodle site_info tool"_. You should see
+your name, username, and the site URL.
+
+## Development
+
+```bash
+git clone git@github.com:Snaw80/moodle-mcp.git
+cd moodle-mcp
+uv sync --all-extras
+uv run mcp-moodle
+```
+
+## Security notes
+
+- Your token is the equivalent of a password for Moodle Web Services — keep
+  `.env` out of version control (the included `.gitignore` already does this).
+- The server reads `MOODLE_TOKEN` from the environment and never logs it.
+- `download_file` appends the token to the URL; that URL is not logged either,
+  but be mindful if your client echoes tool arguments.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_moodle-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-moodle"
+version = "0.1.0"
+description = "MCP server exposing Moodle Web Services to AI assistants (Claude, Cursor, etc.)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Arthur Lefebvre", email = "arthurloup.lefebvre@gmail.com" }]
+keywords = ["mcp", "moodle", "claude", "ai", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Education",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Education",
+]
+dependencies = [
+  "mcp[cli]>=1.2.0",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+token = ["playwright>=1.40"]
+
+[project.scripts]
+mcp-moodle = "moodle_mcp.server:main"
+mcp-moodle-token = "moodle_mcp.get_token:main"
+
+[project.urls]
+Homepage = "https://github.com/Snaw80/moodle-mcp"
+Repository = "https://github.com/Snaw80/moodle-mcp"
+Issues = "https://github.com/Snaw80/moodle-mcp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/moodle_mcp"]

mcp_moodle-0.1.0/src/moodle_mcp/get_token.py

@@ -0,0 +1,393 @@
+"""Fetch a Moodle Web Services token via one of several methods.
+
+Methods:
+  local          POST login/token.php with username/password.
+                 Works for native Moodle accounts. Fails on SSO-only sites.
+  web            Open user/managetoken.php in the browser. After SSO login,
+                 copy the displayed token. Best for SSO sites that allow
+                 users to self-serve tokens. Fragile: some Moodle themes
+                 show a non-API field that looks like a valid token.
+  mobile         Default. Launches a Playwright-controlled Chromium, you
+                 complete SSO inside it, and the moodlemobile:// redirect
+                 is captured at the network level. Verifies the signature
+                 against md5(wwwroot + passport). Works with Microsoft
+                 Azure AD, Google, SAML, OAuth — any real-browser SSO.
+                 First run downloads Chromium (~150MB, one-time).
+  manual-mobile  Same flow but in your default browser; you paste the
+                 resulting moodlemobile:// URL by hand. Fallback when
+                 Playwright can't run (e.g. headless server, no GUI).
+
+By default the token is written to ./.env (chmod 600) and only a masked
+preview is shown. Pass --stdout to print the full token instead (for use
+in pipes/redirects); never let it land in scrollback.
+
+Usage:
+  mcp-moodle-token https://moodle.example.org
+  mcp-moodle-token https://moodle.example.org --method web
+  mcp-moodle-token https://moodle.example.org --method local --user jdoe
+  mcp-moodle-token https://moodle.example.org --method manual-mobile
+  mcp-moodle-token https://moodle.example.org --env-file path/.env
+  mcp-moodle-token https://moodle.example.org --stdout > my-token.txt
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import getpass
+import hashlib
+import re
+import secrets
+import sys
+import webbrowser
+from pathlib import Path
+
+import httpx
+
+_MOODLEMOBILE_RE = re.compile(r"moodlemobile://token=([A-Za-z0-9+/=]+)")
+
+
+def _decode_payload(b64: str) -> tuple[str | None, str | None]:
+    """Decode a moodlemobile token payload into (signature, token)."""
+    try:
+        decoded = base64.b64decode(b64).decode("utf-8", errors="replace")
+    except Exception as e:
+        print(f"  Base64 decode failed: {e}", file=sys.stderr)
+        return None, None
+    parts = decoded.split(":::")
+    if len(parts) < 2:
+        print(f"  Unexpected payload: {decoded[:80]}", file=sys.stderr)
+        return None, None
+    return parts[0], parts[1]
+
+
+def _verify_signature(signature: str, base: str, passport: str) -> bool:
+    """Moodle signs the response with md5(wwwroot + passport)."""
+    expected = hashlib.md5(f"{base}{passport}".encode()).hexdigest()
+    return signature == expected
+
+
+def method_local(base: str, username: str | None) -> str | None:
+    if username is None:
+        username = input("  Username: ").strip()
+    password = getpass.getpass("  Password: ")
+    try:
+        r = httpx.post(
+            f"{base}/login/token.php",
+            data={
+                "username": username,
+                "password": password,
+                "service": "moodle_mobile_app",
+            },
+            timeout=30.0,
+        )
+        r.raise_for_status()
+        data = r.json()
+    except httpx.HTTPError as e:
+        print(f"  HTTP error: {e}", file=sys.stderr)
+        return None
+
+    if "token" in data:
+        return data["token"]
+    err = data.get("errorcode") or data.get("error") or data
+    print(f"  Rejected: {err}", file=sys.stderr)
+    return None
+
+
+def method_web(base: str) -> str | None:
+    url = f"{base}/user/managetoken.php"
+    print(f"  Opening {url}")
+    print("  Complete SSO if prompted, then look under 'Moodle mobile web")
+    print("  service' (or similar). Copy the token and paste it below.")
+    try:
+        webbrowser.open(url)
+    except Exception:
+        pass
+    token = getpass.getpass("  Paste token (hidden, empty to skip): ").strip()
+    return token or None
+
+
+def _ensure_playwright_chromium() -> bool:
+    """Install Playwright's Chromium binary on demand, once."""
+    import subprocess
+
+    print(
+        "  Playwright's Chromium isn't installed yet.",
+        "  Installing now (~150MB, one-time)…",
+        sep="\n",
+        file=sys.stderr,
+    )
+    result = subprocess.run(
+        [sys.executable, "-m", "playwright", "install", "chromium"],
+        capture_output=False,
+    )
+    return result.returncode == 0
+
+
+def method_mobile(base: str) -> str | None:
+    """Launch a Playwright-controlled Chromium, auto-capture token.
+
+    Plain pywebview-style approaches stall inside Microsoft Azure AD's
+    auto-form-submit step (third-party cookies and SSO JS quirks). A real
+    Chromium instance driven by Playwright handles every common SSO
+    provider, and Playwright lets us intercept the moodlemobile:// URL
+    at the network-request layer regardless of whether Moodle emits a
+    server-side 303 or a JS-based redirect.
+    """
+    try:
+        from playwright.sync_api import (  # type: ignore
+            Error as PlaywrightError,
+            sync_playwright,
+        )
+    except ImportError as e:
+        print(
+            f"  playwright not available ({e}).",
+            "  Use --method manual-mobile, or run:",
+            "    pip install playwright && playwright install chromium",
+            sep="\n",
+            file=sys.stderr,
+        )
+        return None
+
+    import time
+
+    passport = secrets.token_hex(16)
+    launch = (
+        f"{base}/admin/tool/mobile/launch.php"
+        f"?service=moodle_mobile_app&passport={passport}&urlscheme=moodlemobile"
+    )
+
+    captured: dict[str, str | None] = {"url": None}
+
+    print(f"  Launching Chromium (passport: {passport[:8]}…).")
+    print("  Complete SSO in the window that opens. It will close itself")
+    print("  the moment the moodlemobile:// redirect fires.")
+
+    try:
+        with sync_playwright() as p:
+            try:
+                browser = p.chromium.launch(headless=False)
+            except PlaywrightError as e:
+                msg = str(e)
+                if "Executable doesn't exist" in msg or "playwright install" in msg:
+                    if not _ensure_playwright_chromium():
+                        print("  Chromium install failed.", file=sys.stderr)
+                        return None
+                    browser = p.chromium.launch(headless=False)
+                else:
+                    raise
+
+            context = browser.new_context()
+            page = context.new_page()
+
+            def on_request(request):
+                if captured["url"]:
+                    return
+                if request.url.startswith("moodlemobile://"):
+                    captured["url"] = request.url
+
+            def on_response(response):
+                # Some Moodle versions emit a server-side 303 instead of JS.
+                # The Location header carries the moodlemobile URL.
+                if captured["url"]:
+                    return
+                if 300 <= response.status < 400:
+                    loc = response.headers.get("location", "")
+                    if loc.startswith("moodlemobile://"):
+                        captured["url"] = loc
+
+            page.on("request", on_request)
+            page.on("response", on_response)
+
+            try:
+                page.goto(launch, wait_until="domcontentloaded")
+            except PlaywrightError:
+                # Goto can raise once Chromium hits moodlemobile:// — ignore.
+                pass
+
+            deadline = time.time() + 300
+            last_url = None
+            while time.time() < deadline and captured["url"] is None:
+                if page.is_closed():
+                    print("  Window closed before SSO finished.", file=sys.stderr)
+                    break
+                try:
+                    current = page.url
+                except PlaywrightError:
+                    current = ""
+                if current and current != last_url:
+                    shown = current.split("?", 1)[0]
+                    print(
+                        f"  [{time.strftime('%H:%M:%S')}] page: {shown[:90]}",
+                        file=sys.stderr,
+                    )
+                    last_url = current
+                # Secondary path: scrape the DOM for a JS-emitted URL.
+                if not captured["url"]:
+                    try:
+                        m = _MOODLEMOBILE_RE.search(page.content())
+                        if m:
+                            captured["url"] = f"moodlemobile://token={m.group(1)}"
+                    except PlaywrightError:
+                        pass
+                page.wait_for_timeout(400)
+
+            try:
+                browser.close()
+            except Exception:
+                pass
+    except Exception as e:
+        print(f"  Playwright error: {e}", file=sys.stderr)
+        return None
+
+    raw = captured["url"]
+    if not raw:
+        print(
+            "  Timed out without capturing a token.",
+            "  Re-run with --method manual-mobile as a fallback.",
+            sep="\n",
+            file=sys.stderr,
+        )
+        return None
+
+    if "token=" not in raw:
+        print(f"  Unexpected capture: {raw[:80]}", file=sys.stderr)
+        return None
+
+    b64 = raw.split("token=", 1)[1].split("&", 1)[0].split("#", 1)[0]
+    signature, token = _decode_payload(b64)
+    if not token:
+        return None
+    if signature and not _verify_signature(signature, base, passport):
+        print(
+            f"  WARNING: signature mismatch (got {signature[:8]}…). "
+            "Token captured but origin not verified — refusing.",
+            file=sys.stderr,
+        )
+        return None
+    return token
+
+
+def method_manual_mobile(base: str) -> str | None:
+    passport = secrets.token_hex(16)
+    launch = (
+        f"{base}/admin/tool/mobile/launch.php"
+        f"?service=moodle_mobile_app&passport={passport}&urlscheme=moodlemobile"
+    )
+    print(f"  Opening {launch}")
+    print("  Complete SSO. The browser will try to open a moodlemobile://")
+    print("  URL and show an error — that's expected. Copy the full URL")
+    print("  from the address bar (or the error message) and paste below.")
+    try:
+        webbrowser.open(launch)
+    except Exception:
+        pass
+
+    raw = getpass.getpass("  Paste moodlemobile://... URL (hidden): ").strip()
+    if not raw or "token=" not in raw:
+        print("  No token= found in URL", file=sys.stderr)
+        return None
+
+    b64 = raw.split("token=", 1)[1].split("&", 1)[0].split("#", 1)[0]
+    signature, token = _decode_payload(b64)
+    if not token:
+        return None
+    if signature and not _verify_signature(signature, base, passport):
+        print(
+            f"  WARNING: signature mismatch (got {signature[:8]}…). "
+            "Token captured but origin not verified — refusing.",
+            file=sys.stderr,
+        )
+        return None
+    return token
+
+
+def write_env(env_file: Path, base: str, token: str) -> None:
+    env_file = env_file.expanduser().resolve()
+    env_file.parent.mkdir(parents=True, exist_ok=True)
+    preserved: list[str] = []
+    if env_file.exists():
+        for line in env_file.read_text().splitlines():
+            if line.startswith(("MOODLE_URL=", "MOODLE_TOKEN=")):
+                continue
+            preserved.append(line)
+    body = "\n".join(preserved + [f"MOODLE_URL={base}", f"MOODLE_TOKEN={token}"])
+    env_file.write_text(body + "\n")
+    env_file.chmod(0o600)
+    print(f"  Wrote {env_file} (chmod 600)", file=sys.stderr)
+
+
+def mask(token: str) -> str:
+    if len(token) <= 8:
+        return "*" * len(token)
+    return f"{token[:4]}…{token[-4:]} ({len(token)} chars)"
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(
+        description="Fetch a Moodle Web Services token.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("moodle_url", help="e.g. https://moodle.example.org")
+    p.add_argument(
+        "--method",
+        choices=["auto", "local", "web", "mobile", "manual-mobile"],
+        default="auto",
+        help=(
+            "auto: 'local' (if --user given) → 'mobile' (Playwright Chromium). "
+            "'mobile' is the cross-SSO default."
+        ),
+    )
+    p.add_argument("--user", help="Username (enables auto-trying 'local').")
+    p.add_argument(
+        "--env-file",
+        type=Path,
+        default=Path(".env"),
+        help="Where to write MOODLE_URL/MOODLE_TOKEN (default: ./.env, chmod 600).",
+    )
+    p.add_argument(
+        "--stdout",
+        action="store_true",
+        help="Print the raw token to stdout instead of writing a file.",
+    )
+    args = p.parse_args()
+
+    base = args.moodle_url.rstrip("/")
+
+    if args.method == "auto":
+        methods = (["local"] if args.user else []) + ["mobile"]
+    else:
+        methods = [args.method]
+
+    runners = {
+        "local": lambda: method_local(base, args.user),
+        "web": lambda: method_web(base),
+        "mobile": lambda: method_mobile(base),
+        "manual-mobile": lambda: method_manual_mobile(base),
+    }
+
+    token: str | None = None
+    for i, m in enumerate(methods):
+        print(f"\n→ Method: {m}")
+        token = runners[m]()
+        if token:
+            break
+        if i < len(methods) - 1:
+            ans = input("  Try next method? [Y/n] ").strip().lower()
+            if ans == "n":
+                break
+
+    if not token:
+        print("\nNo token obtained.", file=sys.stderr)
+        return 2
+
+    if args.stdout:
+        print(token)
+    else:
+        write_env(args.env_file, base, token)
+        print(f"  Token: {mask(token)}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcp_moodle-0.1.0/src/moodle_mcp/server.py

@@ -0,0 +1,195 @@
+"""Moodle MCP server.
+
+Exposes Moodle Web Services (REST) as MCP tools. Works with any MCP client
+(Claude Code, Claude Desktop, Codex, Cursor, etc.) over stdio.
+
+Required env vars:
+    MOODLE_URL    e.g. https://moodle.example.org
+    MOODLE_TOKEN  Web Services token (see `mcp-moodle-token`)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("moodle")
+
+
+def _config() -> tuple[str, str]:
+    url = os.environ.get("MOODLE_URL", "").rstrip("/")
+    token = os.environ.get("MOODLE_TOKEN", "")
+    if not url:
+        raise SystemExit("MOODLE_URL env var is required")
+    if not token:
+        raise SystemExit("MOODLE_TOKEN env var is required")
+    return url, token
+
+
+def _flatten(params: dict[str, Any]) -> dict[str, Any]:
+    """Moodle expects PHP-style array params: key[0]=a&key[1]=b."""
+    out: dict[str, Any] = {}
+    for k, v in params.items():
+        if v is None:
+            continue
+        if isinstance(v, list):
+            for i, item in enumerate(v):
+                out[f"{k}[{i}]"] = item
+        else:
+            out[k] = v
+    return out
+
+
+async def _call(fn: str, **params: Any) -> Any:
+    url, token = _config()
+    payload = {
+        "wstoken": token,
+        "wsfunction": fn,
+        "moodlewsrestformat": "json",
+        **_flatten(params),
+    }
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        r = await client.post(f"{url}/webservice/rest/server.php", data=payload)
+        r.raise_for_status()
+        data = r.json()
+        if isinstance(data, dict) and data.get("exception"):
+            raise RuntimeError(
+                f"Moodle error: {data.get('message')} ({data.get('errorcode')})"
+            )
+        return data
+
+
+@mcp.tool()
+async def site_info() -> dict:
+    """Return Moodle site info and the authenticated user's id/username.
+
+    Use this first to verify the token works.
+    """
+    return await _call("core_webservice_get_site_info")
+
+
+@mcp.tool()
+async def list_my_courses() -> list[dict]:
+    """List courses the authenticated user is enrolled in.
+
+    Returns id, shortname, fullname, category id, and visibility.
+    """
+    me = await _call("core_webservice_get_site_info")
+    courses = await _call("core_enrol_get_users_courses", userid=me["userid"])
+    return [
+        {
+            "id": c["id"],
+            "shortname": c.get("shortname"),
+            "fullname": c.get("fullname"),
+            "category": c.get("category"),
+            "visible": c.get("visible", 1),
+        }
+        for c in courses
+    ]
+
+
+@mcp.tool()
+async def get_course_contents(course_id: int) -> list[dict]:
+    """Return sections, modules and file URLs for a course.
+
+    File URLs returned in `contents[].fileurl` require the Moodle token
+    appended as `?token=...` (or use download_file).
+
+    Args:
+        course_id: numeric course id (see list_my_courses)
+    """
+    return await _call("core_course_get_contents", courseid=course_id)
+
+
+@mcp.tool()
+async def search_courses(query: str, page: int = 0, perpage: int = 20) -> dict:
+    """Search the public course catalog by keyword.
+
+    Args:
+        query: search text
+        page: 0-indexed page
+        perpage: results per page (max 100)
+    """
+    return await _call(
+        "core_course_search_courses",
+        criterianame="search",
+        criteriavalue=query,
+        page=page,
+        perpage=perpage,
+    )
+
+
+@mcp.tool()
+async def list_assignments(course_ids: list[int] | None = None) -> dict:
+    """List assignments across given courses (or all enrolled if omitted).
+
+    Args:
+        course_ids: optional list of course ids; omit to use all enrolled
+    """
+    if course_ids is None:
+        me = await _call("core_webservice_get_site_info")
+        courses = await _call("core_enrol_get_users_courses", userid=me["userid"])
+        course_ids = [c["id"] for c in courses]
+    return await _call("mod_assign_get_assignments", courseids=course_ids)
+
+
+@mcp.tool()
+async def upcoming_events(limit: int = 20) -> dict:
+    """Return upcoming calendar events (deadlines, sessions) for the user.
+
+    Args:
+        limit: max number of events to return
+    """
+    return await _call(
+        "core_calendar_get_action_events_by_timesort", limitnum=limit
+    )
+
+
+@mcp.tool()
+async def get_user_grades(course_id: int) -> dict:
+    """Return the authenticated user's grades for a course.
+
+    Args:
+        course_id: numeric course id
+    """
+    me = await _call("core_webservice_get_site_info")
+    return await _call(
+        "gradereport_user_get_grade_items",
+        courseid=course_id,
+        userid=me["userid"],
+    )
+
+
+@mcp.tool()
+async def download_file(file_url: str, save_path: str) -> dict:
+    """Download a Moodle file (from get_course_contents) to a local path.
+
+    The Moodle token is appended automatically. The target directory is
+    created if missing.
+
+    Args:
+        file_url: pluginfile.php URL from a module's `contents[].fileurl`
+        save_path: absolute local path to write the file to
+    """
+    _, token = _config()
+    sep = "&" if "?" in file_url else "?"
+    url = f"{file_url}{sep}token={token}"
+    dest = Path(save_path).expanduser()
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    async with httpx.AsyncClient(timeout=120.0, follow_redirects=True) as client:
+        r = await client.get(url)
+        r.raise_for_status()
+        dest.write_bytes(r.content)
+    return {"saved": str(dest), "bytes": len(r.content)}
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()