@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/docs/setup.md CHANGED
@@ -1,177 +1,194 @@
1
- # Desktop setup
1
+ # Setup and troubleshooting
2
2
 
3
- This page covers the preserved **Moodle-only** installer. For the combined
4
- Artemis/Zulip/Moodle 0.4.1 pilot, use [campus setup](../README.md#manual-setup) and
5
- the [TUM MCP guide](tum-mcp.md).
3
+ [README](../README.md) · [Tools and scopes](tum-mcp.md) · [Development](development.md)
6
4
 
7
- [README](../README.md) · [macOS](#macos) · [Windows](#windows) · [Linux](#linux) ·
8
- [Updates](#updates) · [Troubleshooting](#troubleshooting) · [Uninstall](#uninstall)
5
+ Use the latest package for the connection, managed update and removal flows below.
9
6
 
10
- ## Prerequisites
7
+ ## Install
11
8
 
12
- Use your own TUM account and a Codex client that supports local plugin marketplaces.
13
- This package runs on the local computer; it does not connect ChatGPT web.
14
-
15
- ### macOS
16
-
17
- Install Git, [uv](https://docs.astral.sh/uv/getting-started/installation/), and
18
- [Google Chrome](https://www.google.com/chrome/). Homebrew users can run:
9
+ Install Node.js 22.14 or newer and a Chromium browser. No system Python, native
10
+ keyring or administrator access is required by TUM MCP. Supported bootstrap
11
+ targets are macOS ARM64/x64, Windows ARM64/x64 and glibc Linux ARM64/x86_64.
12
+ Linux needs a graphical desktop for native browser sign-in; WSL can use Windows.
19
13
 
20
14
  ```sh
21
- brew install git uv
22
- brew install --cask google-chrome
15
+ npm install --global @jamestesting888/tum-mcp@latest
16
+ tum-mcp setup --client codex
17
+ tum-mcp connect
18
+ tum-mcp doctor
23
19
  ```
24
20
 
25
- Git can also come from Apple's Command Line Tools: `xcode-select --install`.
26
- No system Python is needed. For scanned PDFs, optionally install `brew install tesseract`.
27
- Unlock your login keychain if macOS asks. Apple Silicon has been tested locally;
28
- Intel uses the same setup, but has not had a hands-on test.
21
+ Use `--client claude`, `cursor`, `antigravity`, or `generic` for another client.
22
+ Codex needs the plugin enabled and a restart when prompted. Cursor and
23
+ Antigravity setup installs all five skills and MCP configuration; restart each
24
+ client afterward. Existing MCP-only setups gain the skills through `tum-mcp update`
25
+ or another setup run. Generic setup writes configuration for manual installation.
26
+ Setup preserves unrelated settings and refuses to
27
+ replace customized entries. It does not authenticate or fetch courses.
29
28
 
30
- ### Windows
29
+ ## Connect
31
30
 
32
- Use a normal, non-administrator PowerShell window. Install prerequisites if missing:
31
+ Run **`tum-mcp connect`**, with no arguments, in an interactive terminal:
33
32
 
34
- ```powershell
35
- winget install --exact --id Git.Git
36
- winget install --exact --id astral-sh.uv
37
- winget install --exact --id Google.Chrome
38
- ```
33
+ 1. Use up/down to move and Space to select Moodle, Artemis and/or Zulip.
34
+ 2. Press Enter. If several browsers are installed, choose one and press Enter.
35
+ 3. Complete TUM sign-in/MFA in the opened window. Only selected service tabs open.
36
+ 4. Return to the terminal for the saved-connection result.
39
37
 
40
- Open a **new PowerShell window** after installation so PATH is refreshed.
41
- uv supplies Python; a separate Python installation is not required. Ensure
42
- `uv --version` works before running the installer. Codex then launches the private
43
- interpreter directly, so it does not depend on PowerShell's PATH.
38
+ Moodle uses exactly the same selector and storage flow as Artemis and Zulip.
39
+ No API key or Keychain prompt is needed. A temporary browser profile keeps the
40
+ connection separate from your everyday browser. Ctrl+C closes it and preserves
41
+ connections that already completed. A dumb terminal uses numbered prompts.
42
+ Old service arguments and `--service`/`--auth` flags are no longer accepted.
44
43
 
45
- Windows Credential Manager stores the session-encryption key. Optional OCR needs
46
- [Tesseract](https://tesseract-ocr.github.io/tessdoc/Installation.html), with its
47
- installation directory on PATH. Restart Codex after changing PATH.
44
+ Chrome, Edge, Brave, Chromium, Vivaldi and Opera are detected in their standard
45
+ locations. Selected preview channels and Opera GX are detected where installed.
46
+ For another Chromium build, set `TUM_MCP_BROWSER` to its executable path before
47
+ running connect. Compatible builds must allow Playwright automation. Safari and
48
+ Firefox are not supported.
48
49
 
49
- ### Linux
50
+ New Artemis/Zulip accounts start without content scopes. Your agent can use
51
+ status/discover to show account IDs and available course/channel metadata, then
52
+ help you choose [explicit scopes](tum-mcp.md#connections-and-scopes).
53
+ An account ID identifies a saved service connection; it is not your TUM login.
50
54
 
51
- Use a graphical desktop session with Google Chrome, Git, uv, and an
52
- unlocked **Secret Service** keyring, such as GNOME Keyring. The keyring must be
53
- available in the same D-Bus session as Codex. A headless SSH session is insufficient
54
- for interactive Moodle sign-in.
55
+ ## WSL
55
56
 
56
- For Ubuntu/Debian prerequisites:
57
+ Install Node.js and the npm package **inside WSL**. WSL 3.x is the application
58
+ release; distributions still use engine 1 or 2. See Microsoft's
59
+ [release page](https://github.com/microsoft/WSL/releases) and
60
+ [version commands](https://learn.microsoft.com/en-us/windows/wsl/basic-commands).
61
+ Both engines have dedicated CI checks on the current WSL 3.x runner image.
57
62
 
58
63
  ```sh
59
- sudo apt-get install git gnome-keyring
64
+ npm install --global @jamestesting888/tum-mcp@latest
65
+ tum-mcp setup --client cursor --host windows
66
+ tum-mcp connect
67
+ tum-mcp doctor
60
68
  ```
61
69
 
62
- Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and
63
- [Chrome](https://www.google.com/chrome/) using their official installers.
64
- For OCR, optionally install `sudo apt-get install tesseract-ocr`.
65
- On other distributions, use the equivalent packages. KWallet-only setups need
66
- a running Secret Service provider; the plugin deliberately avoids plaintext
67
- or arbitrary third-party credential backends.
70
+ Replace `cursor` with your client. `--host windows` registers the Windows app
71
+ against the WSL backend and shared Linux session paths. It writes the Windows
72
+ user's profile using a `wsl.exe` stdio command that pins the distribution and
73
+ Linux user. Omit the option for clients running inside Linux. Native Windows
74
+ installation also uses the default host. Use `--host windows` on uninstall too.
75
+ Reload or restart the Windows client after setup. The WSL distribution and its
76
+ managed runtime must remain available at the registered paths.
77
+
78
+ Connect detects Windows Chromium browsers and opens them on the Windows desktop.
79
+ First use downloads a private, checksum-verified Windows Node driver from
80
+ nodejs.org into Windows LocalAppData. A separate Windows Python or Node install
81
+ is unnecessary. The backend, session keys and encrypted sessions stay in WSL.
82
+ The bridge uses binary pipes and a temporary browser profile, without a remote
83
+ debugging TCP port. Transport is selected by a runtime pipe test, not a version
84
+ string, so a WSL package update does not change that assumption.
85
+
86
+ Windows interop and its PATH integration must be enabled: `powershell.exe` (or
87
+ `pwsh.exe`) and `wslpath` must be available from WSL. Drive paths are translated
88
+ with `wslpath`; the package does not assume `/mnt/c`. If interop is disabled,
89
+ restore it in your WSL configuration and restart the distribution. A Linux GUI
90
+ browser can also be listed when DISPLAY or WAYLAND_DISPLAY is set. Windows
91
+ browser discovery still requires functioning interop.
92
+
93
+ ## Diagnose and reconnect
94
+
95
+ - `tum-mcp doctor` shows services, client registrations, browsers and optional
96
+ tools. Saved sessions are **Not verified** until checked; registration alone
97
+ does not prove a desktop client is running the server.
98
+ - `tum-mcp doctor --live` verifies saved local sessions with bounded service
99
+ reads and checks optional GitHub CLI authentication. `--json` provides structured
100
+ output; combine the flags if needed. Default doctor checks only CLI availability.
101
+ - For optional study publishing, install GitHub CLI and complete
102
+ `gh auth login --hostname github.com` interactively on the agent's execution host.
103
+ The [publishing workflow](study.md#publish-a-study-website) uses private repositories
104
+ with public Pages websites and requires an eligible paid GitHub plan.
105
+ - An expired session uses the same `tum-mcp connect` selector. Reconnecting the
106
+ same identity preserves course/channel scopes.
107
+ - If no browser appears, check its installation or `TUM_MCP_BROWSER`. A managed
108
+ or incompatible Chromium build may prevent automation; try another browser.
109
+ - Git and Docker are optional. Neither is needed for course reads or the
110
+ GitHub CLI based study publisher.
111
+ - Do not paste passwords, cookies, MFA codes or API keys into chat or bug reports.
112
+
113
+ Sessions are encrypted with owner-restricted local key files. This avoids native
114
+ credential-store prompts, but anyone obtaining both key and ciphertext can
115
+ decrypt them. [Storage locations and recovery](tum-mcp.md#connections-and-scopes)
116
+ explain migration and backup. Existing Moodle data and downloads are preserved.
117
+
118
+ ## Update and remove
68
119
 
69
- ## Install and sign in
120
+ ```sh
121
+ npm install --global @jamestesting888/tum-mcp@latest
122
+ tum-mcp update
123
+ ```
70
124
 
71
- Run these commands on the target computer so packaging generates the correct launcher:
125
+ `update` activates the backend bundled in the invoked npm package and refreshes
126
+ previously configured clients. It does not fetch a newer npm version itself,
127
+ connect services, change scopes or register additional clients. `setup --client
128
+ NAME` explicitly registers one client and can also refresh that client's managed
129
+ files. WSL Windows registrations keep their distribution/user/data paths.
130
+
131
+ Ownership receipts track the entries and files installed by TUM MCP. Unchanged
132
+ managed files advance; unrelated settings and extra files stay intact. Direct
133
+ edits to an entry or skill stop that client's update and are reported for review;
134
+ other clients can still advance. Old runtime generations remain available for
135
+ existing pinned clients. Interrupted setup can recover a stopped lock owner;
136
+ an ownerless/unknown legacy lock requires local review. A failed new runtime is
137
+ not selected, and a damaged runtime is repaired into a fresh generation. A newer
138
+ managed client is not silently downgraded by an older package; intentional
139
+ rollback starts by unregistering that client, then registering the reviewed version.
140
+
141
+ 0.4.1/0.5.0 installations without receipts are adopted only after matching their
142
+ retained runtime's canonical client output. The seven former workflow skills and the three website skills are replaced by
143
+ `read-content`, `sync-study` and `prepare-study`; `audio-notes` adds
144
+ spoken lessons derived from the prepared website. Personal overrides
145
+ under retired names remain in the config `skills/` directory; review and merge
146
+ retrieval guidance into `read-content` before exporting a replacement pack.
147
+ Reload MCP servers in Cursor/Antigravity, restart Claude as appropriate, and
148
+ update/reinstall TUM MCP from the personal source in Codex Plugins if its cached
149
+ copy still shows the older skills. Writing source files does not activate a host.
150
+
151
+ Remove a single client with `tum-mcp uninstall --client cursor` (replace the
152
+ client as needed; add `--host windows` from WSL for a Windows client). To remove
153
+ all managed registrations before uninstalling npm:
72
154
 
73
155
  ```sh
74
- git clone --depth 1 https://github.com/jamestesting0/tum-moodle-integration.git
75
- cd tum-moodle-integration
76
- uv run scripts/install.py
156
+ tum-mcp uninstall --all
157
+ npm uninstall --global @jamestesting888/tum-mcp
77
158
  ```
78
159
 
79
- Do not copy a Mac's generated plugin or session files to Windows/Linux.
160
+ Custom edits and user-added files are preserved. Codex's local source/catalog
161
+ entry can be removed, but its cached/active plugin must also be removed or
162
+ disabled through Codex Plugins. No npm uninstall hook deletes user data.
80
163
 
81
- The installer preserves existing marketplace entries and registers the source
82
- under `~/.codex/plugins/local/tum-moodle/`. In PowerShell, `~` refers to your user
83
- profile. You can also install through the Codex CLI:
164
+ For explicit cleanup, **close coding clients first**, then run:
84
165
 
85
- ```text
86
- codex plugin add tum-moodle@personal-local
166
+ ```sh
167
+ tum-mcp uninstall --all --purge-runtime --forget-credentials
168
+ npm uninstall --global @jamestesting888/tum-mcp
87
169
  ```
88
170
 
89
- If you renamed your personal source, use its marketplace name instead.
90
- When the installer requests it, restart the desktop app completely: **Cmd+Q** on macOS;
91
- exit all app windows/background instances on Windows/Linux, then reopen it.
92
-
93
- After installation, ask **“Sign in to TUM Moodle.”** The agent checks the existing
94
- session before opening Chrome. Complete any TUM login/MFA there. Once connected,
95
- the agent offers an optional course-list check; declining it leaves setup complete.
96
-
97
- ### Installer results and repair
98
-
99
- `uv run scripts/install.py --json` returns one structured result. Progress goes to
100
- stderr; `next_actions` tells the agent exactly what remains.
101
-
102
- | Result | Meaning |
103
- | --- | --- |
104
- | `ready` | Local checks pass and the installed plugin is current. Sign-in is separate. |
105
- | `restart_required` | Software setup passed; fully restart Codex once to load it. |
106
- | `action_required` | Follow the prerequisite, keyring, or manual enablement instruction. Completed software stages are retained. |
107
- | `error` | A stage failed; the result includes the failed stage and error. |
108
-
109
- Exit codes are 0 for software success, 2 for a required user action, and 1 for an
110
- error. A local MCP check does not prove tools have reloaded in the current chat.
111
- Do not keep restarting or reinstalling while waiting for the user.
112
-
113
- If the runtime is damaged, run `uv run scripts/install.py --repair`. This reinstalls
114
- locked runtime packages without removing sessions or downloads. Healthy reruns
115
- check the existing runtime and reuse uv's cache. Native tools can work after the
116
- original checkout is moved/deleted; keep a checkout for future updates.
117
-
118
- ## Updates
119
-
120
- Run `uv run scripts/update.py` from your checkout and follow the printed actions.
121
- It uses your branch's configured upstream and a fast-forward-only pull; it never
122
- stashes edits, switches branches, or creates a merge commit.
123
-
124
- The shared installer refreshes TUM Moodle using the Codex CLI on PATH or in a standard
125
- macOS app bundle. If it cannot find the CLI, it updates the code/runtime and tells
126
- you to reinstall the plugin from your personal source in the Plugins screen.
127
- Custom marketplace names are preserved. A failed step stops the update and
128
- reports the error; fix that issue and rerun the command.
129
-
130
- For a checkout created before the updater was added, first run `git pull --ff-only`.
131
-
132
- ## Troubleshooting
133
-
134
- | Problem | Fix |
135
- | --- | --- |
136
- | No personal plugin source | Repeat packaging with `--register`, then fully restart Codex. Check that your client supports local marketplaces. |
137
- | Skills appear but tools do not | Repeat bootstrap, reinstall the plugin from your personal source, and restart Codex. Check loader errors before repeating restarts. |
138
- | `uv` is missing | Install uv and open a new terminal/app session. Bootstrap also checks `~/.local/bin` and standard Homebrew locations. |
139
- | Windows opens Microsoft Store for Python | Rerun the installer. The generated manifest must point to the private runtime's `Scripts/python.exe`. |
140
- | Native credential store unavailable | Unlock the OS store. Linux needs Secret Service in the current desktop D-Bus session; there is no plaintext fallback. |
141
- | Chrome fails to open | Install Google Chrome, then ask the plugin to sign in again. Chromium-only installations are not selected automatically. |
142
- | Session expired | Ask Codex to sign in to Moodle again. |
143
- | Scanned material fails | Install Tesseract and put it on PATH, then restart Codex and retry. Text PDFs do not require OCR. |
144
- | Search returns little | Ask Codex to index/refresh the course and check coverage. |
145
-
146
- Downloaded originals are in `~/Downloads/TUM Moodle/`. To use a different folder,
147
- set `TUM_MOODLE_DOWNLOAD_DIR` in the environment inherited by Codex.
148
- `TUM_MOODLE_DATA_DIR` overrides the session/cache location. The installed runtime
149
- stays in the standard platform data folder.
150
-
151
- For [bug reports](https://github.com/jamestesting0/tum-moodle-integration/issues),
152
- include OS/client versions and the error message. Remove credentials, cookies,
153
- personal records, and course content.
154
-
155
- ## Data locations
156
-
157
- | Platform | Moodle runtime, session, and cache |
158
- | --- | --- |
159
- | macOS | `~/Library/Application Support/TUMMoodle/` |
160
- | Windows | `%LOCALAPPDATA%\TUMMoodle\` |
161
- | Linux | `${XDG_DATA_HOME:-~/.local/share}/TUMMoodle/` |
162
-
163
- Campus settings and encrypted credentials use a separate `TUMMCP/` folder beside
164
- `TUMMoodle/`. Existing Moodle data remains in place when switching to TUM MCP.
165
-
166
- ## Uninstall
167
-
168
- 1. Ask Codex to sign out and clear the cache, then remove the plugin in Plugins.
169
- 2. To remove the personal catalog entry, delete only `tum-moodle` from
170
- `~/.agents/plugins/marketplace.json`, preserving the other entries.
171
- 3. Delete `~/.codex/plugins/local/tum-moodle/` and the
172
- [platform data folder](#data-locations) if no longer needed.
173
- 4. Remove the `tum-moodle-integration` credential entry using the OS credential
174
- manager: Keychain Access, Windows Credential Manager, or the Linux password/keyring app.
175
-
176
- Delete downloaded files separately if desired. Signing out removes this plugin's
177
- saved session; it does not sign you out of other browsers or revoke TUM sessions.
171
+ `--purge-runtime` deletes verified managed runtime generations after the Python
172
+ helper exits, and removes unchanged managed bootstrap/browser-driver caches.
173
+ Active tracked backends or unrecognized runtime files stop automatic removal.
174
+ Paths overlapping configured assignment work, downloads or Moodle data are
175
+ protected. `--forget-credentials` removes local encrypted service sessions, keys
176
+ and participation Git tokens; it does not revoke remote credentials. Native
177
+ Keychain/Credential Manager/Secret Service records and legacy Moodle sessions
178
+ stay intact. Settings, custom skills, course cache, downloads and assignment
179
+ work are retained by these commands. No command recursively deletes the campus
180
+ data root. Course audio and optional shared speech models/runtimes also remain.
181
+ Remove a shared speech cache only when explicitly requested and no other course
182
+ needs it; its host paths are documented in the audio skill. If removal is
183
+ interrupted, run npm `setup` to recover before reuse.
184
+
185
+ ## Existing Moodle-only installations
186
+
187
+ The older `tum-moodle` commands and sixteen `moodle_*` tools remain compatible.
188
+ The separate source/plugin installer retains its original native credential
189
+ store: macOS Keychain, Windows Credential Manager, or Linux Secret Service.
190
+ Its native-store identity, existing session paths and downloads remain intact.
191
+ The combined `tum-mcp serve` uses local-file storage and directs all login
192
+ requests to `tum-mcp connect`. Reconnect once through that selector to create the
193
+ new session; no automatic extraction of older native-store secrets occurs.
194
+ Disable the older plugin when activating TUM MCP to avoid duplicate tools.