monash-study-kit 1.2.0__tar.gz → 1.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/CHANGELOG.md +17 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/PKG-INFO +52 -11
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/README.md +50 -9
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/README.zh-CN.md +50 -8
- monash_study_kit-1.4.0/docs/panels-library-remote.md +143 -0
- monash_study_kit-1.4.0/docs/screenshots/todo.png +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/docs/security.md +15 -4
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/pyproject.toml +1 -1
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/scripts/check_dist.py +2 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/scripts/smoke_test.py +9 -3
- monash_study_kit-1.4.0/skills/monash-study-kit/SKILL.md +65 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/__init__.py +1 -1
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/cli.py +26 -1
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/help_menu.py +13 -0
- monash_study_kit-1.4.0/src/monash_study_kit/library.py +174 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/mcp_server.py +38 -4
- monash_study_kit-1.4.0/src/monash_study_kit/remote.py +530 -0
- monash_study_kit-1.4.0/src/monash_study_kit/ui/panel.html +265 -0
- monash_study_kit-1.4.0/src/monash_study_kit/widgets.py +70 -0
- monash_study_kit-1.4.0/tests/conftest.py +24 -0
- monash_study_kit-1.4.0/tests/test_feature_cli.py +56 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_help_menu.py +12 -1
- monash_study_kit-1.4.0/tests/test_library.py +105 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_mcp.py +3 -3
- monash_study_kit-1.4.0/tests/test_panels.py +88 -0
- monash_study_kit-1.4.0/tests/test_remote.py +418 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_security.py +3 -2
- monash_study_kit-1.4.0/tests/test_skill.py +49 -0
- monash_study_kit-1.2.0/tests/conftest.py +0 -7
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/.github/ISSUE_TEMPLATE/config.yml +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/.github/pull_request_template.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/.github/workflows/release.yml +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/.github/workflows/test.yml +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/.gitignore +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/CODE_OF_CONDUCT.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/CONTRIBUTING.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/LICENSE +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/SECURITY.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/docs/adr/0001-one-shared-core.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/docs/adr/0002-read-only-public-package.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/docs/adr/0003-release-from-a-tag.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/docs/adr/README.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/docs/releasing.md +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/glama.json +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/scripts/measure_tokens.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/__main__.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/browser_login.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/cdp.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/claude_setup.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/cli_ed.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/clients.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/content_index.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/doctor.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/doctor_deep.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/edlib.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/edquery.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/edsync.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/features.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/htmldom.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/jobs.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/lesson_reader.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/lessons.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/moodlelib.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/output.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/paths.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/recordings.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/syncer.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/textextract.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/todo.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/transcribe.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/update_check.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/src/monash_study_kit/webnotes.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_cdp.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_cli.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_clients.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_content_index.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_doctor.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_doctor_deep.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_ed_auth.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_ed_markdown.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_ed_query.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_ed_quiz.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_features.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_layout.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_lesson_reader.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_recordings.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_removed_files.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_setup.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_shared_core.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_sync_robustness.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_todo.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_update_check.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/tests/test_webnotes.py +0 -0
- {monash_study_kit-1.2.0 → monash_study_kit-1.4.0}/uv.lock +0 -0
|
@@ -2,6 +2,23 @@
|
|
|
2
2
|
|
|
3
3
|
Version numbers follow `__version__` in `src/monash_study_kit/__init__.py`: patch for bug fixes, minor for new features.
|
|
4
4
|
|
|
5
|
+
## Unreleased
|
|
6
|
+
|
|
7
|
+
## 1.4.0
|
|
8
|
+
|
|
9
|
+
- Study todo, Ed Lesson progress and quiz practice now include optional MCP Apps panels. Existing tools keep their arguments and text results; clients without panel support still receive text. Quiz selections stay in the panel and are sent to the AI for explanation only, never submitted to Ed.
|
|
10
|
+
- Add `search_moodle_activities` to locate Moodle sections and activities by name, reusing the existing CLI finder. The local catalog has 18 tools; the original 17 names and schemas are unchanged.
|
|
11
|
+
- Add `monash library [--open]`: a loopback-only, read-only browser for registered Moodle and Ed Lesson files. Filter by course, week or filename and download files without an AI client.
|
|
12
|
+
- Add optional single-user `monash remote serve`, `pair`, `clients` and `revoke`. The remote service binds on loopback behind the owner's HTTPS proxy, uses one-time pairing, PKCE and rotating OAuth tokens, and exposes only the 16 query tools. Local login and sync commands cannot be invoked remotely. The server is never started by setup or the default stdio flow.
|
|
13
|
+
- Package the panel HTML in the wheel and test it from a clean installation. No assignment submission, quiz submission, posting, private server settings or hosted service is added.
|
|
14
|
+
|
|
15
|
+
## 1.3.0
|
|
16
|
+
|
|
17
|
+
- Questions about an assignment now follow a fixed order of sources. The Moodle brief and marking rubric come first. On Ed, only replies from teaching staff and answers they endorsed count; other students' replies are leads, not rules. A later staff correction wins, but when the brief and Ed disagree Claude lists both with their dates and suggests asking staff instead of picking one. Every rule it states names where it came from. This is in the server instructions, so it applies without doing anything.
|
|
18
|
+
- New preset prompt "作业要求" (assignment requirements) in the "+" menu: give it an assignment name and it reads the brief, the rubric and staff answers on Ed, and lists what to hand in, how it is marked, deadlines and format, and Ed clarifications, each with its source.
|
|
19
|
+
- Agent skill at `skills/monash-study-kit/SKILL.md`, installable with `npx skills add Waldo0926/monash-study-kit`. It maps questions to `monash` commands, carries the same rule for assignment questions, and lists what the agent must leave to the student (logins, tokens, submitting). A test checks every command in it against the CLI and the exit codes against `EXIT_CODES`.
|
|
20
|
+
- The package author is listed as Waldo.
|
|
21
|
+
|
|
5
22
|
## 1.2.0
|
|
6
23
|
|
|
7
24
|
- `monash connect <client>` connects Study Kit to Codex, Cursor, VS Code, Windsurf or Gemini CLI in one command. It adds only the `monash` entry with the full path to the program, keeps the rest of the config file and saves a backup first. Codex uses `codex mcp add` when the `codex` command is installed. `monash connect` alone lists the clients and whether each is connected, `--print` shows the entry without writing it, and `--remove` takes it out. A config file that isn't plain JSON (for example with comments) is left alone and the entry is printed to paste by hand.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: monash-study-kit
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.4.0
|
|
4
4
|
Summary: Connect Monash Moodle and Ed to Claude via a local MCP server and CLI: deadlines, announcements, grades, full-text search over course materials and Ed posts, all on your own machine.
|
|
5
5
|
Project-URL: Homepage, https://github.com/Waldo0926/monash-study-kit
|
|
6
6
|
Project-URL: Issues, https://github.com/Waldo0926/monash-study-kit/issues
|
|
7
7
|
Project-URL: Changelog, https://github.com/Waldo0926/monash-study-kit/blob/main/CHANGELOG.md
|
|
8
|
-
Author:
|
|
8
|
+
Author: Waldo
|
|
9
9
|
License-Expression: MIT
|
|
10
10
|
License-File: LICENSE
|
|
11
11
|
Keywords: claude,cli,edstem,mcp,model-context-protocol,monash,moodle,study-tools
|
|
@@ -35,6 +35,7 @@ Description-Content-Type: text/markdown
|
|
|
35
35
|
[](https://pypi.org/project/monash-study-kit/)
|
|
36
36
|
[](LICENSE)
|
|
37
37
|
[](#privacy-and-security)
|
|
38
|
+
[](https://docs.secureview.tech/study-kit/)
|
|
38
39
|
|
|
39
40
|
[](https://github.com/Waldo0926/monash-study-kit/actions/workflows/test.yml) [](https://glama.ai/mcp/servers/Waldo0926/monash-study-kit)
|
|
40
41
|
|
|
@@ -47,11 +48,15 @@ Connect Monash **Moodle** and **Ed** to Claude, then just ask Claude:
|
|
|
47
48
|
- "Which week of FIT2102 covered monads? Which slide deck, which page?"
|
|
48
49
|
- "What does the A2 spec ask for?", "What's my current grade in FIT2109?"
|
|
49
50
|
|
|
50
|
-
|
|
51
|
+
By default, everything stays **on your own computer**: course files, login state and the database live locally and never pass through a third-party server.
|
|
51
52
|
All tools are **read-only**: they never submit assignments, attempt quizzes or post on Ed.
|
|
52
53
|
|
|
53
54
|
Built for Monash Malaysia (times are handled as UTC+8); Australian campuses work too, see the [FAQ](#faq).
|
|
54
55
|
|
|
56
|
+

|
|
57
|
+
|
|
58
|
+
The picture is real output of `monash todo` against a database filled with made-up units, files and posts. Claude reads the same data through the MCP tools. Guide with more pictures: [docs.secureview.tech/study-kit](https://docs.secureview.tech/study-kit/).
|
|
59
|
+
|
|
55
60
|
---
|
|
56
61
|
|
|
57
62
|
## Two parts, one codebase
|
|
@@ -82,6 +87,20 @@ In short: MCP turns Claude into a TA who knows your units; the CLI handles setup
|
|
|
82
87
|
|
|
83
88
|
## Installation
|
|
84
89
|
|
|
90
|
+
The quickest way is one command, which installs `uv`, the kit and then starts `monash setup` (you can [read the scripts](https://docs.secureview.tech/study-kit/install/) first):
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
# macOS, in Terminal
|
|
94
|
+
curl -LsSf https://docs.secureview.tech/study-kit/install.sh | sh
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
```powershell
|
|
98
|
+
# Windows, in PowerShell
|
|
99
|
+
powershell -ExecutionPolicy ByPass -c "irm https://docs.secureview.tech/study-kit/install.ps1 | iex"
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Or do the same steps by hand:
|
|
103
|
+
|
|
85
104
|
### macOS
|
|
86
105
|
|
|
87
106
|
Open Terminal (search "Terminal" in Launchpad) and run these one at a time:
|
|
@@ -138,6 +157,15 @@ At the end you can choose to sync right away. The first sync downloads all cours
|
|
|
138
157
|
|
|
139
158
|
Then open Claude Desktop: under **"+" → Connectors** in the chat box you'll see **monash**. Leave it switched on.
|
|
140
159
|
|
|
160
|
+
## Panels, a local library, and optional remote access (1.4.0)
|
|
161
|
+
|
|
162
|
+
- **Study panels:** todo cards, Ed Lesson progress and quiz practice render in MCP Apps-capable hosts. Existing tools retain their text results; quiz choices go to the AI for explanation, never to Ed for submission.
|
|
163
|
+
- **Activity finder:** ask for a Moodle section or activity by name with `search_moodle_activities`.
|
|
164
|
+
- **Local file library:** run `monash library --open` to browse synced Moodle and Ed Lesson files by course/week and download originals, without an AI app. It only listens on your computer.
|
|
165
|
+
- **Optional self-hosting:** `monash remote serve --public-url https://your-host.example` starts a single-user OAuth-protected remote MCP server behind your own HTTPS proxy. It exposes 16 read-only query tools; local login/sync maintenance stays on the server terminal. No server starts automatically.
|
|
166
|
+
|
|
167
|
+
See [setup, connection modes, security boundaries and validation](docs/panels-library-remote.md). Normal local use still needs no domain, VPS or remote account.
|
|
168
|
+
|
|
141
169
|
## Everyday use
|
|
142
170
|
|
|
143
171
|
Just ask in Claude. While Claude is open, the tool works in the background:
|
|
@@ -151,7 +179,7 @@ Use your own words: Claude picks tools by meaning, not keywords, so both "anythi
|
|
|
151
179
|
To see everything it can do:
|
|
152
180
|
|
|
153
181
|
- Ask Claude "what can you do", or choose one of monash's preset prompts from the **"+" menu**: feature overview, this week's to-dos,
|
|
154
|
-
Ed updates, find a topic, quiz review, grades and feedback. Presets are only sent when you click them, so they cost nothing otherwise.
|
|
182
|
+
Ed updates, find a topic, quiz review, assignment requirements, grades and feedback. Presets are only sent when you click them, so they cost nothing otherwise.
|
|
155
183
|
- Run `monash help` in the terminal: every feature with an example question and the matching command.
|
|
156
184
|
|
|
157
185
|
### When the Moodle login expires
|
|
@@ -195,8 +223,9 @@ monash connect cursor # or codex, vscode, windsurf, gemini
|
|
|
195
223
|
|
|
196
224
|
It adds only the `monash` entry to the client's config file with the full path to the program, keeps everything else, and saves a backup first. Codex is set up with `codex mcp add` when the `codex` command exists. `--print` shows the entry without changing anything, and `--remove` takes it out again. `monash uninstall` removes it from every client.
|
|
197
225
|
|
|
198
|
-
>
|
|
199
|
-
>
|
|
226
|
+
> **Verified:** Claude Desktop and Claude Code with the local server; ChatGPT and Codex through a private remote integration using the same v1.3.0 core. On 30 October 2026, Codex successfully queried Moodle and Ed courses; ChatGPT's course query was also confirmed. The public package's stdio handshake, 17-tool catalog, isolated course query and ping passed an offline smoke test.
|
|
227
|
+
>
|
|
228
|
+
> The tested private deployment remains separate; 1.4.0 adds an optional [self-hosted remote mode](docs/panels-library-remote.md). These checks do not establish native local Codex, Cursor, VS Code, Windsurf or Gemini CLI connectivity. `monash connect` writes the format from each vendor's official docs (as of 2026-10); the official docs take precedence.
|
|
200
229
|
|
|
201
230
|
To configure a client by hand instead, first find the full path of the `monash` program (many clients don't inherit your terminal's PATH):
|
|
202
231
|
|
|
@@ -215,7 +244,7 @@ Replace `/full/path/monash` in the examples with your path. **In JSON, Windows b
|
|
|
215
244
|
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Untested |
|
|
216
245
|
| VS Code (Copilot) | Command Palette → `MCP: Open User Configuration` | Untested |
|
|
217
246
|
| Gemini CLI | `~/.gemini/settings.json` | Untested |
|
|
218
|
-
| ChatGPT web / mobile app |
|
|
247
|
+
| ChatGPT web / mobile app | Separately hosted remote endpoint | Requires a remote MCP server; the public local package alone does not provide one |
|
|
219
248
|
|
|
220
249
|
Codex (`~/.codex/config.toml`), or simply run `codex mcp add monash -- /full/path/monash mcp`:
|
|
221
250
|
|
|
@@ -254,6 +283,16 @@ If the file already lists other servers, add the `monash` entry rather than over
|
|
|
254
283
|
- Tool descriptions are written with Claude in mind. Other models usually follow them fine, but this hasn't been verified.
|
|
255
284
|
- If you'd rather not bother, the CLI works with no AI at all (see [Works without Claude usage](#works-without-claude-usage)); you can paste the output of `monash todo` and friends into any AI.
|
|
256
285
|
|
|
286
|
+
### Agent skill
|
|
287
|
+
|
|
288
|
+
For coding agents that read skills (Claude Code, Codex, Cursor and others), there is a skill that tells the agent which `monash` command answers which question, how to handle assignment questions (brief and rubric first, then staff answers on Ed, each with a source), and what it must leave to you (logins, tokens, submitting):
|
|
289
|
+
|
|
290
|
+
```sh
|
|
291
|
+
npx skills add Waldo0926/monash-study-kit
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
The file is [`skills/monash-study-kit/SKILL.md`](skills/monash-study-kit/SKILL.md). A test checks that every command in it still exists. `npx skills` is a third-party installer from Vercel and needs Node.js; you can also copy the file into your agent's skills folder by hand.
|
|
295
|
+
|
|
257
296
|
### What can be searched
|
|
258
297
|
|
|
259
298
|
`monash grep` and Claude's course-material search cover:
|
|
@@ -290,13 +329,15 @@ If the file already lists other servers, add the `monash` entry rather than over
|
|
|
290
329
|
|
|
291
330
|
## Token use
|
|
292
331
|
|
|
293
|
-
Every MCP tool's name, description and parameters are sent to Claude at the start of each conversation, so they cost tokens even when unused. Measured with `scripts/measure_tokens.py` on 1.
|
|
332
|
+
Every MCP tool's name, description and parameters are sent to Claude at the start of each conversation, so they cost tokens even when unused. Measured with `scripts/measure_tokens.py` on 1.4.0 (estimate: 4 ASCII characters or 1 Chinese character per token):
|
|
294
333
|
|
|
295
334
|
| Sent once per conversation | Tokens |
|
|
296
335
|
| --- | ---: |
|
|
297
|
-
|
|
|
298
|
-
| Server instructions |
|
|
299
|
-
| **Total** | **
|
|
336
|
+
| 18 tool definitions | 2,962 |
|
|
337
|
+
| Server instructions | 270 |
|
|
338
|
+
| **Total** | **3,232** |
|
|
339
|
+
|
|
340
|
+
The instructions grew from 187 in 1.2.0 when the rule for assignment questions was added (brief and rubric first, then staff answers on Ed).
|
|
300
341
|
|
|
301
342
|
The largest single tool is `search_ed_threads` at 324.
|
|
302
343
|
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
[](https://pypi.org/project/monash-study-kit/)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](#privacy-and-security)
|
|
9
|
+
[](https://docs.secureview.tech/study-kit/)
|
|
9
10
|
|
|
10
11
|
[](https://github.com/Waldo0926/monash-study-kit/actions/workflows/test.yml) [](https://glama.ai/mcp/servers/Waldo0926/monash-study-kit)
|
|
11
12
|
|
|
@@ -18,11 +19,15 @@ Connect Monash **Moodle** and **Ed** to Claude, then just ask Claude:
|
|
|
18
19
|
- "Which week of FIT2102 covered monads? Which slide deck, which page?"
|
|
19
20
|
- "What does the A2 spec ask for?", "What's my current grade in FIT2109?"
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
By default, everything stays **on your own computer**: course files, login state and the database live locally and never pass through a third-party server.
|
|
22
23
|
All tools are **read-only**: they never submit assignments, attempt quizzes or post on Ed.
|
|
23
24
|
|
|
24
25
|
Built for Monash Malaysia (times are handled as UTC+8); Australian campuses work too, see the [FAQ](#faq).
|
|
25
26
|
|
|
27
|
+

|
|
28
|
+
|
|
29
|
+
The picture is real output of `monash todo` against a database filled with made-up units, files and posts. Claude reads the same data through the MCP tools. Guide with more pictures: [docs.secureview.tech/study-kit](https://docs.secureview.tech/study-kit/).
|
|
30
|
+
|
|
26
31
|
---
|
|
27
32
|
|
|
28
33
|
## Two parts, one codebase
|
|
@@ -53,6 +58,20 @@ In short: MCP turns Claude into a TA who knows your units; the CLI handles setup
|
|
|
53
58
|
|
|
54
59
|
## Installation
|
|
55
60
|
|
|
61
|
+
The quickest way is one command, which installs `uv`, the kit and then starts `monash setup` (you can [read the scripts](https://docs.secureview.tech/study-kit/install/) first):
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# macOS, in Terminal
|
|
65
|
+
curl -LsSf https://docs.secureview.tech/study-kit/install.sh | sh
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
```powershell
|
|
69
|
+
# Windows, in PowerShell
|
|
70
|
+
powershell -ExecutionPolicy ByPass -c "irm https://docs.secureview.tech/study-kit/install.ps1 | iex"
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Or do the same steps by hand:
|
|
74
|
+
|
|
56
75
|
### macOS
|
|
57
76
|
|
|
58
77
|
Open Terminal (search "Terminal" in Launchpad) and run these one at a time:
|
|
@@ -109,6 +128,15 @@ At the end you can choose to sync right away. The first sync downloads all cours
|
|
|
109
128
|
|
|
110
129
|
Then open Claude Desktop: under **"+" → Connectors** in the chat box you'll see **monash**. Leave it switched on.
|
|
111
130
|
|
|
131
|
+
## Panels, a local library, and optional remote access (1.4.0)
|
|
132
|
+
|
|
133
|
+
- **Study panels:** todo cards, Ed Lesson progress and quiz practice render in MCP Apps-capable hosts. Existing tools retain their text results; quiz choices go to the AI for explanation, never to Ed for submission.
|
|
134
|
+
- **Activity finder:** ask for a Moodle section or activity by name with `search_moodle_activities`.
|
|
135
|
+
- **Local file library:** run `monash library --open` to browse synced Moodle and Ed Lesson files by course/week and download originals, without an AI app. It only listens on your computer.
|
|
136
|
+
- **Optional self-hosting:** `monash remote serve --public-url https://your-host.example` starts a single-user OAuth-protected remote MCP server behind your own HTTPS proxy. It exposes 16 read-only query tools; local login/sync maintenance stays on the server terminal. No server starts automatically.
|
|
137
|
+
|
|
138
|
+
See [setup, connection modes, security boundaries and validation](docs/panels-library-remote.md). Normal local use still needs no domain, VPS or remote account.
|
|
139
|
+
|
|
112
140
|
## Everyday use
|
|
113
141
|
|
|
114
142
|
Just ask in Claude. While Claude is open, the tool works in the background:
|
|
@@ -122,7 +150,7 @@ Use your own words: Claude picks tools by meaning, not keywords, so both "anythi
|
|
|
122
150
|
To see everything it can do:
|
|
123
151
|
|
|
124
152
|
- Ask Claude "what can you do", or choose one of monash's preset prompts from the **"+" menu**: feature overview, this week's to-dos,
|
|
125
|
-
Ed updates, find a topic, quiz review, grades and feedback. Presets are only sent when you click them, so they cost nothing otherwise.
|
|
153
|
+
Ed updates, find a topic, quiz review, assignment requirements, grades and feedback. Presets are only sent when you click them, so they cost nothing otherwise.
|
|
126
154
|
- Run `monash help` in the terminal: every feature with an example question and the matching command.
|
|
127
155
|
|
|
128
156
|
### When the Moodle login expires
|
|
@@ -166,8 +194,9 @@ monash connect cursor # or codex, vscode, windsurf, gemini
|
|
|
166
194
|
|
|
167
195
|
It adds only the `monash` entry to the client's config file with the full path to the program, keeps everything else, and saves a backup first. Codex is set up with `codex mcp add` when the `codex` command exists. `--print` shows the entry without changing anything, and `--remove` takes it out again. `monash uninstall` removes it from every client.
|
|
168
196
|
|
|
169
|
-
>
|
|
170
|
-
>
|
|
197
|
+
> **Verified:** Claude Desktop and Claude Code with the local server; ChatGPT and Codex through a private remote integration using the same v1.3.0 core. On 30 October 2026, Codex successfully queried Moodle and Ed courses; ChatGPT's course query was also confirmed. The public package's stdio handshake, 17-tool catalog, isolated course query and ping passed an offline smoke test.
|
|
198
|
+
>
|
|
199
|
+
> The tested private deployment remains separate; 1.4.0 adds an optional [self-hosted remote mode](docs/panels-library-remote.md). These checks do not establish native local Codex, Cursor, VS Code, Windsurf or Gemini CLI connectivity. `monash connect` writes the format from each vendor's official docs (as of 2026-10); the official docs take precedence.
|
|
171
200
|
|
|
172
201
|
To configure a client by hand instead, first find the full path of the `monash` program (many clients don't inherit your terminal's PATH):
|
|
173
202
|
|
|
@@ -186,7 +215,7 @@ Replace `/full/path/monash` in the examples with your path. **In JSON, Windows b
|
|
|
186
215
|
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Untested |
|
|
187
216
|
| VS Code (Copilot) | Command Palette → `MCP: Open User Configuration` | Untested |
|
|
188
217
|
| Gemini CLI | `~/.gemini/settings.json` | Untested |
|
|
189
|
-
| ChatGPT web / mobile app |
|
|
218
|
+
| ChatGPT web / mobile app | Separately hosted remote endpoint | Requires a remote MCP server; the public local package alone does not provide one |
|
|
190
219
|
|
|
191
220
|
Codex (`~/.codex/config.toml`), or simply run `codex mcp add monash -- /full/path/monash mcp`:
|
|
192
221
|
|
|
@@ -225,6 +254,16 @@ If the file already lists other servers, add the `monash` entry rather than over
|
|
|
225
254
|
- Tool descriptions are written with Claude in mind. Other models usually follow them fine, but this hasn't been verified.
|
|
226
255
|
- If you'd rather not bother, the CLI works with no AI at all (see [Works without Claude usage](#works-without-claude-usage)); you can paste the output of `monash todo` and friends into any AI.
|
|
227
256
|
|
|
257
|
+
### Agent skill
|
|
258
|
+
|
|
259
|
+
For coding agents that read skills (Claude Code, Codex, Cursor and others), there is a skill that tells the agent which `monash` command answers which question, how to handle assignment questions (brief and rubric first, then staff answers on Ed, each with a source), and what it must leave to you (logins, tokens, submitting):
|
|
260
|
+
|
|
261
|
+
```sh
|
|
262
|
+
npx skills add Waldo0926/monash-study-kit
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
The file is [`skills/monash-study-kit/SKILL.md`](skills/monash-study-kit/SKILL.md). A test checks that every command in it still exists. `npx skills` is a third-party installer from Vercel and needs Node.js; you can also copy the file into your agent's skills folder by hand.
|
|
266
|
+
|
|
228
267
|
### What can be searched
|
|
229
268
|
|
|
230
269
|
`monash grep` and Claude's course-material search cover:
|
|
@@ -261,13 +300,15 @@ If the file already lists other servers, add the `monash` entry rather than over
|
|
|
261
300
|
|
|
262
301
|
## Token use
|
|
263
302
|
|
|
264
|
-
Every MCP tool's name, description and parameters are sent to Claude at the start of each conversation, so they cost tokens even when unused. Measured with `scripts/measure_tokens.py` on 1.
|
|
303
|
+
Every MCP tool's name, description and parameters are sent to Claude at the start of each conversation, so they cost tokens even when unused. Measured with `scripts/measure_tokens.py` on 1.4.0 (estimate: 4 ASCII characters or 1 Chinese character per token):
|
|
265
304
|
|
|
266
305
|
| Sent once per conversation | Tokens |
|
|
267
306
|
| --- | ---: |
|
|
268
|
-
|
|
|
269
|
-
| Server instructions |
|
|
270
|
-
| **Total** | **
|
|
307
|
+
| 18 tool definitions | 2,962 |
|
|
308
|
+
| Server instructions | 270 |
|
|
309
|
+
| **Total** | **3,232** |
|
|
310
|
+
|
|
311
|
+
The instructions grew from 187 in 1.2.0 when the rule for assignment questions was added (brief and rubric first, then staff answers on Ed).
|
|
271
312
|
|
|
272
313
|
The largest single tool is `search_ed_threads` at 324.
|
|
273
314
|
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
[](https://pypi.org/project/monash-study-kit/)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](#隐私和安全)
|
|
9
|
+
[](https://docs.secureview.tech/zh-cn/study-kit/)
|
|
9
10
|
|
|
10
11
|
[](https://github.com/Waldo0926/monash-study-kit/actions/workflows/test.yml) [](https://glama.ai/mcp/servers/Waldo0926/monash-study-kit)
|
|
11
12
|
|
|
@@ -18,10 +19,14 @@
|
|
|
18
19
|
- “FIT2102 哪一周讲了 monad?在哪份讲义第几页?”
|
|
19
20
|
- “帮我看看 A2 的 spec 要求什么”、“我 FIT2109 现在成绩多少?”
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
默认所有东西都在**你自己的电脑上**:课件、登录状态、数据库都存在本机,不经过任何第三方服务器。工具全部是**只读**的:不会帮你交作业、做测验或在 Ed 上发帖。
|
|
22
23
|
|
|
23
24
|
适合 Monash 马来西亚校区(时间按 UTC+8 处理);澳洲校区也能用,见[常见问题](#常见问题)。
|
|
24
25
|
|
|
26
|
+

|
|
27
|
+
|
|
28
|
+
图里是 `monash todo` 的真实输出,数据库里的课程、课件和帖子都是编的。Claude 通过 MCP 工具读到的是同样的数据。带图的使用说明:[docs.secureview.tech/zh-cn/study-kit](https://docs.secureview.tech/zh-cn/study-kit/)。
|
|
29
|
+
|
|
25
30
|
---
|
|
26
31
|
|
|
27
32
|
## 它由两部分组成
|
|
@@ -51,6 +56,20 @@
|
|
|
51
56
|
|
|
52
57
|
## 安装
|
|
53
58
|
|
|
59
|
+
最快的办法是一条命令:装好 `uv` 和本工具,然后直接进入 `monash setup`(可以先[看看脚本内容](https://docs.secureview.tech/zh-cn/study-kit/install/)):
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# macOS,在终端里
|
|
63
|
+
curl -LsSf https://docs.secureview.tech/study-kit/install.sh | sh
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```powershell
|
|
67
|
+
# Windows,在 PowerShell 里
|
|
68
|
+
powershell -ExecutionPolicy ByPass -c "irm https://docs.secureview.tech/study-kit/install.ps1 | iex"
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
也可以手动一步步来:
|
|
72
|
+
|
|
54
73
|
### macOS
|
|
55
74
|
|
|
56
75
|
打开“终端”(启动台里搜 Terminal),一行一行粘贴运行:
|
|
@@ -104,6 +123,15 @@ monash setup
|
|
|
104
123
|
|
|
105
124
|
完成后打开 Claude Desktop,在聊天输入框的 **“+” → Connectors** 里能看到 **monash**,开着就行。
|
|
106
125
|
|
|
126
|
+
## 学习面板、本地课件页和可选远程接入(1.4.0)
|
|
127
|
+
|
|
128
|
+
- **三个学习面板:** 待办卡片、Ed Lesson 进度、测验练习,在支持 MCP Apps 的客户端显示。原来的工具文字结果保留;练习答案只发给 AI 讲解,不交给 Ed。
|
|
129
|
+
- **活动查找:** 新增 `search_moodle_activities`,按名称定位 Moodle 章节和活动。
|
|
130
|
+
- **本地课件页:** 运行 `monash library --open`,按课程和周次浏览、下载已同步的 Moodle/Ed Lesson 文件,不用打开 AI,只监听本机。
|
|
131
|
+
- **可选自托管:** `monash remote serve --public-url https://你的域名`,在自己的 HTTPS 代理后运行带 OAuth 的单用户远程 MCP。远程仅开放 16 个只读查询工具,登录和手动同步留在服务器终端。不会自动启动或安装服务。
|
|
132
|
+
|
|
133
|
+
设置方法、接入方式和验证步骤见[完整指南](docs/panels-library-remote.md)。普通本地使用仍不需要域名、VPS 或远程账号。
|
|
134
|
+
|
|
107
135
|
## 平时怎么用
|
|
108
136
|
|
|
109
137
|
直接在 Claude 里问就行。Claude 开着的时候,工具会在后台:
|
|
@@ -115,7 +143,7 @@ monash setup
|
|
|
115
143
|
|
|
116
144
|
直接用自己的话问就行:Claude 按意思挑工具,不是靠关键词触发,“这周有啥要交的”和“我是不是漏交了什么”都能用到待办。想看都能做什么:
|
|
117
145
|
|
|
118
|
-
- 在 Claude 里问“你能做什么”,或者从输入框的 **“+” 菜单**里选 monash 的预设提示:功能大全、本周待办、Ed
|
|
146
|
+
- 在 Claude 里问“你能做什么”,或者从输入框的 **“+” 菜单**里选 monash 的预设提示:功能大全、本周待办、Ed 新消息、找知识点、测验题复习、作业要求、成绩和反馈。预设提示点了才发给 Claude,平时不占额度。
|
|
119
147
|
- 终端里运行 `monash help`:每项功能附一句示例问法和对应的命令。
|
|
120
148
|
|
|
121
149
|
### Moodle 登录过期了怎么办
|
|
@@ -155,7 +183,9 @@ monash connect cursor # 或 codex、vscode、windsurf、gemini
|
|
|
155
183
|
|
|
156
184
|
它只在客户端的配置文件里加 `monash` 这一项,写程序的完整路径,其他内容原样保留,改之前先备份。装了 `codex` 命令的话 Codex 用 `codex mcp add` 接。`--print` 只打印要加的配置不改文件,`--remove` 移除。`monash uninstall` 会从所有客户端移除。
|
|
157
185
|
|
|
158
|
-
>
|
|
186
|
+
> **已验证:** Claude Desktop、Claude Code 的本地接入,以及 ChatGPT、Codex 通过同一套 v1.3.0 核心的私有远程集成。2026 年 10 月 30 日,Codex 成功查询了 Moodle 和 Ed 课程,ChatGPT 的课程查询也已确认。公开包的 stdio 握手、17 个工具目录、隔离数据下的课程查询和 ping 均通过离线测试。
|
|
187
|
+
>
|
|
188
|
+
> 已验证的私有部署保持独立;1.4.0 新增可选的[自托管远程模式](docs/panels-library-remote.md)。这些验证不等同于验证 Codex、Cursor、VS Code、Windsurf、Gemini CLI 的原生本地接入。`monash connect` 写的格式照各家官方文档(2026-10),有出入时以官方文档为准。
|
|
159
189
|
|
|
160
190
|
想手动配置的话,先找到 `monash` 程序的完整路径(很多客户端启动时读不到终端的 PATH):
|
|
161
191
|
|
|
@@ -173,7 +203,7 @@ monash connect cursor # 或 codex、vscode、windsurf、gemini
|
|
|
173
203
|
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | 未测试 |
|
|
174
204
|
| VS Code(Copilot) | 命令面板 → `MCP: Open User Configuration` | 未测试 |
|
|
175
205
|
| Gemini CLI | `~/.gemini/settings.json` | 未测试 |
|
|
176
|
-
| ChatGPT 网页版 / 手机 App |
|
|
206
|
+
| ChatGPT 网页版 / 手机 App | 单独托管的远程地址 | 需要远程 MCP 服务器;仅安装公开本地包不会提供远程地址 |
|
|
177
207
|
|
|
178
208
|
Codex(`~/.codex/config.toml`),或者直接运行 `codex mcp add monash -- /完整路径/monash mcp`:
|
|
179
209
|
|
|
@@ -212,6 +242,16 @@ VS Code(`mcp.json`,注意外层是 `servers` 不是 `mcpServers`):
|
|
|
212
242
|
- 工具说明是按 Claude 写的,别的模型一般也能照着用,但效果没验证过。
|
|
213
243
|
- 不想折腾的话,命令行本身跟任何 AI 都无关(见[没额度了也能用](#claude-没额度了也能用)),可以把 `monash todo` 之类的输出直接复制给任何 AI。
|
|
214
244
|
|
|
245
|
+
### 给 AI 用的技能包
|
|
246
|
+
|
|
247
|
+
会读 skill 的 AI 编程工具(Claude Code、Codex、Cursor 等)可以装这个技能包。它告诉 AI 哪个问题用哪条 `monash` 命令、问作业要求时怎么用资料(作业说明和评分细则优先,再看 Ed 上教职员工的回答,每条标出处),以及哪些事必须留给你自己(登录、令牌、交作业):
|
|
248
|
+
|
|
249
|
+
```sh
|
|
250
|
+
npx skills add Waldo0926/monash-study-kit
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
文件在 [`skills/monash-study-kit/SKILL.md`](skills/monash-study-kit/SKILL.md),有测试检查里面的命令都还存在。`npx skills` 是 Vercel 做的第三方安装工具,要装 Node.js;也可以把文件手动复制到 AI 的 skills 文件夹。
|
|
254
|
+
|
|
215
255
|
### 搜得到哪些内容
|
|
216
256
|
|
|
217
257
|
`monash grep` 和 Claude 里的课件搜索覆盖:
|
|
@@ -242,13 +282,15 @@ VS Code(`mcp.json`,注意外层是 `servers` 不是 `mcpServers`):
|
|
|
242
282
|
|
|
243
283
|
## Token 用量
|
|
244
284
|
|
|
245
|
-
每个 MCP 工具的名字、说明和参数在每次对话开始时都会发给 Claude,不调用也占 token。用 `scripts/measure_tokens.py` 在 1.
|
|
285
|
+
每个 MCP 工具的名字、说明和参数在每次对话开始时都会发给 Claude,不调用也占 token。用 `scripts/measure_tokens.py` 在 1.4.0 上量的结果(估算:4 个 ASCII 字符或 1 个中文字符算 1 个 token):
|
|
246
286
|
|
|
247
287
|
| 每次对话发一次 | Token |
|
|
248
288
|
| --- | ---: |
|
|
249
|
-
|
|
|
250
|
-
| 服务说明 |
|
|
251
|
-
| **合计** | **
|
|
289
|
+
| 18 个工具定义 | 2,962 |
|
|
290
|
+
| 服务说明 | 270 |
|
|
291
|
+
| **合计** | **3,232** |
|
|
292
|
+
|
|
293
|
+
服务说明在 1.2.0 是 187,1.3.0 加了作业问题的规则(作业说明和评分细则优先,再看 Ed 上教职员工的回答)后变成 270。
|
|
252
294
|
|
|
253
295
|
最大的单个工具是 `search_ed_threads`,324。
|
|
254
296
|
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Study panels, local library and optional remote MCP (1.4.0)
|
|
2
|
+
|
|
3
|
+
All additions operate on the owner's own data. The default remains a local stdio
|
|
4
|
+
server. Installing or updating the package does not start a web server, register
|
|
5
|
+
a remote endpoint, change client settings or install a system service.
|
|
6
|
+
|
|
7
|
+
## Three study panels
|
|
8
|
+
|
|
9
|
+
In an MCP Apps-capable host, `get_study_todo` can show deadline cards and unfinished
|
|
10
|
+
Lessons. `get_ed_lessons` can show module progress or quiz practice. The panels use
|
|
11
|
+
the same tools and arguments as before; the original text result remains available
|
|
12
|
+
for hosts without MCP Apps. No extra panel tools are registered.
|
|
13
|
+
|
|
14
|
+
- Ask “What do I need to do this week?” for the todo panel.
|
|
15
|
+
- Ask “Show my FIT2109 Lesson progress” for progress grouped by module.
|
|
16
|
+
- Ask “Help me practice FIT2109's Week 3 quiz” for questions and choices. The AI can
|
|
17
|
+
call `get_ed_lessons` with `course`, `quiz=true`, and optionally `module`. With
|
|
18
|
+
`lesson` plus `quiz=true`, the original lesson text is retained and the attached
|
|
19
|
+
panel selects the matching lesson's questions.
|
|
20
|
+
|
|
21
|
+
The quiz panel keeps choices in memory. Its explanation button sends your answers
|
|
22
|
+
back into the conversation; it does not mark a Lesson complete or submit an Ed
|
|
23
|
+
attempt. Ed does not provide student-visible answer keys, so the AI must read the
|
|
24
|
+
Lesson materials and explain uncertainty. Hosts control whether panels, messages
|
|
25
|
+
and external links are available. A successful protocol test is not a guarantee
|
|
26
|
+
that every client renders MCP Apps.
|
|
27
|
+
|
|
28
|
+
`search_moodle_activities` adds name-based section/activity lookup to MCP, using the
|
|
29
|
+
same backend as `monash moodle find`. It searches names, while `search_content`
|
|
30
|
+
searches downloaded file text. The local catalog is now 18 tools; all 17 existing
|
|
31
|
+
tool names, argument schemas, annotations and descriptions remain compatible.
|
|
32
|
+
|
|
33
|
+
## Browse synced files without an AI
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
monash library --open
|
|
37
|
+
# Or choose a free local port:
|
|
38
|
+
monash library --port 8766
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Open the printed `http://127.0.0.1:PORT/` address. Filter by course and filename or
|
|
42
|
+
week. The page reads existing Moodle file records and Ed Lesson file records;
|
|
43
|
+
`monash sync` remains a separate command. Click a file to download its original
|
|
44
|
+
bytes. Empty data gets a first-sync message. Listings are paginated at 200 files.
|
|
45
|
+
|
|
46
|
+
The server only binds on IPv4 loopback. It has no login, upload, sync or submission
|
|
47
|
+
route. Host/Origin checks reject DNS rebinding and cross-origin requests; course
|
|
48
|
+
text is HTML-escaped and downloaded files are attachments with `nosniff`.
|
|
49
|
+
Unregistered, removed, missing or out-of-root files are refused, including symlinks
|
|
50
|
+
escaping the allowed folders. It does not serve your secrets or browser profile.
|
|
51
|
+
Local programs on the same machine can still access loopback; do not proxy this
|
|
52
|
+
unauthenticated local library onto a public interface. Stop it with Ctrl-C.
|
|
53
|
+
|
|
54
|
+
## Optional single-user remote MCP
|
|
55
|
+
|
|
56
|
+
This mode is for owners who want to host **their own** data. It is not a shared
|
|
57
|
+
student hosting service and does not provide a public server maintained by the
|
|
58
|
+
author. Use a separate OS account and data directory for each owner.
|
|
59
|
+
|
|
60
|
+
1. Install and set up Study Kit under the intended account. Complete Moodle login
|
|
61
|
+
and enter the Ed token on that machine's own terminal. Use `MONASH_KIT_HOME` if
|
|
62
|
+
you need a separate data home; use the same value for serving and pairing.
|
|
63
|
+
2. Provide a domain with HTTPS and a reverse proxy to the loopback port. Then run:
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
monash remote serve --public-url https://study.example.org --port 8765
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`MONASH_KIT_REMOTE_URL` is an alternative to `--public-url`. The server only
|
|
70
|
+
binds to `127.0.0.1`; it does not configure nginx, DNS, certificates or services.
|
|
71
|
+
Normal background sync/keepalive runs while this command runs. Add
|
|
72
|
+
`--no-background` if another process already schedules those jobs.
|
|
73
|
+
3. In another terminal under the **same account/data home**, run:
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
monash remote pair
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Enter that one-time code on the authorization page opened by your AI client.
|
|
80
|
+
The code expires in ten minutes, permits one authorization and locks after
|
|
81
|
+
five wrong attempts. Never paste Moodle Cookies or Ed tokens into a chat.
|
|
82
|
+
4. Configure a remote-capable client's endpoint as
|
|
83
|
+
`https://study.example.org/mcp`, with OAuth. Supported default callbacks are
|
|
84
|
+
the official Claude and ChatGPT HTTPS callbacks. Each client pairs separately.
|
|
85
|
+
A different client's exact callback may be opted in with repeated
|
|
86
|
+
`--redirect-uri` flags (HTTPS, or HTTP on localhost with an explicit port);
|
|
87
|
+
wildcards and arbitrary port patterns are not accepted. Use the callback
|
|
88
|
+
actually reported by that client, not an invented example.
|
|
89
|
+
5. Inspect or revoke authorization locally:
|
|
90
|
+
|
|
91
|
+
```sh
|
|
92
|
+
monash remote clients
|
|
93
|
+
monash remote revoke --client CLIENT_ID
|
|
94
|
+
monash remote revoke --all
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Discovery metadata lives at `/.well-known/oauth-protected-resource` and
|
|
98
|
+
`/.well-known/oauth-authorization-server`. OAuth routes are `/oauth/register`,
|
|
99
|
+
`/oauth/authorize` and `/oauth/token`. The requested scope is `monash`. Tokens are
|
|
100
|
+
bound to the MCP resource URL; access tokens last one hour and refresh tokens last
|
|
101
|
+
30 days and rotate on use. Only hashes are kept in the private
|
|
102
|
+
`secrets/remote-mcp.db` (0700 directory, 0600 file on Unix). Changing the public
|
|
103
|
+
origin changes the audience and requires fresh authorization. Windows users must
|
|
104
|
+
also restrict the account's data-home ACLs.
|
|
105
|
+
|
|
106
|
+
The remote catalog contains 16 read-only query tools. It omits local browser login
|
|
107
|
+
and manual sync triggers and rejects their legacy aliases too. It shares study
|
|
108
|
+
panel resources, tool text and prompts with stdio. There is no credential-setting,
|
|
109
|
+
assignment submission, quiz submission, posting or public file-download route.
|
|
110
|
+
|
|
111
|
+
### Reverse-proxy example (adapt before using)
|
|
112
|
+
|
|
113
|
+
This is a configuration example only; the package never installs or runs it. On
|
|
114
|
+
an existing HTTPS virtual host, forward only MCP/OAuth paths, preserve Host and
|
|
115
|
+
Authorization, cap bodies, and add your normal proxy rate/time limits:
|
|
116
|
+
|
|
117
|
+
```nginx
|
|
118
|
+
location ~ ^/(mcp|oauth/(register|authorize|token)|\.well-known/oauth-(protected-resource|authorization-server)(/mcp)?)$ {
|
|
119
|
+
client_max_body_size 1m;
|
|
120
|
+
proxy_pass http://127.0.0.1:8765;
|
|
121
|
+
proxy_set_header Host $host;
|
|
122
|
+
proxy_set_header Authorization $http_authorization;
|
|
123
|
+
proxy_set_header X-Forwarded-Proto https;
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Use the actual public authority in Host, including a non-default port if used.
|
|
128
|
+
Do not expose `monash library` or the Study Kit data directory through that proxy.
|
|
129
|
+
|
|
130
|
+
## Verification and release boundary
|
|
131
|
+
|
|
132
|
+
Automated tests use temporary Moodle/Ed databases, synthetic course content and
|
|
133
|
+
loopback HTTP. They cover unchanged legacy tool contracts, three panel payloads,
|
|
134
|
+
file traversal/removed-file checks, origin checks, Claude/ChatGPT OAuth flows,
|
|
135
|
+
PKCE, token expiry/rotation, revocation and refusal of local-maintenance tools.
|
|
136
|
+
Wheel smoke reads the packaged panel resource and initializes the actual CLI.
|
|
137
|
+
|
|
138
|
+
After a separately authorized self-hosted deployment, verify HTTPS discovery,
|
|
139
|
+
unauthenticated MCP 401, initialize, query-tool catalog (16), a safe course query,
|
|
140
|
+
normal client refresh and a second query. Check panel rendering in each supported
|
|
141
|
+
host. No live private service or university data is changed by this feature PR.
|
|
142
|
+
Merging does not publish PyPI: follow the repository's normal reviewed tag/release
|
|
143
|
+
process before users install 1.4.0.
|
|
Binary file
|
|
@@ -102,13 +102,13 @@ The open DevTools port was gap G6. It is fixed on macOS and Linux. Windows keeps
|
|
|
102
102
|
|
|
103
103
|
The redirect case was gap G2 and is fixed.
|
|
104
104
|
|
|
105
|
-
## 5. MCP server: stdio
|
|
105
|
+
## 5. MCP server: stdio by default, read-only tools
|
|
106
106
|
|
|
107
107
|
**Risk.** A network listener would let other programs or other machines call the tools with the student's session. A write tool would let a model submit work or post on Ed because it misread a request. The design decision is in [ADR 0002](adr/0002-read-only-public-package.md).
|
|
108
108
|
|
|
109
109
|
**What the code does.**
|
|
110
|
-
- `mcp_server.py:693-713`: `main()` reads JSON-RPC lines from `sys.stdin` and writes replies to `sys.stdout`.
|
|
111
|
-
- `mcp_server.py:611-626`: every tool is published with an `annotations.readOnlyHint`.
|
|
110
|
+
- `mcp_server.py:693-713`: `main()` reads JSON-RPC lines from `sys.stdin` and writes replies to `sys.stdout`. Default stdio use opens no listening socket. Since 1.4.0, only explicitly invoked `monash library` and `monash remote serve` bind HTTP listeners, both on IPv4 loopback. Importing these modules does not start them. The CDP client still connects out to local DevTools.
|
|
111
|
+
- `mcp_server.py:611-626`: every tool is published with an `annotations.readOnlyHint`. In 1.4.0 it is `true` for 16 query tools. It is `false` for `start_monash_login` and `sync_monash_data` (`mcp_server.py:505-506`) because they open a local login window or start a local sync. Neither writes to Moodle or Ed.
|
|
112
112
|
- `mcp_server.py:681-682`: a tool name that is not in the table is refused. There is no submit, quiz, post or reply tool.
|
|
113
113
|
- Moodle AJAX calls used anywhere in the package are all `*_get_*` methods plus `core_session_touch` and `core_session_time_remaining`. The only POSTs are `/calendar/export.php` (`features.py:154`) and Ed's `/renew_token` (`edlib.py:181`). `moodlelib.multipart` (`moodlelib.py:316`) exists but nothing calls it.
|
|
114
114
|
|
|
@@ -121,7 +121,7 @@ The redirect case was gap G2 and is fixed.
|
|
|
121
121
|
- `tests/test_mcp.py::test_tools_cover_both_sides_and_only_login_sync_are_not_read_only`
|
|
122
122
|
- `tests/test_mcp.py::test_unknown_tool_and_method`
|
|
123
123
|
- `tests/test_security.py::test_mcp_talks_over_stdin_and_stdout`
|
|
124
|
-
- `tests/test_security.py::
|
|
124
|
+
- `tests/test_security.py::test_only_explicit_opt_in_modules_can_listen`
|
|
125
125
|
- `tests/test_security.py::test_only_read_calls_reach_moodle_and_ed`
|
|
126
126
|
|
|
127
127
|
## 6. `read_file` only opens files in the two file folders
|
|
@@ -263,3 +263,14 @@ grep -n "add_unredirected_header\|BASE_SCHEME" src/monash_study_kit/*.py
|
|
|
263
263
|
```
|
|
264
264
|
|
|
265
265
|
The real-Chromium test is skipped when no Chromium is installed. When the code changes, re-run the tests above and re-check the line numbers in this file with `grep -n`.
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
## 1.4.0 optional interfaces
|
|
269
|
+
|
|
270
|
+
The earlier line-numbered audit describes the original local core; it is not a live deployment certification. See [the 1.4.0 guide](panels-library-remote.md) for the new interface boundaries.
|
|
271
|
+
|
|
272
|
+
- `widgets.py` and packaged `ui/panel.html`: no external scripts or fetches; text results remain intact, course strings render as text, parent-window source is checked, links allow HTTP(S) only, and quiz answers only request an AI explanation. Host capabilities determine rendering. Tests: `tests/test_panels.py`.
|
|
273
|
+
- `library.py`: explicit loopback bind; Host/Origin checks; registered and active file catalog only; read-only database access, output escaping, attachment downloads and path/symlink boundary checks. No upload, login, sync or write route. Local programs on the same machine can access it. Tests: `tests/test_library.py`.
|
|
274
|
+
- `remote.py`: explicit HTTPS origin (loopback HTTP for tests), loopback bind for a reverse proxy, one-time pairing, PKCE S256, exact callback allowlists, resource/client-bound hashed tokens and rotating refresh, private OAuth state and no credential-setting tool. All 16 remote tools are query tools; local login/sync and legacy aliases are rejected. Network exposure, TLS and client end-to-end acceptance remain the self-hosting owner's responsibility. Tests: `tests/test_remote.py`, `tests/test_feature_cli.py`.
|
|
275
|
+
|
|
276
|
+
Only local OAuth state changes in authorization/revocation; no new operation submits assignments, attempts/submits quizzes, posts or replies on Ed. The three panel views and the local browser consume synced content. All automated test data lives in temporary homes; external socket connections are blocked in the suite.
|
|
@@ -5,7 +5,7 @@ description = "Connect Monash Moodle and Ed to Claude via a local MCP server and
|
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "MIT"
|
|
7
7
|
requires-python = ">=3.10"
|
|
8
|
-
authors = [{ name = "
|
|
8
|
+
authors = [{ name = "Waldo" }]
|
|
9
9
|
keywords = ["mcp", "model-context-protocol", "claude", "moodle", "edstem", "monash", "cli", "study-tools"]
|
|
10
10
|
classifiers = [
|
|
11
11
|
"Development Status :: 5 - Production/Stable",
|
|
@@ -55,6 +55,8 @@ def main() -> None:
|
|
|
55
55
|
if "__pycache__" not in p.parts}
|
|
56
56
|
if missing := want - set(names):
|
|
57
57
|
fail(f"wheel 里少了 {sorted(missing)}")
|
|
58
|
+
if "monash_study_kit/ui/panel.html" not in names:
|
|
59
|
+
fail("wheel 没有打包 ui/panel.html")
|
|
58
60
|
with tarfile.open(sdist) as t:
|
|
59
61
|
sdist_names = [m.name.split("/", 1)[1] for m in t.getmembers() if "/" in m.name]
|
|
60
62
|
for n in names + sdist_names:
|