moodle-study-kit 0.1.0__tar.gz

moodle_study_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yamin Mushtaq
+
+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.

moodle_study_kit-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src *.py
+exclude moodleplan.md
+exclude BUGS-ONBOARDING.md

moodle_study_kit-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: moodle-study-kit
+Version: 0.1.0
+Summary: Read-only Moodle toolkit for agents, MCP servers, and local scripts
+License-Expression: MIT
+Keywords: moodle,lms,education,study,mcp
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pdf
+Requires-Dist: pymupdf>=1.23; extra == "pdf"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pymupdf>=1.23; extra == "dev"
+Dynamic: license-file
+
+# moodle-study-kit
+
+Read-only Moodle toolkit for students and agents. Provides a Python library, CLI, and MCP server for accessing Moodle course data without any write operations.
+
+## Quick start
+
+```bash
+# Clone and install
+git clone <repo-url> && cd moodle-study-kit
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+**Windows note:** If `moodle-study` is not recognised after installation, the Python
+Scripts folder isn't on your PATH. Either:
+
+1. Add it manually — find the path with:
+   ```
+   py -c "import site; print(site.getUserSitePackages())"
+   ```
+   Then add it to your PATH in **Windows Settings > System > Environment Variables**.
+
+2. OR use the module form as a workaround (works immediately, no PATH needed):
+   ```
+   py -m moodle_study_kit.cli courses
+   ```
+
+```bash
+# Run guided setup
+moodle-study setup
+```
+
+The setup command will prompt for your Moodle URL, API token, and user ID, then verify the connection and save credentials to `~/.config/moodle-study-kit/config.json`.
+
+## Getting a Moodle API token
+
+1. Log in to your Moodle site in a browser.
+2. Go to **Site administration > Plugins > Web services > Manage tokens**, or ask your Moodle admin for a web-service token.
+3. If your institution uses the **Moodle mobile app**, you may already have a token. Check your Moodle mobile app settings or use the Moodle mobile web-service endpoint:
+   ```
+   https://<your-moodle>/login/token.php?username=YOUR_USER&password=YOUR_PASS&service=moodle_mobile_app
+   ```
+   **Note:** Only use this over HTTPS. Never share your token.
+4. Copy the token for use in setup.
+
+## Configuration
+
+Credentials are resolved in this order:
+
+1. **Explicit arguments** passed to `MoodleConfig.load(url=..., token=...)`
+2. **Environment variables**: `MOODLE_URL`, `MOODLE_TOKEN`, `MOODLE_USERID`
+3. **Config file** (first found):
+   - `$MOODLE_CREDS_PATH` (if set)
+   - `~/.config/moodle-study-kit/config.json`
+   - `~/.moodle_creds.json`
+
+### Config file format
+
+```json
+{
+  "url": "https://moodle.example.ac.uk",
+  "token": "your_token_here",
+  "userid": 12345
+}
+```
+
+### Environment variables
+
+```bash
+export MOODLE_URL="https://moodle.example.ac.uk"
+export MOODLE_TOKEN="your_token_here"
+export MOODLE_USERID="12345"
+```
+
+## CLI usage
+
+```
+moodle-study courses              # List enrolled courses
+moodle-study deadlines            # Show upcoming deadlines (14-day window)
+moodle-study deadlines --days 7   # Shorter look-ahead
+moodle-study contents 12345       # Show sections for course ID 12345
+moodle-study contents EC100       # Look up by course short-code
+moodle-study contents MG488       # Prefix match: finds MG488_2526 if unique
+moodle-study materials EC100      # Discover all downloadable materials
+moodle-study materials EC100 --week 3   # Materials for week 3 only
+moodle-study setup                # Guided first-time setup
+```
+
+Add `--json` before the command for machine-readable JSON output:
+
+```
+moodle-study --json courses
+moodle-study --json deadlines
+```
+
+## MCP server
+
+For use with Claude Code, OpenClaw, or other MCP-capable agents:
+
+```bash
+pip install -e "moodle-study-kit[mcp]"
+python -m moodle_study_kit.mcp_server
+```
+
+The server runs as a stdio-based MCP server. Tools: `list_courses`, `get_deadlines`, `get_course_contents`, `get_week_materials`, `search_course_content`, `get_weekly_summary`.
+
+**Claude Code**: Add to your Claude Code settings / MCP Servers config:
+```json
+{
+  "mcpServers": {
+    "moodle-study-kit": {
+      "command": "python",
+      "args": ["-m", "moodle_study_kit.mcp_server"]
+    }
+  }
+}
+```
+Set `MOODLE_URL`, `MOODLE_TOKEN`, `MOODLE_USERID` as environment variables or in `~/.config/moodle-study-kit/config.json`.
+
+**OpenClaw**: Add to your agent or gateway config:
+```yaml
+mcpServers:
+  moodle:
+    command: python
+    args: ["-m", "moodle_study_kit.mcp_server"]
+    env:
+      MOODLE_URL: "https://your-moodle.example.ac.uk"
+      MOODLE_TOKEN: "your_token_here"
+      MOODLE_USERID: "12345"
+```
+
+## Running tests
+
+```bash
+pip install -e '.[dev]'
+pytest
+
+# On Windows, if pytest isn't found on PATH:
+py -m pytest
+```
+
+## Safety
+
+This package is **read-only by design**. Every Moodle API call is checked against a hardcoded allowlist in `ALLOWED_FUNCTIONS` inside the client module. Write-like operations — submitting assignments, posting forum replies, uploading files, creating events, deleting content — are blocked with a `SafetyError` before any network request is made.
+
+- Your token cannot modify anything on Moodle, even accidentally.
+- Agents (Claude Code, OpenClaw, etc.) can use these tools safely.
+- Treat your Moodle API token like a password: never commit it to git, never share it, use HTTPS only.
+
+### Known limitations
+
+- **Token portability varies by institution.** Some Moodle instances require specific web-service configurations. Check with your Moodle administrator about enabling REST web services.
+- **Rate limiting.** Moodle servers may throttle rapid API calls. The package handles errors gracefully but cannot bypass institutional limits.
+- **Only Moodle REST API v2 is supported.**
+- **Course discovery by short-code uses prefix matching** (e.g. "MG488" matches "MG488_2526") — see CLI usage above.
+
+## For Agent Authors
+
+moodle-study-kit is designed to be agent-friendly:
+
+- Zero configuration needed for discovery — call `list_courses()` with no arguments to explore.
+- Self-documenting tool names and clear purpose descriptions.
+- Structured output by default — use `--json` on CLI, or rely on structured dict/JSON from the Python API.
+- Graceful degradation with clear error messages when credentials are missing.
+
+Example integration in an agent system prompt:
+```
+You have access to moodle-study-kit. First run list_courses() to see available courses, then get_deadlines() to check upcoming work, then explore specific courses with get_course_contents().
+```

moodle_study_kit-0.1.0/README.md

@@ -0,0 +1,169 @@
+# moodle-study-kit
+
+Read-only Moodle toolkit for students and agents. Provides a Python library, CLI, and MCP server for accessing Moodle course data without any write operations.
+
+## Quick start
+
+```bash
+# Clone and install
+git clone <repo-url> && cd moodle-study-kit
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+**Windows note:** If `moodle-study` is not recognised after installation, the Python
+Scripts folder isn't on your PATH. Either:
+
+1. Add it manually — find the path with:
+   ```
+   py -c "import site; print(site.getUserSitePackages())"
+   ```
+   Then add it to your PATH in **Windows Settings > System > Environment Variables**.
+
+2. OR use the module form as a workaround (works immediately, no PATH needed):
+   ```
+   py -m moodle_study_kit.cli courses
+   ```
+
+```bash
+# Run guided setup
+moodle-study setup
+```
+
+The setup command will prompt for your Moodle URL, API token, and user ID, then verify the connection and save credentials to `~/.config/moodle-study-kit/config.json`.
+
+## Getting a Moodle API token
+
+1. Log in to your Moodle site in a browser.
+2. Go to **Site administration > Plugins > Web services > Manage tokens**, or ask your Moodle admin for a web-service token.
+3. If your institution uses the **Moodle mobile app**, you may already have a token. Check your Moodle mobile app settings or use the Moodle mobile web-service endpoint:
+   ```
+   https://<your-moodle>/login/token.php?username=YOUR_USER&password=YOUR_PASS&service=moodle_mobile_app
+   ```
+   **Note:** Only use this over HTTPS. Never share your token.
+4. Copy the token for use in setup.
+
+## Configuration
+
+Credentials are resolved in this order:
+
+1. **Explicit arguments** passed to `MoodleConfig.load(url=..., token=...)`
+2. **Environment variables**: `MOODLE_URL`, `MOODLE_TOKEN`, `MOODLE_USERID`
+3. **Config file** (first found):
+   - `$MOODLE_CREDS_PATH` (if set)
+   - `~/.config/moodle-study-kit/config.json`
+   - `~/.moodle_creds.json`
+
+### Config file format
+
+```json
+{
+  "url": "https://moodle.example.ac.uk",
+  "token": "your_token_here",
+  "userid": 12345
+}
+```
+
+### Environment variables
+
+```bash
+export MOODLE_URL="https://moodle.example.ac.uk"
+export MOODLE_TOKEN="your_token_here"
+export MOODLE_USERID="12345"
+```
+
+## CLI usage
+
+```
+moodle-study courses              # List enrolled courses
+moodle-study deadlines            # Show upcoming deadlines (14-day window)
+moodle-study deadlines --days 7   # Shorter look-ahead
+moodle-study contents 12345       # Show sections for course ID 12345
+moodle-study contents EC100       # Look up by course short-code
+moodle-study contents MG488       # Prefix match: finds MG488_2526 if unique
+moodle-study materials EC100      # Discover all downloadable materials
+moodle-study materials EC100 --week 3   # Materials for week 3 only
+moodle-study setup                # Guided first-time setup
+```
+
+Add `--json` before the command for machine-readable JSON output:
+
+```
+moodle-study --json courses
+moodle-study --json deadlines
+```
+
+## MCP server
+
+For use with Claude Code, OpenClaw, or other MCP-capable agents:
+
+```bash
+pip install -e "moodle-study-kit[mcp]"
+python -m moodle_study_kit.mcp_server
+```
+
+The server runs as a stdio-based MCP server. Tools: `list_courses`, `get_deadlines`, `get_course_contents`, `get_week_materials`, `search_course_content`, `get_weekly_summary`.
+
+**Claude Code**: Add to your Claude Code settings / MCP Servers config:
+```json
+{
+  "mcpServers": {
+    "moodle-study-kit": {
+      "command": "python",
+      "args": ["-m", "moodle_study_kit.mcp_server"]
+    }
+  }
+}
+```
+Set `MOODLE_URL`, `MOODLE_TOKEN`, `MOODLE_USERID` as environment variables or in `~/.config/moodle-study-kit/config.json`.
+
+**OpenClaw**: Add to your agent or gateway config:
+```yaml
+mcpServers:
+  moodle:
+    command: python
+    args: ["-m", "moodle_study_kit.mcp_server"]
+    env:
+      MOODLE_URL: "https://your-moodle.example.ac.uk"
+      MOODLE_TOKEN: "your_token_here"
+      MOODLE_USERID: "12345"
+```
+
+## Running tests
+
+```bash
+pip install -e '.[dev]'
+pytest
+
+# On Windows, if pytest isn't found on PATH:
+py -m pytest
+```
+
+## Safety
+
+This package is **read-only by design**. Every Moodle API call is checked against a hardcoded allowlist in `ALLOWED_FUNCTIONS` inside the client module. Write-like operations — submitting assignments, posting forum replies, uploading files, creating events, deleting content — are blocked with a `SafetyError` before any network request is made.
+
+- Your token cannot modify anything on Moodle, even accidentally.
+- Agents (Claude Code, OpenClaw, etc.) can use these tools safely.
+- Treat your Moodle API token like a password: never commit it to git, never share it, use HTTPS only.
+
+### Known limitations
+
+- **Token portability varies by institution.** Some Moodle instances require specific web-service configurations. Check with your Moodle administrator about enabling REST web services.
+- **Rate limiting.** Moodle servers may throttle rapid API calls. The package handles errors gracefully but cannot bypass institutional limits.
+- **Only Moodle REST API v2 is supported.**
+- **Course discovery by short-code uses prefix matching** (e.g. "MG488" matches "MG488_2526") — see CLI usage above.
+
+## For Agent Authors
+
+moodle-study-kit is designed to be agent-friendly:
+
+- Zero configuration needed for discovery — call `list_courses()` with no arguments to explore.
+- Self-documenting tool names and clear purpose descriptions.
+- Structured output by default — use `--json` on CLI, or rely on structured dict/JSON from the Python API.
+- Graceful degradation with clear error messages when credentials are missing.
+
+Example integration in an agent system prompt:
+```
+You have access to moodle-study-kit. First run list_courses() to see available courses, then get_deadlines() to check upcoming work, then explore specific courses with get_course_contents().
+```

