# IS MUNI MCP

[![CI](https://github.com/Destingem/is-muni-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Destingem/is-muni-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/is-muni-mcp.svg)](https://pypi.org/project/is-muni-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

MCP server pro studenty Masarykovy univerzity — propojí AI agenty
(Claude Desktop, Codex, ChatGPT desktop, Claude Code, VS Code, Cursor, …)
s Informačním systémem MU, aby pomohli s plánováním studia: rozvrh,
deadliny, e-maily, známky, body z bloků, studijní materiály a další.

> **Nikdy nic nemění.** Server pouze čte data (GET + POST jen na povolené
> čtecí endpointy, typicky AJAX vyhledávání) — neumí odesílat poštu,
> registrovat předměty, přihlašovat na zkoušky ani jinak cokoliv v IS měnit.
> Garance je přímo v kódu: klient
> [`client.py`](src/is_muni_mcp/client.py) nemá metody pro PUT/PATCH/DELETE
> a POST mimo allowlist odmítne (hlídá to i test `test_read_only_client`).

*English summary: read-only MCP server for Masaryk University students —
connects AI agents to IS MUNI (timetable, deadlines, mail, grades, course
materials). Quickstart below is in Czech; commands are the same in any
language. See [CONTRIBUTING](CONTRIBUTING.md) and [SECURITY](SECURITY.md).*

## Instalace na 1 klik (bez terminálu) 🖱️

Vyberte si svého AI klienta — terminál není potřeba ani v jednom případě:

| Klient | Jak na to |
|---|---|
| **Claude Desktop** | Stáhněte **`is-muni-mcp.mcpb`** z [Releases](https://github.com/Destingem/is-muni-mcp/releases), dvojklik, vyplňte učo + heslo. Hotovo. |
| **Codex, ChatGPT desktop, Claude Code, VS Code, Cursor** | Stáhněte **Setup aplikaci** pro svůj systém z [Releases](https://github.com/Destingem/is-muni-mcp/releases), dvojklik — otevře se průvodce v prohlížeči, kde vyplníte učo + heslo a zaškrtáte klienty. Hotovo. (ChatGPT desktop čte stejnou konfiguraci jako Codex — stačí ho po instalaci restartovat.) |

Soubory v Releasu:

- `IS-MUNI-Setup-macos-arm64.zip` — macOS (Apple Silicon; rozbalit, otevřít `IS MUNI Setup.app`)
- `IS-MUNI-Setup-windows-x64.exe` — Windows (stáhnout, dvojklik)
- `is-muni-mcp-linux-x64` — Linux (stáhnout, spustit `./is-muni-mcp wizard`)
- `is-muni-mcp.mcpb` — Claude Desktop (dvojklik)

> ⚠️ Aplikace není placeně podepsaná (to stojí ~2500 Kč/rok), takže macOS
> při prvním otevření zahlásí neověřeného vývojáře: klikněte **pravým tlačítkem
> → Otevřít → Otevřít**. Na Windows SmartScreen podobně: **Další informace →
> Přesto spustit**. Kód je open-source — sestavení si můžete ověřit ve
> [workflow](.github/workflows/release.yml), nic si nestahuje z internetu.
>
> Heslo slouží jen k přihlášení a nikam se neukládá; server si drží pouze
> session. Detaily viz [SECURITY](SECURITY.md).

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3Fname%3Dis-muni%26config%3D%257B%2522type%2522%253A%2520%2522stdio%2522%252C%2520%2522command%2522%253A%2520%2522uvx%2522%252C%2520%2522args%2522%253A%2520%255B%2522is-muni-mcp%2522%255D%257D)
[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP-000000?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=is-muni&config=eyJ0eXBlIjogInN0ZGlvIiwgImNvbW1hbmQiOiAidXZ4IiwgImFyZ3MiOiBbImlzLW11bmktbWNwIl19)

*Tlačítka výše přidají server do VS Code / Cursoru jedním kliknutím
(vyžadují nainstalovaný `uvx` a předchozí `is-muni-mcp login` —
jednodušší je Setup aplikace, která umí obojí).*

Pak se ptejte třeba: *„Co mám příští týden v rozvrhu?“*,
*„Jaké se blíží deadliny?“*, *„Mám nějaké nepřečtené e-maily?“*,
*„Kolik mám bodů v poznámkových blocích?“*

## Rychlý start s terminálem (3 kroky)

Pro Claude Code, VS Code, Zed a další klienty. Potřebujete Python 3.10+
a své učo + primární heslo do IS MUNI.

**1. Instalace** (jednou z možností):

```bash
pipx install is-muni-mcp        # doporučeno pro běžné uživatele
# nebo: uv tool install is-muni-mcp
# nebo: pip install --user is-muni-mcp
```

**2. Přihlášení** — zeptá se na učo a heslo, heslo se nikam neukládá:

```bash
is-muni-mcp login
is-muni-mcp status   # ověření, že přihlášení funguje
```

Session se uloží do `~/.config/is-muni-mcp/cookie.txt` (práva 0600, jen pro vás).
Když časem vyprší (typicky dny až týdny), stačí `login` zopakovat.

**3. Napojení na AI klienta** — jedna z možností:

```bash
is-muni-mcp setup --client claude-desktop   # zapíše konfiguraci za vás
is-muni-mcp setup --client claude-code      # přes `claude mcp add`
is-muni-mcp setup --client codex            # ~/.codex/config.toml (Codex CLI, IDE extenze i ChatGPT desktop)
is-muni-mcp setup --client vscode           # uživatelské mcp.json
is-muni-mcp setup --client cursor           # ~/.cursor/mcp.json
# tip: grafický průvodce (i bez terminálových znalostí): is-muni-mcp wizard
```

Pak restartujte klienta a ptejte se třeba: *„Co mám příští týden v rozvrhu?“*,
*„Jaké se blíží deadliny?“*, *„Mám nějaké nepřečtené e-maily?“*,
*„Kolik mám bodů v poznámkových blocích?“*

## Nástroje (25)

| Oblast | Nástroje |
|---|---|
| Student | `status`, `profil`, `osoba`, `moje_predmety`, `predmet_info`, `moje_znamky`, `moje_seminarni_skupiny`, `hledat_predmet`, `harmonogram` |
| Kalendář a výuka | `kalendar`, `deadlines`, `rozvrh`, `zkouskove_terminy` (pouze přehled) |
| Pošta | `posta_slozky`, `posta_seznam`, `posta_cti` |
| Notifikace | `udalosti`, `pripomenuti` (IS připomíná), `dashboard` (Co se děje / Co vás čeká) |
| Bloky | `poznamkove_bloky` (body a hodnocení z průběžných aktivit) |
| Soubory | `soubory_vypis` (i rekurzivně), `soubor_cti` (text rovnou; u prezentací/dokumentů zkusí i automatickou .txt verzi) |
| Diskuse a vývěska | `diskuse_prehled`, `diskuse_vlakno`, `vyveska` |

## Ruční konfigurace klientů

Když nechcete použít `setup`, přidejte server ručně. Příkaz je vždy `is-muni-mcp`
(bez argumentů spustí server přes stdio; přihlášení si najde samo v
`~/.config/is-muni-mcp/cookie.txt`).

**Claude Desktop** — do `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "is-muni": {
      "command": "is-muni-mcp"
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add is-muni -- is-muni-mcp
```

**Codex a ChatGPT desktop** — do `~/.codex/config.toml` (CLI, IDE extenze
i ChatGPT desktop app sdílí tuto konfiguraci a spouští lokální stdio servery;
po zápisu stačí restartovat aplikaci, stav ukáže `/mcp`):

```toml
[mcp_servers.is-muni]
command = "is-muni-mcp"
startup_timeout_sec = 60
```

**Obecné `mcp.json`** (VS Code, Zed, …) — totéž co výše; konfiguraci pro svůj
stroj vytisknete příkazem `is-muni-mcp setup --client json`
(VS Code: `setup --client vscode --print-only`, Cursor: `... cursor ...`).

**ChatGPT desktop app** — umí lokální stdio servery přes sdílenou Codex
konfiguraci (viz **Codex** výše): stačí `is-muni-mcp setup --client codex`
nebo Setup aplikace a restart ChatGPT. Žádný vzdálený server není potřeba.

**ChatGPT web a další klienti bez lokálního stdio** — webové ChatGPT umí jen
vzdálené MCP servery (URL). Pro tento případ server umí i HTTP transport —
musíte ho ale provozovat sami (např. na vlastním VPS) a ChatGPT pak napojit
na jeho URL:

```bash
is-muni-mcp serve --transport streamable-http --host 127.0.0.1 --port 8000
# URL pro klienta: http://VAS-SERVER:8000/mcp
```

> ⚠️ HTTP režim vystavuje vaše data z IS komukoliv s přístupem k URL —
> provozujte ho jen za autentizací / na privátní síti (Tailscale, VPN)
> a nikdy ne bez zabezpečení na veřejném internetu.

**Docker:**

```bash
docker build -t is-muni-mcp .
docker run -i --rm -v is-muni-config:/config is-muni-mcp login   # přihlášení (session zůstane ve volume)
docker run -i --rm -v is-muni-config:/config is-muni-mcp         # server přes stdio
```

## Přihlášení — detaily a alternativy

- `is-muni-mcp login` — interaktivní přihlášení učem + heslem (doporučeno).
- `is-muni-mcp login --uco 990001` — učo předvyplněné, zeptá se jen na heslo.
- `is-muni-mcp login --cookie "__Host-issession=...; __Host-iscreds=..."` —
  nouzová varianta: vložení hotové session z prohlížeče
  (Vývojářské nástroje → Application → Cookies → `https://is.muni.cz`).
- `is-muni-mcp logout` — smaže uloženou session.
- Proměnné prostředí (přednost před uloženou session, vhodné pro servery
  a CI): `ISMU_COOKIE` (celý řetězec), `ISMU_SESSION` + `ISMU_CREDS`,
  `ISMU_COOKIE_FILE`, nebo `ISMU_UCO` + `ISMU_PASSWORD` (automatické
  přihlášení i obnova expirované session). Vzor viz [`.env.example`](.env.example).
- Stažené binární soubory: `ISMU_DOWNLOAD_DIR` (výchozí `~/.cache/is-muni-mcp`).

## Vývoj a testy

```bash
git clone https://github.com/Destingem/is-muni-mcp.git
cd is-muni-mcp
uv sync --group dev
uv run pytest            # fixture testy parserů + test MCP protokolu (offline)
uv run ruff check src tests mcpb packaging && uv run ruff format --check src tests mcpb packaging
ISMU_LIVE_MCP=1 uv run pytest tests/test_mcp.py -q   # + živé volání přes protokol (potřebuje přihlášení)
```

Testy běží nad redigovanými vzorky stránek IS
([`tests/fixtures/`](tests/fixtures/)) — žádný network, žádná reálná data.
Detaily viz [CONTRIBUTING](CONTRIBUTING.md).

## Jak to funguje a limity

- Data se čtou přímo ze stránek IS (HTML + vložený JSON kalendáře + oficiální
  iCal export rozvrhu `format=ical`). Žádné neoficiální API není potřeba.
- Struktura stránek IS se může změnit — když některý nástroj přestane fungovat,
  většinou stačí upravit příslušný parser v [`src/is_muni_mcp/parsers/`](src/is_muni_mcp/parsers/).
- Některé agendy IS (např. přepínače období) se doplňují JavaScriptem — server
  pracuje s aktuálně vybraným obdobím a studiem.
- Odpovědníky se čtou jen z kalendáře a výpisu souborů — nástroj záměrně neotvírá
  testovací rozhraní, aby omylem nezahájil pokus.
- Neoficiální projekt — není dílem ani pod záštitou Masarykovy univerzity.

## Licence

MIT — viz [LICENSE](LICENSE).