FIT Wiki MCP

Osobní MCP server pro studentskou, neoficiální FIT Wiki. Umí katalog předmětů, strom studijních stránek včetně státnic, navigaci podle sekcí, čtení stránek v Markdownu, diskuse pod stránkami, fulltext, stahování příloh, lokální OCR a předání obrázků modelu klienta pro rukopis a matematiku. Wiki nikdy neupravuje.

Instalace

Ověřeno na Linuxu a Pythonu 3.14; balíček vyžaduje Python 3.11+. Z kořene projektu:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps -e .

Pro čtení PDF, renderování a lokální OCR potřebuješ Poppler a Tesseract s jazykovými daty. Na Ubuntu/Debianu:

sudo apt-get install poppler-utils tesseract-ocr tesseract-ocr-ces tesseract-ocr-eng

Navigace, stránky a hledání fungují i bez systémových OCR nástrojů. Chybějící nástroj vrátí konkrétní DEPENDENCY_MISSING.

Related MCP server: canvas-mcp-server

Přihlášení a spuštění

Do soukromého .env vlož údaje účtu FIT Wiki:

FITWIKI_USERNAME=tvuj_wiki_ucet
FITWIKI_PASSWORD=tvuj_wiki_password

Podporované jsou i existující aliasy COURSES_USERNAME a COURSES_PASSWORD. Jde o formulářový login na wiki, nikoliv o OAuth portálu courses. Explicitní proměnné procesu mají přednost před .env; v rámci stejného zdroje mají názvy FITWIKI_* přednost před aliasy. Cookies zůstávají pouze v paměti.

.venv/bin/python mcp_server.py --doctor
.venv/bin/python mcp_server.py

Druhý příkaz spustí stdio server a čeká na MCP zprávy. Logy chodí na stderr. Launcher najde .env podle umístění projektu i při jiném pracovním adresáři. U instalovaného fitwiki-mcp nastav FITWIKI_ENV_FILE na absolutní cestu, pokud není .env v pracovním adresáři.

Klienti

Návody a výsledky ověření pro Codex, Claude Code, OpenCode v2, pi a Google Antigravity jsou v docs/CLIENTS.md. Konkrétní fragment s absolutními cestami vygeneruješ takto:

.venv/bin/python scripts/client_config.py codex
.venv/bin/python scripts/client_config.py claude
.venv/bin/python scripts/client_config.py opencode
.venv/bin/python scripts/client_config.py pi
.venv/bin/python scripts/client_config.py antigravity

Generátor jen vypíše konfiguraci; fragment sluč se stávající konfigurací klienta. Hesla se do klientských konfigurací nekopírují.

Nástroje a workflow

Začni list_courses(query="BI-DBS"), použij vrácené course_id v get_course_index, vyber sekci a načti stránku či přílohu z vráceného odkazu. Identifikátory předávej přesně, například škola:předměty:bi-dbs; neodvozuj URL jen ze zkratky.

Seznamy vracejí next_cursor, dlouhý text rovněž. Kurzor je vázaný na dotaz, obsah a proces serveru; po restartu či změně obsahu začni znovu bez něj. read_attachment používá čísla stran od 1 a vrací next_page. mode je auto, native nebo local_ocr.

Fulltext přijímá běžná slova a uvozované fráze, nikoliv operátory pro změnu namespace. Vlastní index předmětu se prohledává zvlášť, protože jej wiki namespace filtr nezahrnuje. Výsledek rozlišuje wiki_fulltext, course_index a local_transcription. Pole metadata.partial upozorňuje, že OCR index pokrývá jen již zpracované materiály a úplnost cizího wiki indexu nelze zaručit.

Strom stránek mimo katalog předmětů

get_namespace_index(namespace="škola") vrací přímé podnamespaces a stránky. U položky kind="namespace" použij namespace_id v dalším volání stejného nástroje, u kind="page" použij page_id v get_page nebo get_comments. Například namespace="škola:státnice" zpřístupní státnicové archivy nezávisle na katalogu předmětů. namespace="škola:předměty:bi-pst" projde index stránek PST i tam, kde na ně jeho přehled neodkazuje.

