@jamestesting888/tum-mcp 0.0.0-stage → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TUM Moodle integration contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,6 @@
+The project's original code and documentation are provided under the MIT License.
+
+The TUM logo at plugin/assets/tum-logo.png (assets/tum-logo.png in the packaged
+plugin) is excluded from the MIT License. It belongs to the Technical University
+of Munich and remains subject to its original rights. No trademark rights are
+granted by this project. See plugin/assets/README.md for the source of the image.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# TUM MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use TUM Moodle, Artemis, and Zulip from your coding agent. Runs locally with
+36 tools and seven workflow skills. Unofficial; independent of TUM and OpenAI.
+
+## Agent setup
+
+Paste this into your coding agent:
+
+```text
+Install @jamestesting888/tum-mcp@0.4.1 from npm on this computer.
+Check that Node.js is at least 22.14, then run:
+  npm install --global @jamestesting888/tum-mcp@0.4.1
+  tum-mcp setup --client codex
+For Claude Code, use --client claude instead; other MCP clients use --client generic.
+Preserve existing settings, plugins, sessions, downloads, and customized skills.
+Follow the printed enablement/restart step. Then help me run tum-mcp connect campus
+in an interactive terminal so I can complete TUM sign-in/MFA in Chrome.
+Ask which Artemis courses and Zulip channels to enable before reading content.
+For Moodle, use the plugin's separate Moodle sign-in. Never request secrets in chat.
+```
+
+## Manual setup
+
+You need **Node.js 22.14+**, **Google Chrome**, and your TUM account.
+
+```sh
+npm install --global @jamestesting888/tum-mcp@0.4.1
+tum-mcp setup --client codex
+tum-mcp connect campus
+```
+
+`campus` connects **Artemis and Zulip together**. Complete sign-in and MFA in
+Chrome; no Zulip API key is required. Moodle sign-in is separate: ask the loaded
+plugin, **“Sign in to TUM Moodle.”** Follow any client enablement/restart instruction.
+Disable the older Moodle plugin when enabling TUM MCP to avoid duplicate tools.
+
+Select the courses and channels the backend may read. `status` shows account IDs;
+`discover` lists metadata, and `scope` saves your choices. New accounts start
+without content access. See the [connection and scope commands](docs/tum-mcp.md#connections-and-scopes).
+
+Setup downloads a private Python runtime; consumers do not need Python or uv.
+Git is needed for assignment workspaces and Docker for isolated assignment tests.
+Linux also needs an unlocked Secret Service keyring in its desktop D-Bus session.
+
+## What you can do
+
+| Service | Available |
+| --- | --- |
+| Moodle | Read/search course materials and forums, cite PDF pages, download originals |
+| Artemis | Read released programming exercises and permitted feedback; prepare existing-participation workspaces, run approved local tests, preview submissions |
+| Zulip | Search selected channels, read topics, and summarize recent discussions with citations |
+
+Try “Find the lecture section about scheduling,” “Read this Artemis exercise,”
+or “Catch me up on the selected Zulip channel.” Personal records, participation
+feedback, and workspace writes require their own explicit permissions.
+
+**0.4.1 is a public pilot.** Remote start, push, submit, and rebuild are disabled.
+It cannot post to Zulip or read DMs. A submission preview never submits anything.
+macOS ARM64 browser sign-in and live reads are verified; Windows, Intel Mac, and
+Linux desktop checks remain incomplete. Bootstrap targets and test evidence are
+listed in the [detailed guide](docs/tum-mcp.md#build-and-test-the-local-package).
+
+## Privacy
+
+Sessions stay local and encrypted, with keys in macOS Keychain, Windows Credential
+Manager, or Linux Secret Service. There is no plaintext credential fallback.
+Relevant excerpts can be sent to your agent's configured AI provider. Zulip chat
+text is fetched live; Moodle's document cache is unencrypted and limited to
+30 days / 1 GiB. Downloads remain until deleted.
+
+Use the installed `tum-mcp` command for sign-in to keep the requesting runtime
+consistent. Your OS may ask for credential-store access. See
+[storage details](docs/credential-storage-options.md).
+
+## Update and support
+
+Install the reviewed version you want, then rerun the client setup:
+
+```sh
+npm install --global @jamestesting888/tum-mcp@latest
+tum-mcp setup --client codex
+```
+
+Existing Moodle sessions and downloads are preserved. Customized configurations
+are kept for review. `tum-mcp doctor` checks local prerequisites; it does not
+verify live authentication.
+
+[Detailed guide](docs/tum-mcp.md) · [Moodle-only setup](docs/setup.md) ·
+[Development](docs/development.md) · [Report a problem](https://github.com/jamestesting0/tum-moodle-integration/issues)
+
+## License
+
+[MIT](LICENSE). The TUM logo retains its original rights; see [NOTICE](NOTICE).
+No trademark rights are granted.

package/docs/credential-storage-options.md

@@ -0,0 +1,86 @@
+# Credential storage and setup experience
+
+Checked against project code and primary upstream documentation on 24 October 2026.
+
+## What other projects do
+
+| Project | Protected default | File alternative and trade-off |
+| --- | --- | --- |
+| [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. |
+| [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. |
+| [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. |
+| [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. |
+
+Saving a key elsewhere is technically possible, but location alone does not
+protect it. A readable key file next to encrypted sessions lets a process that
+can copy both decrypt the sessions. Restrictive file permissions help against
+other OS users; they do not provide a separate secret-store boundary against
+code running as the same user. This is why the protected defaults above still
+use operating-system services.
+
+## Current TUM MCP implementation
+
+| Platform | Implemented storage | Verification and expected setup |
+| --- | --- | --- |
+| 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. |
+| 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. |
+| 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. |
+
+The backend selection is in `tum_moodle.auth.system_keyring`; encryption and
+account binding are in `tum_mcp.credentials.Vault`. There is no automatic
+plaintext fallback. The data-encryption key's service name and storage location
+are stable across backend-wheel updates.
+
+Windows can also protect a file directly with per-user
+[DPAPI](https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata).
+That avoids an adjacent unprotected key file. It is a reasonable optional backend
+if Credential Manager proves unsuitable, but it is not implemented in this build.
+It does not remove the need for a usable Windows user/logon context.
+
+## Why this setup prompted repeatedly
+
+The initial account connection ran under development Python. The installed
+package then used managed Python to access the same existing Keychain item.
+Those were different requesting executables. Python keyring documents that
+access is associated with the
+[Python executable](https://keyring.readthedocs.io/en/stable/#security-considerations).
+Temporary **Allow** and persistent **Always Allow** are also different choices.
+
+The fresh-install path was tested separately with a disposable native Keychain
+item: managed Python created it, then a second process of that same runtime read
+it successfully in about one second without another user interaction. The item
+was deleted afterward. This supports using the installed runtime from the first
+login; it does not guarantee every Mac policy will suppress all prompts.
+
+A subsequent real MCP check passed through the installed Codex plugin, its Node
+launcher, and managed Python: both provider identities verified, the selected
+Zulip channel was readable, and an unselected channel was denied. No remote
+submission or message write was performed.
+
+## Recommended direction
+
+1. Keep native protected storage as the default and use the installed `tum-mcp`
+   command for both onboarding and normal use.
+2. Add a foreground storage-access check before opening browser login, so any
+   necessary OS approval happens during setup rather than a later tool call.
+   This is a proposed UX improvement, not a shipped behavior change here.
+3. If future macOS interpreter updates keep changing identity, use a dedicated,
+   consistently signed credential helper. That needs separate packaging/signing
+   work and cannot guarantee that first-time OS approval never appears.
+4. Consider explicit DPAPI-file or session-only modes for their appropriate
+   platforms/use cases. Plain-file storage should require an informed choice;
+   session-only storage requires signing in again after the broker stops.
+
+These recommendations change neither the existing stored credentials nor their
+permissions. Keychain approval is scoped to Python's access to this item; scripts
+using the same trusted executable can also request it. A restricted MCP API is
+not a system-wide sandbox for an otherwise unrestricted coding agent.
+
+## Separate desktop-app permission
+
+The macOS prompt naming **ChatGPT** and asking to access data from other apps is
+separate from a Keychain request for `tum-mcp`. Apple associates that prompt with
+[files in other apps' sandbox containers](https://developer.apple.com/documentation/BundleResources/Information-Property-List/NSAppDataUsageDescription).
+The campus backend's default storage and HTTP read paths do not need that broad
+host permission. The specific container behind the observed prompt was not
+identified; computer-use inventory is a possible trigger, not a confirmed cause.

package/docs/development.md

@@ -0,0 +1,96 @@
+# Development
+
+[README](../README.md) · [Setup](setup.md)
+
+For the combined 0.4.1 campus pilot, see the [TUM MCP guide](tum-mcp.md) and
+[current verification limits](tum-mcp.md#build-and-test-the-local-package). This page also
+covers the preserved Moodle-only installer.
+
+## Checks
+
+```sh
+uv sync --locked
+uv run ruff check src tests plugin/scripts scripts
+uv run ruff format --check src tests plugin/scripts scripts
+uv run pytest -q
+uv run python scripts/package_plugin.py
+uv build
+node npm/build.mjs
+npm test
+npm pack --ignore-scripts --pack-destination dist
+npm run test:consumer -- dist/jamestesting888-tum-mcp-0.4.1.tgz
+```
+
+Python 3.13 is the managed runtime on every platform. Install Tesseract for the
+OCR integration test. Ordinary tests use synthetic materials and in-memory
+credentials; no Moodle login is needed. No language-server installation is required.
+
+GitHub Actions runs the suite on macOS, Windows, and Ubuntu, including packaged
+MCP startup, PDF/OCR extraction, downloads, and real native credential-store
+round trips. The Linux job starts its own D-Bus/Secret Service session.
+The campus additions configure fresh npm consumer checks on all three runners;
+those checks must pass for the release commit before claiming release coverage.
+
+To test an installed package, set `TUM_MOODLE_PACKAGED` to its
+`scripts/launch.py` path before running pytest. Set `TUM_MOODLE_SYSTEM_KEYRING=1`
+to enable the native-store test; it creates and removes a unique synthetic entry.
+
+Live Moodle checks are separate: `TUM_MOODLE_LIVE=1 uv run pytest tests/live -q`.
+They require the developer's saved session and Real Time Systems enrollment;
+one test downloads a lecture. Never supply personal credentials to public CI.
+
+## Architecture
+
+| Module | Responsibility |
+| --- | --- |
+| `platforms.py` | Shared OS data/runtime paths; also imported by bootstrap and launcher |
+| `auth.py`, `login.py` | Encrypted sessions, native credential stores, Chrome sign-in |
+| `server.py`, `service.py` | MCP tools and retrieval coordination |
+| `http_client.py` | Read-only Moodle network boundary |
+| `parsing.py`, `forums.py`, `personal_records.py` | Moodle content and explicit private-record reads |
+| `extraction.py`, `extract_worker.py` | Document/OCR extraction with process limits |
+| `library.py`, `downloads.py` | Local search/cache and persistent exports |
+
+The stdlib-only `scripts/install.py` owns packaging, runtime checks, activation,
+and structured handoff. The updater pulls safely, then delegates to that installer.
+Packaged `scripts/runtime_setup.py` is shared with bootstrap; its content receipt
+and offline dependency check permit healthy reruns without synchronization.
+Source changes force a package refresh even if the version/metadata timestamp
+is unchanged. `--repair` reinstalls the locked runtime. The MCP smoke check lists
+tools without reading a Moodle session or making Moodle requests.
+
+Generated manifests launch the absolute private Python path on every OS.
+Portable source templates contain no machine paths. Rebuild on each target
+computer; moving/deleting the checkout does not affect the installed runtime.
+
+CI enables `TUM_MOODLE_INSTALLER_INTEGRATION=1` for a real isolated-cache install,
+offline rerun, same-version source update, damaged-runtime detection, and repair.
+Set `TUM_MOODLE_INSTALLER_EVIDENCE` to write stage timings. The external Codex CLI
+is synthetic in those tests; dependency installation and MCP startup are real.
+Timings exclude agent latency, user sign-in/MFA, and application restart time.
+
+Credentials use explicit OS backends. Unsupported or unavailable stores fail
+with `SETUP_REQUIRED`; environment-selected plaintext alternatives are ignored.
+Keep the existing macOS service name and account path to preserve saved sessions.
+
+Extraction runs in a subprocess with a 60-second wall limit and 512 MiB aggregate
+memory monitoring. POSIX also enforces a CPU limit and kills the process group;
+Windows terminates the worker and its observed child processes.
+
+## Manual desktop verification
+
+Automated tests do not replace a desktop check. On each target OS, verify:
+
+1. Register/install from a checkout with spaces in its path; restart the client.
+2. Confirm native tools appear, then complete Chrome sign-in and MFA.
+3. List current-semester courses, read a PDF, and check a forum.
+4. Download one material and open the returned file locally.
+5. Restart the client and confirm session reuse, then test logout and sign-in.
+
+macOS has had a live course/sign-in test. Windows and Linux still require this
+interactive check before claiming equivalent desktop verification.
+
+Keep changes focused. Never commit session files, course materials, databases,
+or `.env` files. The cache/search database is local and unencrypted; private
+records are excluded from ordinary search. External recording links receive
+no Moodle cookies.

package/docs/setup.md

@@ -0,0 +1,177 @@
+# Desktop setup
+
+This page covers the preserved **Moodle-only** installer. For the combined
+Artemis/Zulip/Moodle 0.4.1 pilot, use [campus setup](../README.md#manual-setup) and
+the [TUM MCP guide](tum-mcp.md).
+
+[README](../README.md) · [macOS](#macos) · [Windows](#windows) · [Linux](#linux) ·
+[Updates](#updates) · [Troubleshooting](#troubleshooting) · [Uninstall](#uninstall)
+
+## Prerequisites
+
+Use your own TUM account and a Codex client that supports local plugin marketplaces.
+This package runs on the local computer; it does not connect ChatGPT web.
+
+### macOS
+
+Install Git, [uv](https://docs.astral.sh/uv/getting-started/installation/), and
+[Google Chrome](https://www.google.com/chrome/). Homebrew users can run:
+
+```sh
+brew install git uv
+brew install --cask google-chrome
+```
+
+Git can also come from Apple's Command Line Tools: `xcode-select --install`.
+No system Python is needed. For scanned PDFs, optionally install `brew install tesseract`.
+Unlock your login keychain if macOS asks. Apple Silicon has been tested locally;
+Intel uses the same setup, but has not had a hands-on test.
+
+### Windows
+
+Use a normal, non-administrator PowerShell window. Install prerequisites if missing:
+
+```powershell
+winget install --exact --id Git.Git
+winget install --exact --id astral-sh.uv
+winget install --exact --id Google.Chrome
+```
+
+Open a **new PowerShell window** after installation so PATH is refreshed.
+uv supplies Python; a separate Python installation is not required. Ensure
+`uv --version` works before running the installer. Codex then launches the private
+interpreter directly, so it does not depend on PowerShell's PATH.
+
+Windows Credential Manager stores the session-encryption key. Optional OCR needs
+[Tesseract](https://tesseract-ocr.github.io/tessdoc/Installation.html), with its
+installation directory on PATH. Restart Codex after changing PATH.
+
+### Linux
+
+Use a graphical desktop session with Google Chrome, Git, uv, and an
+unlocked **Secret Service** keyring, such as GNOME Keyring. The keyring must be
+available in the same D-Bus session as Codex. A headless SSH session is insufficient
+for interactive Moodle sign-in.
+
+For Ubuntu/Debian prerequisites:
+
+```sh
+sudo apt-get install git gnome-keyring
+```
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and
+[Chrome](https://www.google.com/chrome/) using their official installers.
+For OCR, optionally install `sudo apt-get install tesseract-ocr`.
+On other distributions, use the equivalent packages. KWallet-only setups need
+a running Secret Service provider; the plugin deliberately avoids plaintext
+or arbitrary third-party credential backends.
+
+## Install and sign in
+
+Run these commands on the target computer so packaging generates the correct launcher:
+
+```sh
+git clone --depth 1 https://github.com/jamestesting0/tum-moodle-integration.git
+cd tum-moodle-integration
+uv run scripts/install.py
+```
+
+Do not copy a Mac's generated plugin or session files to Windows/Linux.
+
+The installer preserves existing marketplace entries and registers the source
+under `~/.codex/plugins/local/tum-moodle/`. In PowerShell, `~` refers to your user
+profile. You can also install through the Codex CLI:
+
+```text
+codex plugin add tum-moodle@personal-local
+```
+
+If you renamed your personal source, use its marketplace name instead.
+When the installer requests it, restart the desktop app completely: **Cmd+Q** on macOS;
+exit all app windows/background instances on Windows/Linux, then reopen it.
+
+After installation, ask **“Sign in to TUM Moodle.”** The agent checks the existing
+session before opening Chrome. Complete any TUM login/MFA there. Once connected,
+the agent offers an optional course-list check; declining it leaves setup complete.
+
+### Installer results and repair
+
+`uv run scripts/install.py --json` returns one structured result. Progress goes to
+stderr; `next_actions` tells the agent exactly what remains.
+
+| Result | Meaning |
+| --- | --- |
+| `ready` | Local checks pass and the installed plugin is current. Sign-in is separate. |
+| `restart_required` | Software setup passed; fully restart Codex once to load it. |
+| `action_required` | Follow the prerequisite, keyring, or manual enablement instruction. Completed software stages are retained. |
+| `error` | A stage failed; the result includes the failed stage and error. |
+
+Exit codes are 0 for software success, 2 for a required user action, and 1 for an
+error. A local MCP check does not prove tools have reloaded in the current chat.
+Do not keep restarting or reinstalling while waiting for the user.
+
+If the runtime is damaged, run `uv run scripts/install.py --repair`. This reinstalls
+locked runtime packages without removing sessions or downloads. Healthy reruns
+check the existing runtime and reuse uv's cache. Native tools can work after the
+original checkout is moved/deleted; keep a checkout for future updates.
+
+## Updates
+
+Run `uv run scripts/update.py` from your checkout and follow the printed actions.
+It uses your branch's configured upstream and a fast-forward-only pull; it never
+stashes edits, switches branches, or creates a merge commit.
+
+The shared installer refreshes TUM Moodle using the Codex CLI on PATH or in a standard
+macOS app bundle. If it cannot find the CLI, it updates the code/runtime and tells
+you to reinstall the plugin from your personal source in the Plugins screen.
+Custom marketplace names are preserved. A failed step stops the update and
+reports the error; fix that issue and rerun the command.
+
+For a checkout created before the updater was added, first run `git pull --ff-only`.
+
+## Troubleshooting
+
+| Problem | Fix |
+| --- | --- |
+| No personal plugin source | Repeat packaging with `--register`, then fully restart Codex. Check that your client supports local marketplaces. |
+| Skills appear but tools do not | Repeat bootstrap, reinstall the plugin from your personal source, and restart Codex. Check loader errors before repeating restarts. |
+| `uv` is missing | Install uv and open a new terminal/app session. Bootstrap also checks `~/.local/bin` and standard Homebrew locations. |
+| Windows opens Microsoft Store for Python | Rerun the installer. The generated manifest must point to the private runtime's `Scripts/python.exe`. |
+| Native credential store unavailable | Unlock the OS store. Linux needs Secret Service in the current desktop D-Bus session; there is no plaintext fallback. |
+| Chrome fails to open | Install Google Chrome, then ask the plugin to sign in again. Chromium-only installations are not selected automatically. |
+| Session expired | Ask Codex to sign in to Moodle again. |
+| Scanned material fails | Install Tesseract and put it on PATH, then restart Codex and retry. Text PDFs do not require OCR. |
+| Search returns little | Ask Codex to index/refresh the course and check coverage. |
+
+Downloaded originals are in `~/Downloads/TUM Moodle/`. To use a different folder,
+set `TUM_MOODLE_DOWNLOAD_DIR` in the environment inherited by Codex.
+`TUM_MOODLE_DATA_DIR` overrides the session/cache location. The installed runtime
+stays in the standard platform data folder.
+
+For [bug reports](https://github.com/jamestesting0/tum-moodle-integration/issues),
+include OS/client versions and the error message. Remove credentials, cookies,
+personal records, and course content.
+
+## Data locations
+
+| Platform | Moodle runtime, session, and cache |
+| --- | --- |
+| macOS | `~/Library/Application Support/TUMMoodle/` |
+| Windows | `%LOCALAPPDATA%\TUMMoodle\` |
+| Linux | `${XDG_DATA_HOME:-~/.local/share}/TUMMoodle/` |
+
+Campus settings and encrypted credentials use a separate `TUMMCP/` folder beside
+`TUMMoodle/`. Existing Moodle data remains in place when switching to TUM MCP.
+
+## Uninstall
+
+1. Ask Codex to sign out and clear the cache, then remove the plugin in Plugins.
+2. To remove the personal catalog entry, delete only `tum-moodle` from
+   `~/.agents/plugins/marketplace.json`, preserving the other entries.
+3. Delete `~/.codex/plugins/local/tum-moodle/` and the
+   [platform data folder](#data-locations) if no longer needed.
+4. Remove the `tum-moodle-integration` credential entry using the OS credential
+   manager: Keychain Access, Windows Credential Manager, or the Linux password/keyring app.
+
+Delete downloaded files separately if desired. Signing out removes this plugin's
+saved session; it does not sign you out of other browsers or revoke TUM sessions.