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í.

<div align="center">

</div>

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

<div align="center"> <img src="assets/bakalari-mcp.png" alt="Bakaláři MCP Server Logo" width="400" /> </div>

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": "Nov", 
          "mistnost": "123",
          "skupina": null
        }
      ]
    }
  ]
}

Konfigurace v MCP klientovi (Claude Desktop / n8n)

Pro stdio mode (původní způsob)

Pro použití s Docker místo uvx, aktualizuj MCP konfiguraci:

{
  "mcpServers": {
    "bakalari-mcp-server": {
      "autoApprove": [
        "rozvrh",
        "staly_rozvrh"
      ],
      "disabled": false,
      "timeout": 60,
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/mirecekd/bakalari-mcp:latest-cli",
        "--user",
        "YOUR_USER",
        "--password",
        "YOUR_PASSWORD", 
        "--url",
        "https://skola.bakalari.cz"
      ],
      "transportType": "stdio"
    }
  }
}

Pro HTTP mode (nový způsob s MCP proxy)

Pro použití jako HTTP server přes MCP proxy:

{
  "mcpServers": {
    "bakalari-mcp-server": {
      "autoApprove": [
        "rozvrh",
        "staly_rozvrh"
      ],
      "disabled": false,
      "timeout": 60,
      "url": "http://localhost:8805",
      "transportType": "http"
    }
  }
}

Pro HTTP Streaming mode (nejnovější)

Pro použití s nativním HTTP streaming transportem:

{
  "mcpServers": {
    "bakalari-mcp-server": {
      "autoApprove": [
        "rozvrh",
        "staly_rozvrh"
      ],
      "disabled": false,
      "timeout": 60,
      "url": "http://localhost:8806",
      "transportType": "http"
    }
  }
}

GitHub Container Registry (GHCR)

Pre-built Docker images jsou dostupné na GitHub Container Registry:

Dostupné images:

• CLI (stdio): ghcr.io/mirecekd/bakalari-mcp:latest-cli
• Proxy (HTTP): ghcr.io/mirecekd/bakalari-mcp:latest-proxy
• HTTP Streaming: ghcr.io/mirecekd/bakalari-mcp:latest-http

Použití GHCR images:

# CLI version
docker run --rm -i ghcr.io/mirecekd/bakalari-mcp:latest-cli \
  --user USERNAME --password PASSWORD --url https://school.bakalari.cz

# Proxy version (port 8805)
docker run -p 8805:8805 \
  -e BAKALARI_USER=USERNAME \
  -e BAKALARI_PASSWORD=PASSWORD \
  -e BAKALARI_URL=https://school.bakalari.cz \
  ghcr.io/mirecekd/bakalari-mcp:latest-proxy

# HTTP Streaming version (port 8806)
docker run -p 8806:8806 ghcr.io/mirecekd/bakalari-mcp:latest-http \
  --user USERNAME --password PASSWORD --url https://school.bakalari.cz

Multi-arch support:

Všechny images podporují:

• linux/amd64 (Intel/AMD x64)
• linux/arm64 (Apple Silicon, ARM64)

Postupy pro MCP konfiguraci

1. Vybuduj Docker image:

   cd bakalari-mcp-server
   # Pro stdio mode:
   ./build-cli.sh
   # Pro HTTP mode:
   ./build-proxy.sh
   # Nebo oba najednou:
   ./build-all.sh
   

2. Spusť kontejner (pro HTTP mode):

   docker run -d -e BAKALARI_USER=your_user -e BAKALARI_PASSWORD=your_pass -e BAKALARI_URL=your_url -p 8805:8805 mirecekd/bakalari-mcp:proxy
   

3. Aktualizuj MCP settings aplikace v claude_desktop_config.json, anythingllm_mcp_servers.json, cline_mcp_settings.json

4. Restartuj aplikaci pro načtení nové konfigurace

Autentizace

Server automaticky spravuje autentizaci:

1. Při prvním použití se přihlásí pomocí username/password
2. Získá access_token a refresh_token
3. Při expiraci access_token automaticky obnoví pomocí refresh_token
4. Pokud i refresh_token expiruje, znovu se přihlásí pomocí username/password

Chybové stavy

Všechny nástroje vrací chybové zprávy v případě problémů:

{
  "error": "Popis chyby"
}

Možné typy chyb:

• Chyba autentizace: Neplatné přihlašovací údaje nebo problémy s tokenem
• Chyba API: Problém s komunikací s Bakaláři API
• Neplatný formát data: Špatně zadané datum

Příklad použití v MCP klientovi

# Získání dnešního rozvrhu
result = await mcp_client.call_tool("rozvrh")

# Získání rozvrhu pro konkrétní datum
result = await mcp_client.call_tool("rozvrh", {"datum": "2024-03-15"})

# Získání stálého rozvrhu
result = await mcp_client.call_tool("staly_rozvrh")

Pokročilé funkce

Dekódování rozvrhu

Server inteligentně dekóduje rozvrh pomocí:

• Lookup tabulek: Překlad ID na čitelné názvy předmětů, učitelů, místností
• Inference předmětů: Automatické rozpoznání předmětu z tématu hodiny
• Zpracování změn: Detekce zrušených hodin, suplování a dalších změn
• Validace dat: Kontrola formátu data a základní validace

Podpora změn v rozvrhu

Server rozpoznává a správně zpracovává:

• Zrušené hodiny: Označené jako ❌ se zachováním původních informací
• Suplování: Nový učitel s odkazem na původního
• Spojené hodiny: Sloučení více hodin do jedné
• Změny místností: Aktualizované místo konání

Technické detaily

• Protokol: MCP přes stdio nebo HTTP (s mcp-proxy)
• Framework: FastMCP
• HTTP klient: aiohttp (async)
• Python verze: 3.8+
• Distribuce: source code
• Proxy: mcp-proxy pro HTTP transport

Vývojáři

Pro lokální vývoj:

# Klonování a setup
git clone <repository-url>
cd bakalari-mcp-server

# Instalace dev závislostí  
pip install -e .

# Spuštění pro testování
python3 src/bakalari_mcp_server/server.py --user TEST --password TEST --url https://test.bakalari.cz