@jamestesting888/tum-mcp 0.4.1 → 0.5.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 (10) hide show
  1. package/README.md +61 -68
  2. package/docs/development.md +20 -8
  3. package/docs/setup.md +110 -157
  4. package/docs/tum-mcp.md +99 -40
  5. package/npm/backend/manifest.json +3 -3
  6. package/npm/backend/requirements.txt +42 -1
  7. package/npm/backend/{tum_moodle_integration-0.4.1-py3-none-any.whl → tum_moodle_integration-0.5.0-py3-none-any.whl} +0 -0
  8. package/npm/tum-mcp.mjs +2 -2
  9. package/package.json +5 -5
  10. package/docs/credential-storage-options.md +0 -86
package/README.md CHANGED
@@ -1,95 +1,88 @@
1
1
  # TUM MCP
2
2
 
3
- Use TUM Moodle, Artemis, and Zulip from your coding agent. Runs locally with
3
+ Connect your coding agent to TUM Moodle, Artemis, and Zulip. Runs locally with
4
4
  36 tools and seven workflow skills. Unofficial; independent of TUM and OpenAI.
5
5
 
6
+ **Version 0.5.0** · [npm package](https://www.npmjs.com/package/@jamestesting888/tum-mcp/v/0.5.0)
7
+
6
8
  ## Agent setup
7
9
 
8
10
  Paste this into your coding agent:
9
11
 
10
12
  ```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
13
+ 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:
14
15
  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.
16
+ Use --client claude, cursor, antigravity, or generic for a different client.
17
+ Preserve existing settings and customized skills. Follow the activation steps.
18
+ 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.
19
20
  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.
21
+ Run tum-mcp doctor to explain what is available and what still needs setup.
21
22
  ```
22
23
 
23
- ## Manual setup
24
+ ## Quick start
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@0.5.0
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.
37
-
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).
41
-
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.
45
-
46
- ## What you can do
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).
47
39
 
48
- | Service | Available |
40
+ | Client | Setup |
49
41
  | --- | --- |
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 |
53
-
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.
57
-
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).
63
-
64
- ## Privacy
65
-
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.
71
-
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).
75
-
76
- ## Update and support
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 |
62
+ | --- | --- |
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 |
77
66
 
78
- Install the reviewed version you want, then rerun the client setup:
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.
79
71
 
80
- ```sh
81
- npm install --global @jamestesting888/tum-mcp@latest
82
- tum-mcp setup --client codex
83
- ```
72
+ ## Privacy and updates
84
73
 
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.
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.
88
79
 
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)
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.
91
82
 
92
- ## License
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).
93
87
 
