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().
```