moodle_study_kit-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moodle-study-kit"
+version = "0.1.0"
+description = "Read-only Moodle toolkit for agents, MCP servers, and local scripts"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+keywords = ["moodle", "lms", "education", "study", "mcp"]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Education",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pdf = ["pymupdf>=1.23"]
+mcp = ["mcp>=1.0"]
+dev = ["pytest>=7.0", "pymupdf>=1.23"]
+
+[project.scripts]
+moodle-study = "moodle_study_kit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

moodle_study_kit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moodle_study_kit-0.1.0/src/moodle_study_kit/__init__.py

@@ -0,0 +1,65 @@
+"""moodle-study-kit — Read-only Moodle toolkit."""
+
+from moodle_study_kit.client import (
+    ALLOWED_FUNCTIONS,
+    BLOCKED_PATTERNS,
+    MoodleClient,
+    MoodleWriteAttemptError,
+)
+from moodle_study_kit.config import DEFAULT_CONFIG_PATH, MoodleConfig, test_connection
+from moodle_study_kit.deadlines import get_upcoming_deadlines
+from moodle_study_kit.extraction import (
+    FILE_PRIORITY,
+    SUPPORTED_EXTENSIONS,
+    clean_text,
+    extract_file_text,
+    is_boilerplate,
+    strip_html,
+)
+from moodle_study_kit.materials import (
+    extract_materials,
+    get_section_materials,
+    match_section,
+    search_course_content,
+)
+from moodle_study_kit.summaries import (
+    build_deterministic_summary,
+    build_summary,
+    classify_section,
+    fallback_bullets,
+    find_best_section,
+    format_bullets,
+    get_downloadable_files,
+    score_section_match,
+    summarize_modules,
+)
+
+__all__ = [
+    "ALLOWED_FUNCTIONS",
+    "BLOCKED_PATTERNS",
+    "DEFAULT_CONFIG_PATH",
+    "FILE_PRIORITY",
+    "MoodleClient",
+    "MoodleConfig",
+    "MoodleWriteAttemptError",
+    "SUPPORTED_EXTENSIONS",
+    "build_deterministic_summary",
+    "build_summary",
+    "classify_section",
+    "clean_text",
+    "extract_file_text",
+    "extract_materials",
+    "fallback_bullets",
+    "find_best_section",
+    "format_bullets",
+    "get_downloadable_files",
+    "get_section_materials",
+    "get_upcoming_deadlines",
+    "is_boilerplate",
+    "match_section",
+    "score_section_match",
+    "search_course_content",
+    "strip_html",
+    "summarize_modules",
+    "test_connection",
+]