@jamestesting888/tum-mcp 0.4.1 → 0.6.0

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.
Files changed (15) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/NOTICE +2 -4
  3. package/README.md +157 -59
  4. package/docs/development.md +118 -80
  5. package/docs/setup.md +164 -147
  6. package/docs/study.md +325 -0
  7. package/docs/tum-mcp.md +184 -135
  8. package/npm/backend/manifest.json +3 -3
  9. package/npm/backend/requirements.txt +62 -17
  10. package/npm/backend/tum_mcp-0.6.0-py3-none-any.whl +0 -0
  11. package/npm/runtime.mjs +210 -62
  12. package/npm/tum-mcp.mjs +20 -8
  13. package/package.json +50 -11
  14. package/docs/credential-storage-options.md +0 -86
  15. package/npm/backend/tum_moodle_integration-0.4.1-py3-none-any.whl +0 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,29 @@
1
+ # Changes
2
+
3
+ ## 0.6.0 — 2026-10-25
4
+
5
+ - Merge course setup and updates into `sync-study`, with recovery for incomplete
6
+ projects and preservation of edits, source coverage and course identity.
7
+ - Ship five focused skills: `read-content`, `sync-study`, `prepare-study`,
8
+ `audio-notes` and `publish-study`. Managed upgrades preserve personal overrides.
9
+ - Package the study renderer: consistent typography, responsive tables and math,
10
+ flip cards, four-choice practice, collapsible revision topics and review dialogs.
11
+ - Add local passage comments across content, cards and practice, with anchored
12
+ popups, automatic sync and conflict protection.
13
+ - Support inline LaTeX variables and a mobile outline overlay that keeps your place.
14
+ - Add category audio guidance and optional GitHub Pages publication. First
15
+ publication requires consent to a public website; the repository stays private.
16
+ - Install all five skills for Cursor and Antigravity during setup and update,
17
+ with ownership checks that preserve customized files during update and removal.
18
+ - Recognize occupied preview ports and deliver complete HTTP rejection responses
19
+ on Windows, and serve web assets independently of OS file associations.
20
+ Reuse isolated test fixtures,
21
+ retain native/platform coverage and expose slow tests and failures in CI.
22
+ - Preserve Windows CRLF study instructions through repeated synchronization.
23
+ - Group Artemis and Zulip implementation by provider, retaining read-only campus
24
+ tools and Moodle compatibility. Fix OCR with aliased macOS temporary paths.
25
+
26
+ Upgrading does not rebuild personal study sites automatically. Ask your agent to
27
+ update the prepared website; customized renderer files are preserved for review.
28
+ Audio, source materials, comments and study projects remain outside package
29
+ installation/removal.
package/NOTICE CHANGED
@@ -1,6 +1,4 @@
1
1
  The project's original code and documentation are provided under the MIT License.
2
2
 
3
- The TUM logo at plugin/assets/tum-logo.png (assets/tum-logo.png in the packaged
4
- plugin) is excluded from the MIT License. It belongs to the Technical University
5
- of Munich and remains subject to its original rights. No trademark rights are
6
- granted by this project. See plugin/assets/README.md for the source of the image.
3
+ No TUM logo is distributed. TUM names and trademarks belong to their respective
4
+ owners; no trademark rights or university endorsement are granted by this project.
package/README.md CHANGED
@@ -1,95 +1,193 @@
1
1
  # TUM MCP
2
2
 
