Bakaláři Mcp

Bakaláři MCP Server

Bakaláři v3 API 用の MCP（Model Context Protocol）サーバーです。標準化された MCP インターフェースを通じて、Bakaláři 学校システムにアクセスできます。

注意事項

!! このプロジェクトを使用するには、Docker/Python の基本的な知識と、MCP を対象の LLM クライアントに接続する方法についての知識が必要です !!

機能

• rozvrh - 指定した日付または現在の時間割を取得します
• staly_rozvrh - 固定時間割（変更のない基本時間割）を取得します
• absence - 欠席に関する情報を取得します
• znamky - 成績に関する情報を取得します

インストールと起動

利用可能なトランスポート方式

サーバーは次の 3 つのトランスポート方式に対応しています。

1. CLI (stdio) - stdin/stdout 経由で直接 MCP 通信を行います
2. Proxy (HTTP) - mcp-proxy を使用したポート 8805 の HTTP サーバーです
3. HTTP Streaming - ポート 8806 のネイティブ HTTP ストリーミングトランスポートです

HTTP Streaming サーバーとして起動

ポート 8806 でネイティブ HTTP ストリーミングトランスポートを使用して起動するには：

# 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

サーバーは http://localhost:8806 で HTTP ストリーミング MCP として利用できます。

MCP proxy を使用して HTTP サーバーとして起動

ポート 8805 で HTTP サーバーとして起動するには：

# 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

サーバーは http://localhost:8805 で SSE MCP として利用できます。

Docker を使用して起動（stdio モード）

クイックスタート

# 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

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

1 つのコマンドで直接起動

# 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

uvx を使用して起動（代替方法）

パッケージをすでにビルドしている場合：

# 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

仕組み

パッケージのビルド

配布パッケージを作成するには：

# Instalace build nástrojů
pip install build

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

# Výsledné soubory najdeš v dist/

ソースコードから起動

# 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

パラメーター

• --user（必須）：Bakaláři のユーザー名
• --password（必須）：Bakaláři のパスワード
• --url（省略可能）：Bakaláři サーバーの URL（デフォルト：https://skola.bakalari.cz）

利用可能なツール

rozvrh(datum)

指定した日付の時間割を、情報をデコードして取得します。

パラメーター：

• datum（省略可能）：YYYY-MM-DD 形式の日付です。指定しない場合は今日の日付が使用されます。

応答例：

{
  "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()

固定時間割（変更のない基本時間割）を取得します。

応答例：

{
  "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
        }
      ]
    }
  ]
}

MCP クライアントでの設定（Claude Desktop / n8n）

stdio モードの場合（従来の方法）

uvx の代わりに Docker を使用するには、MCP の設定を更新します。

{
  "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"
    }
  }
}

HTTP モードの場合（MCP proxy を使う新しい方法）

MCP proxy 経由で HTTP サーバーとして使用するには：

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

HTTP Streaming モードの場合（最新）

ネイティブ HTTP ストリーミングトランスポートを使用するには：

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

GitHub Container Registry (GHCR)

ビルド済み Docker イメージは GitHub Container Registry で利用できます。

利用可能なイメージ：

• 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

GHCR イメージの使用：

# 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

マルチアーキテクチャ対応：

すべてのイメージが次に対応しています。

• linux/amd64（Intel/AMD x64）
• linux/arm64（Apple Silicon、ARM64）

MCP 設定手順

1. Docker イメージをビルドします：

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

2. コンテナーを起動します（HTTP モードの場合）：

   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. claude_desktop_config.json、anythingllm_mcp_servers.json、cline_mcp_settings.json でアプリの MCP 設定を更新します

4. 新しい設定を読み込むため、アプリを再起動します

認証

サーバーは認証を自動的に管理します。

1. 初回使用時に、username/password を使用してログインします
2. access_token と refresh_token を取得します
3. access_token の期限が切れると、refresh_token を使用して自動的に更新します
4. refresh_token の期限も切れた場合は、username/password を使用して再度ログインします

エラー状態

問題が発生した場合、すべてのツールがエラーメッセージを返します。

{
  "error": "Popis chyby"
}

エラーの種類は次のとおりです。

• 認証エラー：認証情報が無効、またはトークンに問題があります
• API エラー：Bakaláři API との通信に問題があります
• 日付形式が無効：日付の形式が正しくありません

MCP クライアントでの使用例

# 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")

高度な機能

時間割のデコード

サーバーは次の方法で時間割をインテリジェントにデコードします。

• ルックアップテーブル：ID を読みやすい教科名、教師名、教室名に変換
• 教科の推定：授業のトピックから教科を自動認識
• 変更の処理：授業のキャンセル、代講、その他の変更を検出
• データの検証：日付形式の確認と基本的な検証

時間割の変更への対応

サーバーは次の変更を認識し、適切に処理します。

• 授業のキャンセル：元の情報を保持したまま❌で表示
• 代講：元の教師への参照を含む新しい教師
• 合同授業：複数の授業を1つに統合
• 教室の変更：開催場所を更新

技術的な詳細

• プロトコル：stdio または HTTP 経由の MCP（mcp-proxy 使用）
• フレームワーク：FastMCP
• HTTP クライアント：aiohttp（async）
• Python バージョン：3.8+
• 配布形式：ソースコード
• プロキシ：HTTP トランスポート用の mcp-proxy

開発者

ローカル開発の場合：

# 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

サポート

このツールがお役に立ちましたら、開発をご支援いただけます。