Výsledek obsahuje jen přímé potomky viditelné účtu, podporuje kurzor/refresh a nespouští rekurzivní crawl. Prázdný výsledek vrací namespace_exists=null, protože neprokazuje existenci namespace ani absenci skrytých stránek. HTTP operace používá ověřený čtecí POST call=index; samotný GET do AJAX endpointu vrací nesprávně kořen stromu.

Externí odkazy, které wiki zabalila jako fetch.php?media=https…, se vracejí jako odkazy na skutečný externí cíl i v Markdownu. Nejsou vydávány za interní přílohy a server je nestahuje s wiki přihlašovacími údaji.

Komentáře a obrázky v diskusi

Diskuse se čte samostatně přes get_comments, protože export používaný pro get_page ji neobsahuje. Například:

{
  "page_id": "škola:předměty:bi-pst:pst_test_2023-10-11_novak-11-00"
}

Autor se filtruje podřetězcem bez ohledu na velikost písmen a diakritiku. comment_id vybere konkrétní komentář. Výsledek obsahuje comment_id, parent_id odpovědi, author, published_at, Markdown a přímý odkaz na komentář. Neuvedený autor nebo čas jsou null. Do textu se zahrne i rozbalovací obsah, ovládání formulářů a přepínače se odstraní.

Přílohy jsou v attachments s hotovým attachment_id pro read_attachment nebo get_material_image; samotný seznam komentářů jejich obrazový obsah nepřepisuje. Odkaz komentáře na médium se zaznamená pro předmětové hledání získaných přepisů.

limit omezuje počet vrácených částí (1–20, výchozí 10), max_chars délku jedné části (100–10 000, výchozí 5000). Dlouhý komentář má opakované ID a pole part/parts; přes next_cursor lze získat celý text. total je počet komentářů po filtrování, page_total počet všech komentářů stránky a total_parts počet částí po rozdělení. Filtr autora nezahrne automaticky odpovědi jiných autorů; jejich vazby zůstávají v parent_id.

discussion_available=false odlišuje stránku bez dostupné diskuse od dostupné prázdné diskuse. Nerozpoznané nebo poškozené rozložení vrátí PARSE_ERROR místo tichého vynechání příspěvků. Cache diskuse platí nejvýše 5 minut, refresh=true vynutí nové čtení. Wiki fulltext nepovažuj za úplné hledání v komentářích; k jejich čtení slouží tento nástroj. Publikování komentářů není součástí API.

OCR a model s viděním

1. read_attachment nejdřív využije text PDF. U skenu/obrázku použije lokální Tesseract ces+eng; smíšená PDF označí varováním o rastrovém obsahu.

2. Pro rukopis, vzorce, diagramy nebo nejistý výsledek zavolej get_material_image. Vrací obrazový blok, ne pouze cestu či base64 v textu.

3. Model připojeného klienta přepíše obraz do Markdown/LaTeXu, označí nečitelné části a uloží přepis přes save_transcription s vráceným source_hash.

4. U výřezu nastav partial=true. Částečný přepis nepřepíše celostránkový záznam. Přepisy jsou vždy verified=false a originál zůstane dostupný.

region je [left, top, right, bottom] v rozsahu 0..1. Obraz pro klienta má nejvýše 2000 px na delší straně; pro drobné písmo použij výřez. Lokální render/OCR běží po jedné straně a s omezeným časem, velikostí a souběžností. Nečitelný sken může vrátit status=needs_vision místo vymyšleného textu.

Server nevolá samostatné OCR API. Model klienta však může běžet u vzdáleného poskytovatele; tato cesta proto není zárukou lokálního zpracování. Bez modelu s viděním je k dispozici lokální OCR a originál, kvalita rukopisu/matematiky tím není garantovaná. Rozhodnutí a kompromisy.