94
- [MIT](LICENSE). The TUM logo retains its original rights; see [NOTICE](NOTICE).
95
- No trademark rights are granted.
88
+ [MIT](LICENSE) · [NOTICE](NOTICE) · [Report a problem](https://github.com/jamestesting0/tum-mcp/issues)
package/docs/development.md CHANGED
@@ -2,9 +2,12 @@
2
2
 
3
3
  [README](../README.md) · [Setup](setup.md)
4
4
 
5
- For the combined 0.4.1 campus pilot, see the [TUM MCP guide](tum-mcp.md) and
5
+ For the combined campus package, see the [TUM MCP guide](tum-mcp.md) and
6
6
  [current verification limits](tum-mcp.md#build-and-test-the-local-package). This page also
7
- covers the preserved Moodle-only installer.
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.
8
11
 
9
12
  ## Checks
10
13
 
@@ -18,7 +21,7 @@ uv build
18
21
  node npm/build.mjs
19
22
  npm test
20
23
  npm pack --ignore-scripts --pack-destination dist
21
- npm run test:consumer -- dist/jamestesting888-tum-mcp-0.4.1.tgz
24
+ npm run test:consumer -- dist/jamestesting888-tum-mcp-0.5.0.tgz
22
25
  ```
23
26
 
24
27
  Python 3.13 is the managed runtime on every platform. Install Tesseract for the
@@ -27,7 +30,12 @@ credentials; no Moodle login is needed. No language-server installation is requi
27
30
 
28
31
  GitHub Actions runs the suite on macOS, Windows, and Ubuntu, including packaged
29
32
  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.
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.
31
39
  The campus additions configure fresh npm consumer checks on all three runners;
32
40
  those checks must pass for the release commit before claiming release coverage.
33
41
 
@@ -44,7 +52,8 @@ one test downloads a lecture. Never supply personal credentials to public CI.
44
52
  | Module | Responsibility |
45
53
  | --- | --- |
46
54
  | `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 |
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 |
48
57
  | `server.py`, `service.py` | MCP tools and retrieval coordination |
49
58
  | `http_client.py` | Read-only Moodle network boundary |
50
59
  | `parsing.py`, `forums.py`, `personal_records.py` | Moodle content and explicit private-record reads |
@@ -69,9 +78,11 @@ Set `TUM_MOODLE_INSTALLER_EVIDENCE` to write stage timings. The external Codex C
69
78
  is synthetic in those tests; dependency installation and MCP startup are real.
70
79
  Timings exclude agent latency, user sign-in/MFA, and application restart time.
71
80
 
72
- Credentials use explicit OS backends. Unsupported or unavailable stores fail
81
+ The preserved Moodle-only installer uses explicit OS backends. Unsupported or unavailable stores fail
73
82
  with `SETUP_REQUIRED`; environment-selected plaintext alternatives are ignored.
74
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.
75
86
 
76
87
  Extraction runs in a subprocess with a 60-second wall limit and 512 MiB aggregate
77
88
  memory monitoring. POSIX also enforces a CPU limit and kills the process group;
@@ -82,12 +93,13 @@ Windows terminates the worker and its observed child processes.
82
93
  Automated tests do not replace a desktop check. On each target OS, verify:
83
94
 
84
95
  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.
96
+ 2. Confirm native tools appear, then complete Chromium sign-in and MFA.
86
97
  3. List current-semester courses, read a PDF, and check a forum.
87
98
  4. Download one material and open the returned file locally.
88
99
  5. Restart the client and confirm session reuse, then test logout and sign-in.
89
100
 
90
- macOS has had a live course/sign-in test. Windows and Linux still require this
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
91
103
  interactive check before claiming equivalent desktop verification.
92
104
 
93
105
  Keep changes focused. Never commit session files, course materials, databases,
package/docs/setup.md CHANGED
@@ -1,177 +1,130 @@
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
+ These instructions apply to **0.5.0**. Upgrade older installations before using
6
+ the interactive connection flow below.
9
7
 
10
- ## Prerequisites
8
+ ## Install
11
9
 
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:
10
+ Install Node.js 22.14 or newer and a Chromium browser. No system Python, native
11
+ keyring or administrator access is required by TUM MCP. Supported bootstrap
12
+ targets are macOS ARM64/x64, Windows ARM64/x64 and glibc Linux ARM64/x86_64.
13
+ Linux needs a graphical desktop for native browser sign-in; WSL can use Windows.
19
14
 
20
15
  ```sh
21
- brew install git uv
22
- brew install --cask google-chrome
16
+ npm install --global @jamestesting888/tum-mcp@0.5.0
17
+ tum-mcp setup --client codex
18
+ tum-mcp connect
19
+ tum-mcp doctor
23
20
  ```
24
21
 
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.
22
+ Use `--client claude`, `cursor`, `antigravity`, or `generic` for another client.
23
+ Codex needs the plugin enabled and a restart when prompted. Cursor and
24
+ Antigravity need their MCP servers reloaded. Generic setup writes configuration
25
+ for manual installation. Setup preserves unrelated settings and refuses to
26
+ replace customized entries. It does not authenticate or fetch courses.
29
27
 
30
- ### Windows
28
+ ## Connect
31
29
 
32
- Use a normal, non-administrator PowerShell window. Install prerequisites if missing:
30
+ Run **`tum-mcp connect`**, with no arguments, in an interactive terminal:
33
31
 
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
- ```
32
+ 1. Use up/down to move and Space to select Moodle, Artemis and/or Zulip.
33
+ 2. Press Enter. If several browsers are installed, choose one and press Enter.
34
+ 3. Complete TUM sign-in/MFA in the opened window. Only selected service tabs open.
35
+ 4. Return to the terminal for the saved-connection result.
39
36
 
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.
37
+ Moodle uses exactly the same selector and storage flow as Artemis and Zulip.
38
+ No API key or Keychain prompt is needed. A temporary browser profile keeps the
39
+ connection separate from your everyday browser. Ctrl+C closes it and preserves
40
+ connections that already completed. A dumb terminal uses numbered prompts.
41
+ Old service arguments and `--service`/`--auth` flags are no longer accepted.
44
42
 
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.
43
+ Chrome, Edge, Brave, Chromium, Vivaldi and Opera are detected in their standard
44
+ locations. Selected preview channels and Opera GX are detected where installed.
45
+ For another Chromium build, set `TUM_MCP_BROWSER` to its executable path before
46
+ running connect. Compatible builds must allow Playwright automation. Safari and
47
+ Firefox are not supported.
48
48
 
49
- ### Linux
49
+ New Artemis/Zulip accounts start without content scopes. Your agent can use
50
+ status/discover to show account IDs and available course/channel metadata, then
51
+ help you choose [explicit scopes](tum-mcp.md#connections-and-scopes).
52
+ An account ID identifies a saved service connection; it is not your TUM login.
50
53
 
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.
54
+ ## WSL
55
55
 
56
- For Ubuntu/Debian prerequisites:
56
+ Install Node.js and the npm package **inside WSL**. WSL 3.x is the application
57
+ release; distributions still use engine 1 or 2. See Microsoft's
58
+ [release page](https://github.com/microsoft/WSL/releases) and
59
+ [version commands](https://learn.microsoft.com/en-us/windows/wsl/basic-commands).
60
+ Both engines have dedicated CI checks on the current WSL 3.x runner image.
57
61
 
58
62
  ```sh
59
- sudo apt-get install git gnome-keyring
60
- ```
61
-
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.
68
-
69
- ## Install and sign in
70
-
71
- Run these commands on the target computer so packaging generates the correct launcher:
72
-
73
- ```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
77
- ```
78
-
79
- Do not copy a Mac's generated plugin or session files to Windows/Linux.
80
-
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:
84
-
85
- ```text
86
- codex plugin add tum-moodle@personal-local
63
+ npm install --global @jamestesting888/tum-mcp@0.5.0
64
+ tum-mcp setup --client cursor --host windows
65
+ tum-mcp connect
66
+ tum-mcp doctor
87
67
  ```
88
68
 
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.
69
+ Replace `cursor` with your client. `--host windows` registers the Windows app
70
+ against the WSL backend and shared Linux session paths. It writes the Windows
71
+ user's profile using a `wsl.exe` stdio command that pins the distribution and
72
+ Linux user. Omit the option for clients running inside Linux. Native Windows
73
+ installation also uses the default host. Use `--host windows` on uninstall too.
74
+ Reload or restart the Windows client after setup. The WSL distribution and its
75
+ managed runtime must remain available at the registered paths.
76
+
77
+ Connect detects Windows Chromium browsers and opens them on the Windows desktop.
78
+ First use downloads a private, checksum-verified Windows Node driver from
79
+ nodejs.org into Windows LocalAppData. A separate Windows Python or Node install
80
+ is unnecessary. The backend, session keys and encrypted sessions stay in WSL.
81
+ The bridge uses binary pipes and a temporary browser profile, without a remote
82
+ debugging TCP port. Transport is selected by a runtime pipe test, not a version
83
+ string, so a WSL package update does not change that assumption.
84
+
85
+ Windows interop and its PATH integration must be enabled: `powershell.exe` (or
86
+ `pwsh.exe`) and `wslpath` must be available from WSL. Drive paths are translated
87
+ with `wslpath`; the package does not assume `/mnt/c`. If interop is disabled,
88
+ restore it in your WSL configuration and restart the distribution. A Linux GUI
89
+ browser can also be listed when DISPLAY or WAYLAND_DISPLAY is set. Windows
90
+ browser discovery still requires functioning interop.
91
+
92
+ ## Diagnose and reconnect
93
+
94
+ - `tum-mcp doctor` shows services, client registrations, browsers and optional
95
+ tools. Saved sessions are **Not verified** until checked; registration alone
96
+ does not prove a desktop client is running the server.
97
+ - `tum-mcp doctor --live` verifies saved local sessions with bounded service
98
+ reads. `--json` provides structured output; combine the flags if needed.
99
+ - An expired session uses the same `tum-mcp connect` selector. Reconnecting the
100
+ same identity preserves course/channel scopes.
101
+ - If no browser appears, check its installation or `TUM_MCP_BROWSER`. A managed
102
+ or incompatible Chromium build may prevent automation; try another browser.
103
+ - Git is optional for assignment workspaces. Docker is optional for approved
104
+ isolated tests. Missing either does not prevent course reads.
105
+ - Do not paste passwords, cookies, MFA codes or API keys into chat or bug reports.
106
+
107
+ Sessions are encrypted with owner-restricted local key files. This avoids native
108
+ credential-store prompts, but anyone obtaining both key and ciphertext can
109
+ decrypt them. [Storage locations and recovery](tum-mcp.md#connections-and-scopes)
110
+ explain migration and backup. Existing Moodle data and downloads are preserved.
111
+
112
+ ## Update and remove
113
+
114
+ Update with `npm install --global @jamestesting888/tum-mcp@latest`, then rerun
115
+ setup. Review conflicts instead of deleting customized client configuration.
116
+ `tum-mcp uninstall --client cursor` (or your client) removes unchanged managed
117
+ registration while retaining sessions, downloads and personal work. Codex plugin
118
+ removal uses its Plugins UI. Remove the npm package separately with
119
+ `npm uninstall --global @jamestesting888/tum-mcp`.
120
+
121
+ ## Existing Moodle-only installations
122
+
123
+ The older `tum-moodle` commands and sixteen `moodle_*` tools remain compatible.
124
+ The separate source/plugin installer retains its original native credential
125
+ store: macOS Keychain, Windows Credential Manager, or Linux Secret Service.
126
+ Its native-store identity, existing session paths and downloads remain intact.
127
+ The combined `tum-mcp serve` uses local-file storage and directs all login
128
+ requests to `tum-mcp connect`. Reconnect once through that selector to create the
129
+ new session; no automatic extraction of older native-store secrets occurs.
130
+ Disable the older plugin when activating TUM MCP to avoid duplicate tools.
package/docs/tum-mcp.md CHANGED
@@ -1,10 +1,10 @@
1
- # TUM MCP 0.4.1 guide
1
+ # TUM MCP guide
2
2
 
3
3
  Package: `@jamestesting888/tum-mcp`, CLI: `tum-mcp`, backend: Python 3.13.
4
- Patch 0.4.1 fixes UTF-8 skill and client-configuration handling on Windows code pages.
5
- Version 0.4.1 is distributed as a public read/local-assistance pilot. The complete
6
- revision 3 remote workflow is not included; its approval and host boundaries
7
- remain unverified and its remote-action tools remain disabled.
4
+ Version **0.5.0** provides interactive service and browser selection, local-file
5
+ credential keys, richer diagnostics, Cursor/Antigravity adapters, and WSL-backed
6
+ Windows client setup. The package supports campus reads and local assignment
7
+ assistance; remote-action tools remain disabled.
8
8
 
9
9
  ## Current capabilities
10
10
 
@@ -19,7 +19,7 @@ An internal, release-gated executor covers exact-action fingerprints, encrypted
19
19
  expiring one-use grants, account/scope/credential revalidation, and durable
20
20
  unknown-outcome receipts. Synthetic tests cover one POST or exact-commit push,
21
21
  copied/fabricated approvals, changed targets, and lost responses. No MCP write
22
- tool, approval issuer, or preference can open this development release's gate.
22
+ tool, approval issuer, or preference can open this version's gate.
23
23
  The internal executor is groundwork for Phase 5; no live-action certification is claimed.
24
24
  Revision 3 Phase 5 needs a demonstrated trusted approval/credential boundary and
25
25
  safe practice-exercise verification before those tools can be exposed. A
@@ -35,7 +35,7 @@ public discovery. Provider routes were checked against that Artemis revision.
35
35
 
36
36
  ## Build and test the local package
37
37
 
38
- For normal installation, use `npm install --global @jamestesting888/tum-mcp@0.4.1`
38
+ For normal installation, use `npm install --global @jamestesting888/tum-mcp@0.5.0`
39
39
  and `tum-mcp setup --client codex`. The following commands are for maintainers.
40
40
 
41
41
  ```sh
@@ -46,7 +46,7 @@ uv run pytest -q -m 'not live'
46
46
  node npm/build.mjs
47
47
  npm test
48
48
  npm pack --ignore-scripts --pack-destination dist
49
- npm run test:consumer -- dist/jamestesting888-tum-mcp-0.4.1.tgz
49
+ npm run test:consumer -- dist/jamestesting888-tum-mcp-0.5.0.tgz
50
50
  ```
51
51
 
52
52
  The npm artifact has an explicit file allowlist, a bundled backend wheel,
@@ -69,13 +69,14 @@ and Python 3.13.15; an existing matching uv, including the verified cached downl
69
69
  is reused. Source checkouts and system
70
70
  Python are unnecessary for consumers. Supported bootstrap targets are macOS
71
71
  arm64/x64, Windows arm64/x64, and glibc Linux arm64/x64; hands-on verification is
72
- recorded separately. Linux still needs a native Secret Service for credentials.
72
+ recorded separately. New campus sessions use permission-restricted local keys and need no Secret Service.
73
73
  Clean consumer bootstrap, idempotent setup, diagnostics, and skill validation
74
74
  passed on macOS ARM64 and in Linux ARM64 and x86_64 containers. The x86_64 check
75
75
  ran through Docker amd64 emulation on an ARM64 Mac; packaged MCP protocol checks
76
76
  and an encrypted credential round trip through a real GNOME Secret Service in an
77
77
  isolated D-Bus session also passed. Real Linux desktop browser sign-in, macOS x64,
78
- and Windows hands-on checks remain open. The installer targets glibc Linux
78
+ and Windows hands-on checks remain open. New storage and terminal behavior need
79
+ the current checkout’s test evidence; earlier native-store results do not certify them. The installer targets glibc Linux
79
80
  x86_64/amd64 and aarch64/ARM64.
80
81
 
81
82
  `update` provisions the backend bundled in the invoked package and preserves
@@ -89,14 +90,14 @@ available to existing client registrations. Use an older reviewed package and
89
90
  rerun its setup to restore that runtime, reviewing any client configuration diff.
90
91
 
91
92
  For platforms outside the bootstrap targets, the source installation needs
92
- Python 3.13+, uv, Git, and a native credential store: run `uv sync --locked`, then
93
- `uv run tum-mcp setup --client generic` from the checkout. Chrome is needed for
94
- browser onboarding. Docker is needed only for isolated assignment tests.
93
+ Python 3.13+, uv, and Git: run `uv sync --locked`, then
94
+ `uv run tum-mcp setup --client generic` from the checkout. An installed Chromium browser is needed for
95
+ browser onboarding. See [setup](setup.md) for browser choices and WSL. Docker is needed only for isolated assignment tests.
95
96
 
96
97
  ## Connections and scopes
97
98
 
98
99
  ```sh
99
- tum-mcp connect campus
100
+ tum-mcp connect
100
101
  tum-mcp status
101
102
  tum-mcp discover artemis ACCOUNT_ID
102
103
  tum-mcp discover zulip ACCOUNT_ID
@@ -104,19 +105,26 @@ tum-mcp scope artemis ACCOUNT_ID --course COURSE_ID --sensitive --workspace
104
105
  tum-mcp scope zulip ACCOUNT_ID --channel CHANNEL_ID
105
106
  ```
106
107
 
107
- `connect campus` opens Artemis and Zulip in one temporary Chrome context for
108
- user-driven sign-in/MFA; the identity provider can reuse its session between tabs.
109
- Only each service's own host cookies are encrypted and saved. Identity-provider
110
- cookies are discarded when the browser closes. Single-service commands remain
111
- available as `connect artemis` and `connect zulip`.
112
-
113
- Zulip browser sessions use its read-only `/json/` routes; API-key authentication
114
- uses `/api/v1/`. A successful authenticated `/json/users/me` read was verified on
115
- TUM's deployment. This separation is also documented in
116
- [Zulip's dispatcher](https://github.com/zulip/zulip/blob/12.0/zerver/lib/rest.py).
117
- Session expiry requires browser reconnection. API keys are optional:
118
- `connect zulip --auth api-key` imports an existing key through hidden local input.
119
- Never paste credentials in chat. Browser login and Artemis Git access remain
108
+ `connect` takes no arguments or connection options. Move with up/down, toggle
109
+ services with Space, and press Enter. Choose a browser when more than one is
110
+ installed. Only selected tabs open in one temporary browser context. Moodle,
111
+ Artemis and Zulip all follow this flow; no separate Moodle login is needed.
112
+ Sign-in/MFA stays in the browser. `TERM=dumb` uses numbered prompts. Ctrl+C
113
+ cancels and retains completed connections. Old service/campus arguments and
114
+ `--service`/`--auth` flags are rejected before any browser opens.
115
+
116
+ Detection covers Chrome, Edge, Brave, Chromium, Vivaldi, Opera and selected
117
+ preview channels. Set `TUM_MCP_BROWSER` to an executable path for another
118
+ compatible Chromium build. Browsers must permit Playwright automation. Firefox
119
+ and Safari use different protocols and are outside this integration.
120
+ Only service-owned cookies are saved; identity-provider cookies are discarded
121
+ when the temporary browser closes. Existing browser profiles are never imported.
122
+
123
+ Zulip uses its read-only `/json/` routes with the browser session; no API key is
124
+ required. Reconnect through the same selector when a session expires. Existing
125
+ API-key records remain readable for compatibility, but key entry is not part of
126
+ onboarding. See [Zulip's dispatcher](https://github.com/zulip/zulip/blob/12.0/zerver/lib/rest.py).
127
+ Browser login and Artemis Git access remain
120
128
  separate capabilities. Existing scopes survive reconnection; new identities start
121
129
  with empty scopes. Private channels additionally require `--private-channel ID` while
122
130
  remaining in `--channel ID`. `--sensitive` enables own Artemis participation and
@@ -130,14 +138,28 @@ was started, code pushed, message sent, or read flag changed by these checks.
130
138
 
131
139
  Settings live outside the installed package in `TUMMCP/config/preferences.json`.
132
140
  The default data directory is beside the legacy `TUMMoodle` directory on each OS.
133
- Existing Moodle data is retained in place, preserving the keychain lookup. New
134
- service credentials are encrypted separately with an account/provider/origin-bound
135
- identity and a native credential-store key. There is no plaintext fallback.
136
- For the platform trade-offs, upstream examples, and the distinction between
137
- Keychain and desktop-app permissions, see
138
- [credential storage options](credential-storage-options.md). Use the installed
139
- `tum-mcp` runtime from the first login to avoid development-to-packaged Python
140
- permission changes.
141
+ Existing Moodle data and its native-store identity are retained in place. New
142
+ campus connections deliberately do not read or migrate native-store secrets;
143
+ reconnect each service once to use local-file storage. The combined MCP process
144
+ uses that storage for all `moodle_*` compatibility tools. The separate Moodle-only
145
+ installer keeps its native-store default.
146
+ Previously imported Artemis Git tokens also need re-importing into the new store;
147
+ browser sign-in does not import them or open the old native store.
148
+
149
+ New Moodle sessions live under `TUMMoodle/local-session/`; campus credentials live
150
+ under `TUMMCP/credentials/local/`. Each directory has an independent `session.key`.
151
+ Encrypted records and keys have owner-only permissions: 0700 directories / 0600
152
+ keys on POSIX; protected current-user DACLs on Windows through PowerShell. No
153
+ administrator privileges are requested. This avoids Keychain/Secret Service
154
+ prompts but protects less than a native store. A copy of both ciphertext and key
155
+ is sufficient to decrypt a session. Do not share, sync publicly, or package them.
156
+
157
+ Missing or damaged keys fail closed. Restore the matching key from a private
158
+ backup. To start fresh, stop clients and move the affected **local storage folder**
159
+ to a private backup before reconnecting; this also resets its stored Git tokens.
160
+ Never remove the legacy Moodle directory or downloads to repair a login.
161
+ Native-store records remain available to the older installation for rollback.
162
+
141
163
  Zulip message text is retrieved live and is not persisted. Retrieved excerpts may
142
164
  be transmitted to the coding agent's configured AI provider. Moodle's existing
143
165
  document cache retains its documented plaintext/expiry behavior.
@@ -145,6 +167,20 @@ document cache retains its documented plaintext/expiry behavior.
145
167
  Course nicknames can be mapped in `mappings` using explicit per-service IDs.
146
168
  The tools resolve one exact mapping; ambiguity never grants broader access.
147
169
 
170
+ ## Diagnostics
171
+
172
+ `doctor` reads local configuration and checks runtime prerequisites. It does not
173
+ open a browser, contact campus services, decrypt sessions, or read native stores.
174
+ Saved sessions are **Not verified** until checked. Missing optional Git/Docker
175
+ capabilities do not prevent course reads. Client registration is distinguished
176
+ from activation; the host must confirm a running MCP connection after setup.
177
+
178
+ Use `doctor --live` for bounded authenticated identity checks on saved local
179
+ sessions. This reads Moodle's course overview and Artemis/Zulip identity only;
180
+ it does not broaden content scopes. `doctor --json` emits schema-versioned JSON
181
+ without terminal styling; combine both flags for live automation. Paths appear
182
+ in JSON for troubleshooting. Default diagnostics do not create state folders.
183
+
148
184
  ## Assignment workspaces and tests
149
185
 
150
186
  The user requests `artemis_prepare_workspace` with explicit account/course/
@@ -202,6 +238,28 @@ local MCP server, and installs the skill pack. Codex's submission invocation
202
238
  policy and Claude's `disable-model-invocation` metadata are handled independently.
203
239
  Generic clients receive configuration plus optional manual skill export.
204
240
 
241
+ `setup --client cursor` writes `~/.cursor/mcp.json`.
242
+ `setup --client antigravity` writes `~/.gemini/config/mcp_config.json`; an existing
243
+ legacy `~/.gemini/antigravity/mcp_config.json` is reused when no current file exists.
244
+ Both merge the `tum` stdio entry and preserve unrelated settings.
245
+ From WSL, append `--host windows` to any client setup command to target its
246
+ Windows profile. The generated `wsl.exe` command pins the distribution, Linux
247
+ user, managed Python and data paths, so clients share the WSL connection.
248
+ Use the same host option on uninstall. Native Windows uses the default host.
249
+ `doctor` in WSL shows local and Windows client registrations separately.
250
+ See [the WSL guide](setup.md#wsl) for interop requirements. Conflicting or
251
+ invalid configuration is preserved with an actionable error. Reload MCP servers
252
+ in the host after setup; actual host activation is not certified by writing files.
253
+ See the official [Cursor MCP documentation](https://cursor.com/docs/mcp) and
254
+ [Antigravity MCP documentation](https://antigravity.google/docs/mcp).
255
+
256
+ These two adapters install MCP configuration only. Export the workflow skills
257
+ below and install them using the host's documented skill mechanism after review.
258
+ This avoids claiming equivalent invocation controls across clients. No new
259
+ Cursor/Antigravity model-routing or native desktop activation result is claimed.
260
+ `uninstall --client cursor` and `uninstall --client antigravity` remove only an
261
+ unchanged managed entry; sessions and personal work stay intact.
262
+
205
263
  ```sh
206
264
  tum-mcp skills list
207
265
  tum-mcp skills inspect tum-zulip-research
@@ -231,16 +289,17 @@ release; no measured activation accuracy is claimed by the structural checks.
231
289
 
232
290
  ## Release scope
233
291
 
234
- The maintainer authorized public npm distribution of the current 0.4.1 pilot.
235
- This does not certify the complete revision 3 workflow or all desktop targets.
236
- Host/model skill-selection trials, native Windows/macOS x64 onboarding, and real
237
- Linux desktop browser sign-in remain incomplete. Remote workflows also need a
292
+ Version 0.5.0 has automated installation, browser transport, storage and MCP
293
+ checks on macOS, Windows, Linux, and both distribution engines on WSL 3.0.3.
294
+ These checks use synthetic pages and credentials. Fresh human SSO/MFA and
295
+ desktop-client activation on every target remain separate manual checks, as do
296
+ host/model skill-selection trials. Remote workflows also need a
238
297
  trusted approval/host credential boundary and safe practice verification before
239
298
  they can be exposed. Browser sign-in alone does not establish a saved backend connection.
240
299
 
241
300
  Maintainer checks include the relevant tests, a reviewed tarball inventory,
242
301
  integrity checks, and an isolated consumer install. Never publish or stage npm
243
302
  packages as a test. Review and authorization of a registry upload are separate
244
- from a GitHub source push; this pilot is being published to npm first.
303
+ from a GitHub source push.
245
304
  `tum-mcp status` reports registry state as `not_checked`, since it inspects local
246
305
  configuration without making registry requests.
package/npm/backend/manifest.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "wheel": "tum_moodle_integration-0.4.1-py3-none-any.whl",
3
- "wheelSha256": "5e5b586e0bfff7504bb4026d155e274283dfb47d69d7f4b9077e95c7374b71fc",
4
- "requirementsSha256": "2ce7807c938fb7aa2e74fbc9537555830240ea43a2858c2f436ba5efd031dda6"
2
+ "wheel": "tum_moodle_integration-0.5.0-py3-none-any.whl",
3
+ "wheelSha256": "ec23f7335cd579eb96dabb62ee835c8d35c8e17f2900d194162bb6887d878b7e",
4
+ "requirementsSha256": "af80954b16be4f432ad3cdc56a0354236703a852b3f50206ba688355c723a118"
5
5
  }
package/npm/backend/requirements.txt CHANGED
@@ -431,6 +431,10 @@ playwright==1.64.0 \
431
431
  --hash=sha256:97a5c247f1130f3343f097caf3bb1e79358d6b6cfa3550d97ecd721d1905911a \
432
432
  --hash=sha256:d76a501c9930b5a097b00e2448cda2200122a1e8e4be762ff535c1b076277737
433
433
  # via tum-moodle-integration
434
+ prompt-toolkit==3.0.53 \
435
+ --hash=sha256:01c0891d7f9237d5e339f7d3e42cdae80b7534abb1c7c0e3352efba6231492f2 \
436
+ --hash=sha256:9ec8a0ad96d5c56148b3f914aa79c1564c3fde5d2e6b876e7bc327e353cf8fa6
437
+ # via questionary
434
438
  psutil==7.2.2 \
435
439
  --hash=sha256:0746f5f8d406af344fd547f1c8daa5f5c33dbc293bb8d6a16d80b4bb88f59372 \
436
440
  --hash=sha256:076a2d2f923fd4821644f5ba89f059523da90dc9014e85f8e45a5774ca5bc6f9 \
@@ -635,6 +639,10 @@ pyyaml==6.0.3 \
635
639
  --hash=sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c \
636
640
  --hash=sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6
637
641
  # via tum-moodle-integration
642
+ questionary==2.1.1 \
643
+ --hash=sha256:3d7e980292bb0107abaa79c68dd3eee3c561b83a0f89ae482860b181c8bd412d \
644
+ --hash=sha256:a51af13f345f1cdea62347589fbb6df3b290306ab8930713bfae4d475a7d4a59
645
+ # via tum-moodle-integration
638
646
  referencing==0.37.0 \
639
647
  --hash=sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231 \
640
648
  --hash=sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8
@@ -644,7 +652,9 @@ referencing==0.37.0 \
644
652
  rich==15.0.0 \
645
653
  --hash=sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb \
646
654
  --hash=sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36
647
- # via typer
655
+ # via
656
+ # tum-moodle-integration
657
+ # typer
648
658
  rpds-py==2026.9.1 \
649
659
  --hash=sha256:00ba2d8c7dd4ee537978ddf4b3fbd712bef2d8751603f7f3146b3f4287768e25 \
650
660
  --hash=sha256:028ad274ea951dac64491b5d1e65712a4aeabfdbdb9fccf797b57bd899b0c495 \
@@ -778,3 +788,34 @@ uvicorn==0.54.0 ; sys_platform != 'emscripten' \
778
788
  --hash=sha256:505bdb0f318731d45f1f712071fc781a8981f6847a31c902c9f5e652d4f67faf \
779
789
  --hash=sha256:a2e33cbfaa0306f8e6b0c13e0cb89d7d7a2da3e62b90c66e18c33d9807b28620
780
790
  # via mcp
791
+ wcwidth==0.9.3 \
792
+ --hash=sha256:16d09df90b3a8f799ea14c726a41d9b906c3104f95f46d158e1ebe45cf4d547b \
793
+ --hash=sha256:2f875a4c9e62df2ecfa70d99b24c551f2245609858e179c3a40e74631b2d08a4 \
794
+ --hash=sha256:3b119ef60177a92b4f298b80e98464c2922a1fba3ed77fe9a2bcb69edf1b9af4 \
795
+ --hash=sha256:3e3e31d6c17d6da3051f7eb854d5e4bebdc52a08a7a52adc2da6f15af51304e8 \
796
+ --hash=sha256:457f986e4867111cb037ccbf0d97ae100b1ecad030d43a020e7207f1e29649d5 \
797
+ --hash=sha256:52a13869704d43a4add59c68ebc892198e53063883114783bf0b7457e250e3f4 \
798
+ --hash=sha256:537ea00b6792bb243cd09582322c54dbc848879e5d34ea4c5fee0147529685ab \
799
+ --hash=sha256:569a0cdb826d3097b6dbacfaa45aa0002d72a2ba6fa8a63251ea43ac4dd7b6a4 \
800
+ --hash=sha256:5d3b0b6c37f40e8d8298941ec373a426a892bb9a514328abcc9226cdc60ae6eb \
801
+ --hash=sha256:658dcbce546e7f28ee361f88e4a8e591dd56f46bff6084e11b4ad8310ed99946 \
802
+ --hash=sha256:6f3e855d3a09af8b7b6d56e76bc270681032f8a37d527a8d5707a441958e3730 \
803
+ --hash=sha256:70a2ca239b85a219324968993c76c117fe423d4e1a7c9d860c999c66192f2570 \
804
+ --hash=sha256:7a95d8c784cbccbbcb808eaadfd156cd282b2bdd95e89b32505e3443381ce61d \
805
+ --hash=sha256:80557db1f77148b78e1b3c2a9cc4ebc4feabef42aaf69a555565057031c32367 \
806
+ --hash=sha256:9470169fcb4e5340269175ebb3642dd5bfc8f82da8c86f29fc1fefc6c2b9bc1b \
807
+ --hash=sha256:9ab8bfee107e08de09e15f9f6afb9fe0f64c8d64fd296d0d8557bafe71ea3f93 \
808
+ --hash=sha256:9e1cbe18c18d152e1e68e4e2561dab6c2bc988f8fd337a1fb2e1e0809c3fa568 \
809
+ --hash=sha256:a44acbb23b525070a0b8c343dd7cab7a4020aff73b38804f7a66d6a66e16e3fc \
810
+ --hash=sha256:a7c0405a3bf3c564e481d6b2d55c99cc231bb68cf8f4a0995944bbce5ebf1a5d \
811
+ --hash=sha256:aab90ab489850f87633922c3064f6d0442d8f6ae5407a62f82bdb1f424179c05 \
812
+ --hash=sha256:c12abd75ffcbad417e7770a6feb82413c102ccce5c435068c39a82e2218b00b3 \
813
+ --hash=sha256:c1bbc8ebf133422cadfefea95a9f89d6c9e9a1ae19930bef7862a9b59b20bbad \
814
+ --hash=sha256:c4531d93344441a7948e665854f0c40e3a8342ee106436d1531efa7a9fa7641e \
815
+ --hash=sha256:dfe7cfbd4cb59db9fe0931bd6091ab4a95b3acc5d56bfb50fa9fef0ccba5dc5c \
816
+ --hash=sha256:e3c9069c54a2da0bf4f6c7e65a735cb1da0f47601a15cb5fef7e4b6ffca4cf60 \
817
+ --hash=sha256:e9362be098c43d076aa43754face3cc0180fa81cea9ba304240b15490f2617e8 \
818
+ --hash=sha256:eef39f3260991d8767189d296f0116fa4b45ad9c3a9a16d5af9187fb66b27564 \
819
+ --hash=sha256:f11789e520ade8017fa93b01a4b8985571bb433eaefc2f857b57e36875e2e1d8 \
820
+ --hash=sha256:f2f943c4ef14e9baba730740265f4e5bf5fc8473550e36cd92828cd5663561a6
821
+ # via prompt-toolkit
package/npm/tum-mcp.mjs CHANGED
@@ -5,9 +5,9 @@ import { currentPython, ensureRuntime } from './runtime.mjs';
5
5
  const args = process.argv.slice(2);
6
6
  try {
7
7
  if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]))) {
8
- console.log('TUM MCP 0.4.1\nCommands: setup [--client codex|claude|generic], connect, scope, discover, status, doctor, serve, skills, workspace, actions, logout, uninstall, update\nRun setup explicitly to provision the managed Python backend.');
8
+ console.log('TUM MCP 0.5.0\nCommands: setup [--client codex|claude|cursor|antigravity|generic], connect, scope, discover, status, doctor [--json] [--live], serve, skills, workspace, actions, logout, uninstall, update\nRun connect without arguments to select services and an installed Chromium browser. Run setup explicitly to provision the managed Python backend.');
9
9
  } else if (['--version', 'version'].includes(args[0])) {
10
- console.log('0.4.1');
10
+ console.log('0.5.0');
11
11
  } else {
12
12
  const setup = ['setup', 'update'].includes(args[0]);
13
13
  const python = setup ? await ensureRuntime() : currentPython();
package/package.json CHANGED
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "name": "@jamestesting888/tum-mcp",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
4
4
  "description": "Local-first TUM Moodle, Artemis, and Zulip integration with campus workflow skills",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {"tum-mcp": "npm/tum-mcp.mjs"},
8
8
  "engines": {"node": ">=22.14.0"},
9
- "files": ["npm/tum-mcp.mjs", "npm/runtime.mjs", "npm/download.mjs", "npm/uv-artifacts.json", "npm/backend/*.whl", "npm/backend/requirements.txt", "npm/backend/manifest.json", "LICENSE", "NOTICE", "README.md", "docs/setup.md", "docs/development.md", "docs/tum-mcp.md", "docs/credential-storage-options.md"],
9
+ "files": ["npm/tum-mcp.mjs", "npm/runtime.mjs", "npm/download.mjs", "npm/uv-artifacts.json", "npm/backend/*.whl", "npm/backend/requirements.txt", "npm/backend/manifest.json", "LICENSE", "NOTICE", "README.md", "docs/setup.md", "docs/development.md", "docs/tum-mcp.md"],
10
10
  "scripts": {"prepack": "node npm/build.mjs", "test": "node --test npm/test/*.test.mjs", "test:consumer": "node npm/smoke-consumer.mjs"},
11
11
  "publishConfig": {"access": "public"},
12
- "repository": {"type": "git", "url": "git+https://github.com/jamestesting0/tum-moodle-integration.git"},
13
- "homepage": "https://github.com/jamestesting0/tum-moodle-integration#readme",
14
- "bugs": {"url": "https://github.com/jamestesting0/tum-moodle-integration/issues"},
12
+ "repository": {"type": "git", "url": "git+https://github.com/jamestesting0/tum-mcp.git"},
13
+ "homepage": "https://github.com/jamestesting0/tum-mcp#readme",
14
+ "bugs": {"url": "https://github.com/jamestesting0/tum-mcp/issues"},
15
15
  "keywords": ["mcp", "tum", "moodle", "artemis", "zulip", "codex"]
16
16
  }
