@jamestesting888/tum-mcp 0.5.0 → 0.6.1

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