Bakaláři MCP Server

Bakaláři MCP Server

MCP (Model Context Protocol) server pro Bakaláři v3 API. Umožňuje přístup k Bakaláři školnímu systému přes standardizované MCP rozhraní.

Upozornění

!! K používání tohoto projektu je potřeba trošku umět s dockerem/pythonem a vědět, jak funguje připojení MCP k danému LLM klientu !!

Funkce

• rozvrh - Získání rozvrhu pro konkrétní datum nebo aktuální rozvrh
• staly_rozvrh - Získání stálého rozvrhu (základní rozvrh bez změn)
• absence - Získání informací o basencích
• znamky - Získání informací o známkách

Instalace a spuštění

Dostupné transport metody

Server podporuje tři transport metody:

1. CLI (stdio) - Přímá MCP komunikace přes stdin/stdout
2. Proxy (HTTP) - HTTP server pomocí mcp-proxy na portu 8805
3. HTTP Streaming - Nativní HTTP streaming transport na portu 8806

Spuštění jako HTTP Streaming server

Pro spuštění s nativním HTTP streaming transportem na portu 8806:

# Build HTTP streaming image
./build-http.sh
# nebo manuálně
docker build -f Dockerfile.http -t mirecekd/bakalari-mcp:http .

# Spuštění
docker run -p 8806:8806 mirecekd/bakalari-mcp:http \
  --user YOUR_USERNAME \
  --password YOUR_PASSWORD \
  --url https://your-school.bakalari.cz

Server bude dostupný jako HTTP streaming MCP na http://localhost:8806.

Spuštění jako HTTP server pomocí MCP proxy

Pro spuštění jako HTTP server na portu 8805:

# Build MCP proxy image
./build-proxy.sh
# nebo manuálně
docker build -f Dockerfile.proxy -t mirecekd/bakalari-mcp:proxy .

# Spuštění s environment variables
docker run -e BAKALARI_USER=your_user -e BAKALARI_PASSWORD=your_pass -e BAKALARI_URL=your_url -p 8805:8805 mirecekd/bakalari-mcp:proxy

Server bude dostupný jako SSE MCP na http://localhost:8805.

Spuštění pomocí Docker (stdio mode)

Rychlé spuštění

# Build CLI Docker image
./build-cli.sh
# nebo manuálně
docker build -f Dockerfile.cli -t mirecekd/bakalari-mcp:cli .

# Spuštění přes Docker
docker run --rm -i mirecekd/bakalari-mcp:cli \
  --user USERNAME \
  --password PASSWORD \
  --url https://your-school.bakalari.cz

Spuštění s docker-compose

# Zkopíruj a upravuješ konfiguraci
cp .env.example .env
# Edituj .env s tvými údaji

# Spuštění
docker-compose up bakalari-mcp-server

# Nebo pro development (s live reloading)
docker-compose --profile dev up bakalari-mcp-dev

Přímé spuštění jedním příkazem

# Pro MCP konfiguraci - nahraď uvx příkaz tímto:
docker run --rm -i ghcr.io/mirecekd/bakalari-mcp:latest-cli \
  --user YOUR_USER \
  --password YOUR_PASSWORD \
  --url https://skola.bakalari.cz

Spuštění pomocí uvx (alternativa)

Pokud máš již vybuilděný balíček:

# Z místního wheel souboru
uvx --from ./dist/bakalari_mcp_server-1.0.0-py3-none-any.whl bakalari-mcp-server --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

# Nebo z aktuálního adresáře během vývoje
uvx --from . bakalari-mcp-server --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

Jak to funguje

Build balíčku

Pro vytvoření distribučního balíčku:

# Instalace build nástrojů
pip install build

# Vytvoření balíčku
python3 -m build

# Výsledné soubory najdeš v dist/

Spuštění ze zdrojového kódu

# Instalace závislostí
pip install fastmcp aiohttp

# Spuštění ze zdrojového kódu
python3 src/bakalari_mcp_server/server.py --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

Parametry

• --user (povinný): Uživatelské jméno pro Bakaláři
• --password (povinný): Heslo pro Bakaláři
• --url (povíně volitelný): URL Bakaláři serveru (výchozí: https://skola.bakalari.cz)

Dostupné nástroje

rozvrh(datum)

Získá rozvrh pro zadané datum s dekódovanými informacemi.

Parametry:

• datum (volitelný): Datum ve formátu YYYY-MM-DD. Pokud není zadáno, použije se dnešní datum.

Příklad odpovědi:

{
  "datum": "2025-05-15",
  "den_tydne": 5,
  "hodiny": [
    {
      "hodina": "1",
      "cas": "8:00 - 8:45",
      "predmet": "Matematika",
      "zkratka_predmetu": "M",
      "ucitel": "Nov",
      "mistnost": "123",
      "tema": "Kvadratické rovnice",
      "zmena": {
        "typ": "Modified",
        "popis": "Změna učitele"
      }
    }
  ],
  "pocet_hodin": 6
}

staly_rozvrh()

Získá stálý rozvrh (základní rozvrh bez změn).

Příklad odpovědi:

{
  "typ": "staly_rozvrh",
  "dny": [
    {
      "den_tydne": 1,
      "den_cislo": 1,
      "hodiny": [
        {
          "hodina": "1",
          "cas": "8:00 - 8:45",
          "predmet": "Matematika",
          "zkratka_predmetu": "M",
          "ucitel": "No