3
- Use TUM Moodle, Artemis, and Zulip from your coding agent. Runs locally with
4
- 36 tools and seven workflow skills. Unofficial; independent of TUM and OpenAI.
3
+ Connect your coding agent to Moodle, Artemis and Zulip. Read course content and
4
+ build a private, source-backed study workspace. Unofficial; independent of TUM.
5
+
6
+ **Latest release: [0.6.0](https://www.npmjs.com/package/@jamestesting888/tum-mcp).**
7
+ [Release notes](CHANGELOG.md).
5
8
 
6
9
  ## Agent setup
7
10
 
8
- Paste this into your coding agent:
11
+ Paste this into your coding agent to install the published package:
9
12
 
10
13
  ```text
11
- Install @jamestesting888/tum-mcp@0.4.1 from npm on this computer.
12
- Check that Node.js is at least 22.14, then run:
13
- npm install --global @jamestesting888/tum-mcp@0.4.1
14
+ Install @jamestesting888/tum-mcp on this computer. Check Node.js is 22.14+.
15
+ Run npm install --global @jamestesting888/tum-mcp@latest, then:
14
16
  tum-mcp setup --client codex
15
- For Claude Code, use --client claude instead; other MCP clients use --client generic.
16
- Preserve existing settings, plugins, sessions, downloads, and customized skills.
17
- Follow the printed enablement/restart step. Then help me run tum-mcp connect campus
18
- in an interactive terminal so I can complete TUM sign-in/MFA in Chrome.
19
- Ask which Artemis courses and Zulip channels to enable before reading content.
20
- For Moodle, use the plugin's separate Moodle sign-in. Never request secrets in chat.
17
+ Use --client claude, cursor, antigravity, or generic for a different client.
18
+ Preserve existing settings and customized skills. Follow the activation steps.
19
+ Help me run tum-mcp connect in an interactive terminal and choose services.
20
+ I will complete sign-in/MFA in the browser. Never request secrets in chat.
21
+ Run tum-mcp doctor to explain what is available and what still needs setup.
21
22
  ```
22
23
 
23
- ## Manual setup
24
+ ## Connect
24
25
 
25
- You need **Node.js 22.14+**, **Google Chrome**, and your TUM account.
26
+ You need **Node.js 22.14+**, **a Chromium browser**, and your TUM account.
26
27
 
27
28
  ```sh
28
- npm install --global @jamestesting888/tum-mcp@0.4.1
29
+ npm install --global @jamestesting888/tum-mcp@latest
29
30
  tum-mcp setup --client codex
30
- tum-mcp connect campus
31
+ tum-mcp connect
32
+ tum-mcp doctor
31
33
  ```
32
34
 
33
- `campus` connects **Artemis and Zulip together**. Complete sign-in and MFA in
34
- Chrome; no Zulip API key is required. Moodle sign-in is separate: ask the loaded
35
- plugin, **“Sign in to TUM Moodle.”** Follow any client enablement/restart instruction.
36
- Disable the older Moodle plugin when enabling TUM MCP to avoid duplicate tools.
35
+ Select services with **Space**, then **Enter**. Choose an installed browser and
36
+ complete sign-in there. Only selected tabs open; Zulip needs no API key.
37
+ Enable the [course and channel scopes](docs/tum-mcp.md#connections-and-scopes) you want to use.
38
+
39
+ | Client | Setup |
40
+ | --- | --- |
41
+ | Codex | `--client codex` · plugin and skills; enable/restart when prompted |
42
+ | Claude Code | `--client claude` · MCP registration and skills |
43
+ | Cursor | `--client cursor` · MCP registration and all five skills; restart |
44
+ | Google Antigravity | `--client antigravity` · MCP registration and all five skills; restart |
45
+ | Other MCP clients | `--client generic` · configuration for manual installation |
46
+
47
+ For existing Cursor and Antigravity setups, run `tum-mcp update` to add the skills.
48
+ Updates and uninstall preserve customized files and report them for review.
37
49
 
38
- Select the courses and channels the backend may read. `status` shows account IDs;
39
- `discover` lists metadata, and `scope` saves your choices. New accounts start
40
- without content access. See the [connection and scope commands](docs/tum-mcp.md#connections-and-scopes).
50
+ Supports macOS, Windows, glibc Linux x86_64/ARM64 and WSL 3.x. In WSL, sign-in
51
+ opens a Windows browser. Add `--host windows` to setup for a Windows client that
52
+ uses the WSL backend. [Browser and WSL setup](docs/setup.md#wsl).
41
53
 
42
- Setup downloads a private Python runtime; consumers do not need Python or uv.
43
- Git is needed for assignment workspaces and Docker for isolated assignment tests.
44
- Linux also needs an unlocked Secret Service keyring in its desktop D-Bus session.
54
+ Setup supplies a private Python runtime. New connections use encrypted local
55
+ files and need no native keyring, Git or Docker.
45
56
 
46
- ## What you can do
57
+ ## Read and study
47
58
 
48
- | Service | Available |
59
+ | Source | Available content |
49
60
  | --- | --- |
50
- | Moodle | Read/search course materials and forums, cite PDF pages, download originals |
51
- | Artemis | Read released programming exercises and permitted feedback; prepare existing-participation workspaces, run approved local tests, preview submissions |
52
- | Zulip | Search selected channels, read topics, and summarize recent discussions with citations |
61
+ | Moodle | Materials, pages, announcements, forums, original downloads and cited PDF pages |
62
+ | Artemis | Lectures, text/online/video units, student slide PDFs, released exercise statements and permitted own feedback |
63
+ | Zulip | Selected course channels, discussion search and cited catch-up |
64
+
65
+ Campus access is read-only. Exercise start, deployment, execution, submission,
66
+ posting and read-state changes are unavailable.
67
+
68
+ ### Skills and example requests
69
+
70
+ The package includes five skills. Once you've chosen a course from
71
+ your connections, try requests like these:
72
+
73
+ | Skill | Use it to | Example request |
74
+ | --- | --- | --- |
75
+ | `read-content` | Read and explain course sources with citations | "Can you explain what we covered in last week's lecture?" |
76
+ | `sync-study` | Create or refresh a course project | "Set up a study project for this course." |
77
+ | `prepare-study` | Build lessons, flashcards and practice | "Make me a study website with flashcards and practice questions." |
78
+ | `publish-study` | Put a prepared website on GitHub Pages | "Put my study site online so I can open it on my phone." |
79
+ | `audio-notes` | Save spoken lessons under `audio/` | "Turn this into audio notes I can listen to on the go." |
80
+
81
+ Useful follow-ups in an existing project:
82
+
83
+ - "Did I miss anything important on Zulip this week?"
84
+ - "There's new course material. Can you update my study site?"
85
+ - "I've left some comments on the site. Can you fix those parts?"
86
+ - "Can you update the audio notes too?"
87
+
88
+ Client setup installs managed copies of the
89
+ [skill sources](src/tum_mcp/bundled/skills/). Develop or review skills in this repository.
90
+
91
+ ### Recommended study flow
92
+
93
+ 1. **`sync-study`**: Set up a project for your course and collect its material.
94
+ Use it again when new material is available.
95
+ 2. **`prepare-study`**: Turn that material into a study website with explanations,
96
+ flashcards and practice questions.
97
+ 3. **`publish-study`** (optional): Put the website online so you can study on your
98
+ phone. Check the [publishing requirements](#publish-for-phone-access-optional) first.
99
+ 4. **`audio-notes`** (optional): Turn the prepared content into spoken lessons.
100
+ Use them to revisit prepared topics while walking or commuting.
101
+
102
+ Each project holds one course. To open the website locally, run this from the
103
+ course project folder:
104
+
105
+ ```sh
106
+ tum-mcp study
107
+ ```
108
+
109
+ Your browser opens at `http://127.0.0.1:8765`. Press **Ctrl+C** in the terminal to stop.
110
+ See the [study guide and local demo](docs/study.md) for more examples.
111
+
112
+ ### Publish for phone access (optional)
53
113
 
54
- Try “Find the lecture section about scheduling,” “Read this Artemis exercise,”
55
- or “Catch me up on the selected Zulip channel.” Personal records, participation
56
- feedback, and workspace writes require their own explicit permissions.
114
+ Publishing requires [GitHub CLI](https://cli.github.com/) on the computer where
115
+ your agent runs and an eligible paid GitHub plan. Sign in locally, then check it:
57
116
 
58
- **0.4.1 is a public pilot.** Remote start, push, submit, and rebuild are disabled.
59
- It cannot post to Zulip or read DMs. A submission preview never submits anything.
60
- macOS ARM64 browser sign-in and live reads are verified; Windows, Intel Mac, and
61
- Linux desktop checks remain incomplete. Bootstrap targets and test evidence are
62
- listed in the [detailed guide](docs/tum-mcp.md#build-and-test-the-local-package).
117
+ ```sh
118
+ gh auth login --hostname github.com
119
+ tum-mcp doctor --live
120
+ ```
63
121
 
64
- ## Privacy
122
+ `doctor` checks CLI availability; `--live` also verifies GitHub authentication.
123
+ A coding platform's GitHub connector does not sign in the local CLI. No token
124
+ needs to be pasted into the agent or stored by TUM MCP.
65
125
 
66
- Sessions stay local and encrypted, with keys in macOS Keychain, Windows Credential
67
- Manager, or Linux Secret Service. There is no plaintext credential fallback.
68
- Relevant excerpts can be sent to your agent's configured AI provider. Zulip chat
69
- text is fetched live; Moodle's document cache is unencrypted and limited to
70
- 30 days / 1 GiB. Downloads remain until deleted.
126
+ **The repository is private. The website is public.** Review the lesson text,
127
+ quotations and source links before asking your agent to publish.
71
128
 
72
- Use the installed `tum-mcp` command for sign-in to keep the requesting runtime
73
- consistent. Your OS may ask for credential-store access. See
74
- [storage details](docs/credential-storage-options.md).
129
+ Later builds update the same site. `tum-mcp study` also prints its hosted URL.
130
+ See [publishing details](docs/study.md#publish-a-study-website).
75
131
 
76
- ## Update and support
132
+ ## Sign-in and session privacy
77
133
 
78
- Install the reviewed version you want, then rerun the client setup:
134
+ Sign-in and MFA happen in a temporary browser window. Only service-owned session
135
+ cookies are retained; identity-provider cookies are discarded when it closes.
136
+ Sessions stay on your computer in encrypted files with owner-restricted keys.
137
+ Configured local clients share those connections and selected scopes.
138
+
139
+ ## Your study project
140
+
141
+ The agent keeps each course in its own folder. After preparing the website,
142
+ your project looks like this, with audio added when requested:
143
+
144
+ ```text
145
+ my-course/
146
+ ├── AGENTS.md Course overview and source index for your agent
147
+ ├── materials/
148
+ │ ├── content/ Lectures, slides and reading
149
+ │ ├── exercises/ Exercise sheets and practice material
150
+ │ ├── exams/ Available exam and revision material
151
+ │ └── other/ Announcements and course information
152
+ ├── study/
153
+ │ ├── content.json Lessons, flashcards and practice questions
154
+ │ └── index.html Your study website
155
+ ├── audio/ Optional audio notes
156
+ │ ├── scripts/ Narration text
157
+ │ └── tracks/ Audio lessons
158
+ └── .study/
159
+ ├── state.json Course identity and source versions
160
+ └── comments.json Passage comments, when added
161
+ ```
162
+
163
+ Your agent uses your configured AI provider to work with course material.
164
+ Publishing uploads only the generated website; materials, audio and comments
165
+ stay local. Study progress is saved in your browser.
166
+
167
+ ## Update
79
168
 
80
169
  ```sh
81
170
  npm install --global @jamestesting888/tum-mcp@latest
82
- tum-mcp setup --client codex
171
+ tum-mcp update
83
172
  ```
84
173
 
85
- Existing Moodle sessions and downloads are preserved. Customized configurations
86
- are kept for review. `tum-mcp doctor` checks local prerequisites; it does not
87
- verify live authentication.
174
+ `update` prepares the invoked package's runtime and refreshes configured clients.
175
+ Sessions, scopes and downloads carry forward. User-edited entries and skills are
176
+ preserved and reported for review. Reload the client; refresh its cached plugin
177
+ if needed. Study sites are updated separately through the study workflows.
178
+
179
+ ## Remove
180
+
181
+ ```sh
182
+ tum-mcp uninstall --all
183
+ npm uninstall --global @jamestesting888/tum-mcp
184
+ ```
88
185
 
89
- [Detailed guide](docs/tum-mcp.md) · [Moodle-only setup](docs/setup.md) ·
90
- [Development](docs/development.md) · [Report a problem](https://github.com/jamestesting0/tum-moodle-integration/issues)
186
+ Managed registrations and unchanged skills are removed. Settings, sessions,
187
+ downloads and study projects are preserved. After closing clients, add
188
+ `--purge-runtime` to remove generated runtimes or `--forget-credentials` to
189
+ remove saved local sessions and historical Git tokens. [Removal details](docs/setup.md#update-and-remove).
91
190
 
92
- ## License
191
+ [Guide](docs/tum-mcp.md) · [Setup](docs/setup.md) · [Study workflows](docs/study.md) · [Development](docs/development.md)
93
192
 
94
- [MIT](LICENSE). The TUM logo retains its original rights; see [NOTICE](NOTICE).
95
- No trademark rights are granted.
193
+ [MIT](LICENSE) · [NOTICE](NOTICE) · [Report a problem](https://github.com/jamestesting0/tum-mcp/issues)
package/docs/development.md CHANGED
@@ -1,96 +1,134 @@
1
1
  # Development
2
2
 
3
- [README](../README.md) · [Setup](setup.md)
4
-
5
- For the combined 0.4.1 campus pilot, see the [TUM MCP guide](tum-mcp.md) and
6
- [current verification limits](tum-mcp.md#build-and-test-the-local-package). This page also
7
- covers the preserved Moodle-only installer.
3
+ The npm package is the distribution. Its wheel contains one Python package,
4
+ `src/tum_mcp/`, with peer `moodle/`, `artemis/` and `zulip/` provider packages.
5
+ The retired standalone Moodle plugin and its checkout installer are no longer
6
+ maintained.
7
+ Client adapters still generate the configuration each host needs.
8
8
 
9
9
  ## Checks
10
10
 
11
11
  ```sh
12
12
  uv sync --locked
13
- uv run ruff check src tests plugin/scripts scripts
14
- uv run ruff format --check src tests plugin/scripts scripts
15
- uv run pytest -q
16
- uv run python scripts/package_plugin.py
13
+ uv run ruff check src tests scripts
14
+ uv run ruff format --check src tests scripts
15
+ uv run pytest -v -x --tb=short --durations=20 -o faulthandler_timeout=60
17
16
  uv build
18
17
  node npm/build.mjs
19
18
  npm test
20
19
  npm pack --ignore-scripts --pack-destination dist
21
- npm run test:consumer -- dist/jamestesting888-tum-mcp-0.4.1.tgz
20
+ npm run test:consumer
21
+ npm run test:upgrade
22
22
  ```
23
23
 
24
- Python 3.13 is the managed runtime on every platform. Install Tesseract for the
25
- OCR integration test. Ordinary tests use synthetic materials and in-memory
26
- credentials; no Moodle login is needed. No language-server installation is required.
27
-
28
- GitHub Actions runs the suite on macOS, Windows, and Ubuntu, including packaged
29
- MCP startup, PDF/OCR extraction, downloads, and real native credential-store
30
- round trips. The Linux job starts its own D-Bus/Secret Service session.
31
- The campus additions configure fresh npm consumer checks on all three runners;
32
- those checks must pass for the release commit before claiming release coverage.
33
-
34
- To test an installed package, set `TUM_MOODLE_PACKAGED` to its
35
- `scripts/launch.py` path before running pytest. Set `TUM_MOODLE_SYSTEM_KEYRING=1`
36
- to enable the native-store test; it creates and removes a unique synthetic entry.
24
+ Python 3.13 is the managed runtime. Install Tesseract for OCR tests. Default tests
25
+ use synthetic sources and credentials. No language-server installation is needed.
26
+ Set `TUM_MOODLE_SYSTEM_KEYRING=1` for a unique synthetic native-store round trip.
27
+ The ordinary campus runtime uses encrypted local files and owner-restricted keys.
28
+ Set `TUM_MCP_BROWSER_INTEGRATION=1` to include the real HTTP static-export browser
29
+ check locally; CI enables it. Set environment variables using your shell's syntax.
30
+ Verbose test IDs, immediate first-failure output, slowest-test timings and a stack
31
+ dump after 60 seconds make a stalled boundary visible. The dump is diagnostic;
32
+ it does not skip a slow test or extend the CI deadline.
37
33
 
38
- Live Moodle checks are separate: `TUM_MOODLE_LIVE=1 uv run pytest tests/live -q`.
39
- They require the developer's saved session and Real Time Systems enrollment;
40
- one test downloads a lecture. Never supply personal credentials to public CI.
34
+ Each layer owns a different failure boundary:
41
35
 
42
- ## Architecture
43
-
44
- | Module | Responsibility |
36
+ | Layer | What it must prove |
37
+ | --- | --- |
38
+ | Unit | Parsing, policy, malformed input and failure branches with synthetic collaborators |
39
+ | Integration | Real files, CLI/MCP, transactions, HTTP confinement and isolated project updates |
40
+ | Installed consumer | Actual npm/wheel contents, managed runtime and complete browser workflows |
41
+ | Public upgrade | Earlier published versions, repair, ownership conflicts and removal |
42
+ | Native platform | OS credential/ACL behavior; WSL Windows browser transport on both engines |
43
+
44
+ Study integration fixtures build the real starter once, then copy it into a fresh
45
+ project for each test. Launcher tests only need an HTML entry point. Neither
46
+ shares mutable course state. Client transaction tests use five small synthetic
47
+ skills, including nested binary assets; full-pack export, migration and installed
48
+ consumer tests retain the actual bundled files. Browser checks keep the phone/desktop and light/dark
49
+ rendering matrix; long revision-state journeys run once per layout. Keep native
50
+ ACL/keyring and installed-artifact checks even when a mocked unit test is faster.
51
+ Text fixtures use explicit UTF-8; line-ending cases cover LF and CRLF without
52
+ changing the meaning of the managed inventory or user notes.
53
+ For a regression, extend its existing owner test and demonstrate failure without
54
+ the fix; do not add another test that only checks the same implementation text.
55
+
56
+ CI runs macOS, Windows and Linux, plus both distribution engines on WSL 3.x.
57
+ Consumer checks install the actual npm artifact, discover tools, build a study
58
+ site and test available Chromium browsers with temporary profiles and synthetic
59
+ pages. WSL verifies Windows browser transport. No live account is used.
60
+ Upgrade checks cover public 0.4.1/0.5.0, client refresh, customized-file conflicts,
61
+ failed preparation, runtime repair and removal that preserves work/credentials.
62
+ All five jobs must pass on the exact pushed commit before completion is claimed.
63
+
64
+ Live Moodle checks are opt-in: `TUM_MOODLE_LIVE=1 uv run pytest tests/live -q`.
65
+ They use the developer's selected course and saved session. Keep them out of CI.
66
+
67
+ ## Releases
68
+
69
+ Keep package.json, pyproject.toml and `tum_mcp.__version__` aligned. Build/pack into
70
+ `dist/`, inspect the wheel and tarball contents, and record the tarball's SHA-256.
71
+ Run the consumer and upgrade checks against that artifact before pushing. Confirm
72
+ both desktop and WSL workflows for the exact pushed SHA; a previous green run is
73
+ not release evidence. Local agent notes, course projects and credentials must be
74
+ absent from both Git and the package.
75
+
76
+ Prepare the README and changelog for the release before building the final
77
+ tarball so npm receives the same release documentation. Publishing is a separate
78
+ explicit step using that reviewed tarball, with npm's browser verification when
79
+ required. Do not use publication as a test. Confirm the registry version, latest
80
+ tag and artifact integrity before pushing the release documentation.
81
+
82
+ ## Source layout
83
+
84
+ | Location | Responsibility |
45
85
  | --- | --- |
46
- | `platforms.py` | Shared OS data/runtime paths; also imported by bootstrap and launcher |
47
- | `auth.py`, `login.py` | Encrypted sessions, native credential stores, Chrome sign-in |
48
- | `server.py`, `service.py` | MCP tools and retrieval coordination |
49
- | `http_client.py` | Read-only Moodle network boundary |
50
- | `parsing.py`, `forums.py`, `personal_records.py` | Moodle content and explicit private-record reads |
51
- | `extraction.py`, `extract_worker.py` | Document/OCR extraction with process limits |
52
- | `library.py`, `downloads.py` | Local search/cache and persistent exports |
53
-
54
- The stdlib-only `scripts/install.py` owns packaging, runtime checks, activation,
55
- and structured handoff. The updater pulls safely, then delegates to that installer.
56
- Packaged `scripts/runtime_setup.py` is shared with bootstrap; its content receipt
57
- and offline dependency check permit healthy reruns without synchronization.
58
- Source changes force a package refresh even if the version/metadata timestamp
59
- is unchanged. `--repair` reinstalls the locked runtime. The MCP smoke check lists
60
- tools without reading a Moodle session or making Moodle requests.
61
-
62
- Generated manifests launch the absolute private Python path on every OS.
63
- Portable source templates contain no machine paths. Rebuild on each target
64
- computer; moving/deleting the checkout does not affect the installed runtime.
65
-
66
- CI enables `TUM_MOODLE_INSTALLER_INTEGRATION=1` for a real isolated-cache install,
67
- offline rerun, same-version source update, damaged-runtime detection, and repair.
68
- Set `TUM_MOODLE_INSTALLER_EVIDENCE` to write stage timings. The external Codex CLI
69
- is synthetic in those tests; dependency installation and MCP startup are real.
70
- Timings exclude agent latency, user sign-in/MFA, and application restart time.
71
-
72
- Credentials use explicit OS backends. Unsupported or unavailable stores fail
73
- with `SETUP_REQUIRED`; environment-selected plaintext alternatives are ignored.
74
- Keep the existing macOS service name and account path to preserve saved sessions.
75
-
76
- Extraction runs in a subprocess with a 60-second wall limit and 512 MiB aggregate
77
- memory monitoring. POSIX also enforces a CPU limit and kills the process group;
78
- Windows terminates the worker and its observed child processes.
79
-
80
- ## Manual desktop verification
81
-
82
- Automated tests do not replace a desktop check. On each target OS, verify:
83
-
84
- 1. Register/install from a checkout with spaces in its path; restart the client.
85
- 2. Confirm native tools appear, then complete Chrome sign-in and MFA.
86
- 3. List current-semester courses, read a PDF, and check a forum.
87
- 4. Download one material and open the returned file locally.
88
- 5. Restart the client and confirm session reuse, then test logout and sign-in.
89
-
90
- macOS has had a live course/sign-in test. Windows and Linux still require this
91
- interactive check before claiming equivalent desktop verification.
92
-
93
- Keep changes focused. Never commit session files, course materials, databases,
94
- or `.env` files. The cache/search database is local and unencrypted; private
95
- records are excluded from ordinary search. External recording links receive
96
- no Moodle cookies.
86
+ | `src/tum_mcp/moodle/` | Moodle reads, sessions, browser/WSL support, extraction and downloads |
87
+ | `src/tum_mcp/artemis/` | Artemis client, exercise/feedback models, lecture reads and lecture models |
88
+ | `src/tum_mcp/zulip/` | Zulip client and channel/topic/message models |
89
+ | `src/tum_mcp/server.py` | Combined read-only MCP service, including sixteen `moodle_*` tools |
90
+ | `src/tum_mcp/connect.py` | Unified interactive connection workflow |
91
+ | `src/tum_mcp/credentials.py`, `transport.py`, `settings.py` | Shared campus credential vault, HTTP transport and account policy |
92
+ | `src/tum_mcp/client_*.py` | Host-specific configuration and managed skill installation |
93
+ | `src/tum_mcp/study_*.py` | Course snapshots, teaching, build, preview and project-local passage comments |
94
+ | `src/tum_mcp/bundled/skills/` | Canonical versioned source of reading, study and audio skills and their references/assets |
95
+ | `npm/` | Private-runtime installation, updates, integrity and cleanup |
96
+ | `tests/` | Synthetic backend, package and owned-browser checks |
97
+
98
+ Client setup installs managed copies of the repository's skills; those copies are
99
+ outputs, not another source tree. Use `skills customize` for a personal override.
100
+ The Codex adapter generates a small host plugin because that client uses it to
101
+ load skills and MCP together; it is separate from the removed top-level Moodle
102
+ plugin distribution.
103
+
104
+ Keep Moodle's existing native-store service/account identity, session paths and
105
+ download locations stable during migrations. Environment variable names and the
106
+ `tum-moodle` CLI alias remain compatible; its implementation now resides inside
107
+ `tum_mcp.moodle`. No automatic native-store secret extraction occurs.
108
+
109
+ Extraction uses bounded subprocesses. POSIX enforces CPU/process-group limits;
110
+ Windows terminates the worker and observed children. Study imports and preview
111
+ paths are confined to the chosen project. Course sources never become agent rules.
112
+ The preview's only write endpoint accepts bounded same-origin comment operations.
113
+ Comments use private project files and optimistic revisions; comments and quoted
114
+ material remain untrusted data for the skill.
115
+
116
+ ## Study renderer
117
+
118
+ Author `study/content.json`. Formula blocks use LaTeX compiled locally into safe
119
+ native MathML; legacy MathML remains accepted. Unit `path` labels group the outline
120
+ without changing learning-progress revisions. Shared modules render all units;
121
+ content changes do not require a framework or per-unit HTML.
122
+
123
+ The distributed design/teaching/verification contracts live under
124
+ `src/tum_mcp/bundled/skills/prepare-study/references/`. Local agent notes and
125
+ screenshots belong in ignored `docs/local/` or `.omo/`. Keep real course projects,
126
+ session files, databases, downloads and environment files out of artifacts.
127
+
128
+ ## Manual checks
129
+
130
+ Use an installed artifact outside the checkout. Confirm host discovery, complete
131
+ Chromium sign-in/MFA, read a PDF and forum, download a file, then restart and check
132
+ session reuse. Automated synthetic sign-in does not certify human SSO on every OS.
133
+ For UI changes, exercise the generated app at narrow/wide widths in both themes;
134
+ check keyboard navigation, reduced motion, source links and retained progress.