Data, cache a limity

Výchozí úložiště je ~/.cache/fitwiki-mcp/<account-hash>/, mimo repozitář. Adresáře mají oprávnění 0700, soubory 0600; zvolené existující úložiště musí být soukromé. Účet, reprezentace, původní obsah a verze parseru/OCR konfigurace oddělují záznamy. Vazba na přečtené stránky umožňuje předmětové hledání i v přílohách uložených ve společném namespace. Server odmítá cizí URL, jiné wiki akce, nebezpečné lokální cesty a symlinky. Externí odkazy vrací jako odkazy.

Výchozí TTL: katalog/index 24 h, stránky a originály příloh 1 h, hledání 5 min. refresh=true vynutí obnovu tam, kde jej nástroj nabízí. Při síťovém výpadku může vrátit označenou starší kopii; při zamítnutí přístupu či selhání přihlášení se na cache neodvolává jako na úspěšné online čtení. Čerstvá cache se v rámci TTL nemusí znovu dotazovat na změny oprávnění.

Limity: 1 HTTP požadavek/s, HTML 5 MiB, příloha 50 MiB, seznam do 50 položek, textový blok do 30 000 znaků. Široké hledání wiki může stáhnout mnoho výsledků najednou; MCP stránkuje získaný seznam lokálně. Místní OCR index má limit 5000 záznamů a pokrývá pouze získané texty.

Volby prostředí a aliasy jsou v .env.example. FITWIKI_DATA_DIR nastaví soukromý datový adresář; FITWIKI_REQUEST_INTERVAL, FITWIKI_PAGE_TTL, FITWIKI_INDEX_TTL, FITWIKI_SEARCH_TTL a FITWIKI_OCR_LANGUAGES upraví chování. Server cookies neukládá a .env nepřepisuje.

Resources

fitwiki://courses, fitwiki://courses/{course_id}/index, fitwiki://pages/{page_id}, fitwiki://pages/{page_id}/comments a fitwiki://namespaces/{namespace_id} vracejí JSON ze stejné služby jako nástroje. Dvojtečky v identifikátoru lze zakódovat jako %3A. Pro stránkování použij nástroje; základní workflow nezávisí na podpoře resources klientem.

Ověření a řešení chyb

.venv/bin/ruff check src tests scripts mcp_server.py
.venv/bin/pytest -q
.venv/bin/python scripts/live_smoke.py --live
.venv/bin/python scripts/live_smoke.py --live --mode legacy

Běžné testy jsou offline a používají syntetické fixtures. Live test je explicitní a využije .env; vypisuje jen technická metadata. Skutečně provedené ověření a limity.

Chyby nástroje mají isError=true a JSON s error.code, message a retryable. AUTH_REQUIRED znamená chybějící údaje/session, AUTH_FAILED neúspěšný login, ACCESS_DENIED zamítnutý přístup, NOT_FOUND chybějící materiál. INVALID_CURSOR vyřeš novým požadavkem bez kurzoru; TOO_LARGE užším rozsahem; BUSY opakováním po skončení jiného renderu. PROCESS_TIMEOUT nebo nečitelný lokální OCR řeš menším rozsahem či vision cestou. Stav HTTP 200 server nepovažuje automaticky za úspěšné čtení.

Obsah wiki je neoficiální. U požadavků, klasifikace a aktuálních oznámení ověř oficiální courses portál. Licence a případné výjimky zůstávají vlastností originálních materiálů. Hromadný archiv, generování nových PDF, samostatná OCR služba a sdílené HTTP hostování jsou mimo tuto verzi.

Licence

Zdrojový kód a dokumentace projektu jsou dostupné pod licencí MIT, Copyright (c) 2026 kvelzer. Licence projektu se nevztahuje na obsah FIT Wiki ani stažené materiály; ty si zachovávají vlastní licence a podmínky.