package/docs/credential-storage-options.md DELETED
@@ -1,86 +0,0 @@
1
- # Credential storage and setup experience
2
-
3
- Checked against project code and primary upstream documentation on 24 October 2026.
4
-
5
- ## What other projects do
6
-
7
- | Project | Protected default | File alternative and trade-off |
8
- | --- | --- | --- |
9
- | [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/credstores.md) | macOS Keychain and Windows Credential Manager; configurable Linux stores | Supports Windows DPAPI-protected files. Also offers explicitly insecure plaintext files and an ephemeral cache. |
10
- | [Docker](https://docs.docker.com/reference/cli/docker/login/#credential-stores) | Native credential helpers; Docker Desktop configures one | Without a helper it stores base64-encoded credentials in configuration. Docker describes that as less secure. |
11
- | [GitHub CLI](https://cli.github.com/manual/gh_auth_login) | System credential store | Supports `--insecure-storage` and documents a plain-file fallback when secure storage fails. [Its implementation](https://github.com/cli/cli/blob/trunk/internal/config/config.go#L496-L512) explicitly tracks whether insecure storage was used. |
12
- | [Electron](https://www.electronjs.org/docs/latest/api/safe-storage) | macOS Keychain; Windows DPAPI; Linux desktop secret stores | macOS can still prompt. Its documentation recommends consistent code signing to prevent repeated approval after updates. Linux fallback backends need careful inspection because protection can be weaker. |
13
-
14
- Saving a key elsewhere is technically possible, but location alone does not
15
- protect it. A readable key file next to encrypted sessions lets a process that
16
- can copy both decrypt the sessions. Restrictive file permissions help against
17
- other OS users; they do not provide a separate secret-store boundary against
18
- code running as the same user. This is why the protected defaults above still
19
- use operating-system services.
20
-
21
- ## Current TUM MCP implementation
22
-
23
- | Platform | Implemented storage | Verification and expected setup |
24
- | --- | --- | --- |
25
- | macOS | Native Keychain item holds the encryption key; service cookies remain in encrypted files | Real saved sessions and scoped reads passed from the managed runtime after the user approved access. OS prompts remain possible for locked items, changed application identity, or temporary approval. |
26
- | Windows | Windows Credential Locker through Python keyring | Implementation and CI configuration exist. Hands-on Windows verification is still pending; no claim of universally prompt-free operation is made. |
27
- | Linux | Freedesktop Secret Service through Python keyring | ARM64 and x86_64 container bootstrap passed. On x86_64, an encrypted credential round trip across separate processes passed through real GNOME Secret Service in an isolated D-Bus session. Real desktop browser sign-in remains open. A usable, unlocked service and D-Bus session are required. |
28
-
29
- The backend selection is in `tum_moodle.auth.system_keyring`; encryption and
30
- account binding are in `tum_mcp.credentials.Vault`. There is no automatic
31
- plaintext fallback. The data-encryption key's service name and storage location
32
- are stable across backend-wheel updates.
33
-
34
- Windows can also protect a file directly with per-user
35
- [DPAPI](https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata).
36
- That avoids an adjacent unprotected key file. It is a reasonable optional backend
37
- if Credential Manager proves unsuitable, but it is not implemented in this build.
38
- It does not remove the need for a usable Windows user/logon context.
39
-
40
- ## Why this setup prompted repeatedly
41
-
42
- The initial account connection ran under development Python. The installed
43
- package then used managed Python to access the same existing Keychain item.
44
- Those were different requesting executables. Python keyring documents that
45
- access is associated with the
46
- [Python executable](https://keyring.readthedocs.io/en/stable/#security-considerations).
47
- Temporary **Allow** and persistent **Always Allow** are also different choices.
48
-
49
- The fresh-install path was tested separately with a disposable native Keychain
50
- item: managed Python created it, then a second process of that same runtime read
51
- it successfully in about one second without another user interaction. The item
52
- was deleted afterward. This supports using the installed runtime from the first
53
- login; it does not guarantee every Mac policy will suppress all prompts.
54
-
55
- A subsequent real MCP check passed through the installed Codex plugin, its Node
56
- launcher, and managed Python: both provider identities verified, the selected
57
- Zulip channel was readable, and an unselected channel was denied. No remote
58
- submission or message write was performed.
59
-
60
- ## Recommended direction
61
-
62
- 1. Keep native protected storage as the default and use the installed `tum-mcp`
63
- command for both onboarding and normal use.
64
- 2. Add a foreground storage-access check before opening browser login, so any
65
- necessary OS approval happens during setup rather than a later tool call.
66
- This is a proposed UX improvement, not a shipped behavior change here.
67
- 3. If future macOS interpreter updates keep changing identity, use a dedicated,
68
- consistently signed credential helper. That needs separate packaging/signing
69
- work and cannot guarantee that first-time OS approval never appears.
70
- 4. Consider explicit DPAPI-file or session-only modes for their appropriate
71
- platforms/use cases. Plain-file storage should require an informed choice;
72
- session-only storage requires signing in again after the broker stops.
73
-
74
- These recommendations change neither the existing stored credentials nor their
75
- permissions. Keychain approval is scoped to Python's access to this item; scripts
76
- using the same trusted executable can also request it. A restricted MCP API is
77
- not a system-wide sandbox for an otherwise unrestricted coding agent.
78
-
79
- ## Separate desktop-app permission
80
-
81
- The macOS prompt naming **ChatGPT** and asking to access data from other apps is
82
- separate from a Keychain request for `tum-mcp`. Apple associates that prompt with
83
- [files in other apps' sandbox containers](https://developer.apple.com/documentation/BundleResources/Information-Property-List/NSAppDataUsageDescription).
84
- The campus backend's default storage and HTTP read paths do not need that broad
85
- host permission. The specific container behind the observed prompt was not
86
- identified; computer-use inventory is a possible trigger, not a confirmed cause.