Bakaláři Mcp

Bakaláři MCP Server

用于 Bakaláři v3 API 的 MCP（模型上下文协议）服务。通过标准化的 MCP 接口访问 Bakaláři 学校系统。

注意

!! 使用此项目需要具备一些 Docker/Python 使用经验，并了解如何将 MCP 连接到相应的 LLM 客户端！！

功能

• rozvrh - 获取指定日期的课表或当前课表
• staly_rozvrh - 获取固定课表（未变更的基础课表）
• absence - 获取缺勤信息
• znamky - 获取成绩信息

安装和运行

可用的传输方式

服务支持三种传输方式：

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 流式 MCP 服务运行，可通过 http://localhost:8806 访问。

使用 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

服务将作为 SSE MCP 服务运行，可通过 http://localhost:8805 访问。

使用 Docker 运行（stdio mode）

快速启动

# 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

通过一条命令直接运行

# 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 mode（原有方式）

要使用 Docker 而不是 uvx，请更新 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 mode（使用 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 mode（最新方式）

要使用原生 HTTP 流式传输：

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

GitHub Container Registry (GHCR)

GitHub Container Registry 上提供预构建的 Docker 镜像：

可用镜像：

• 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 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. 在 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 转换为可读的科目、教师和教室名称
• 科目推断：根据课程主题自动识别科目
• 变更处理：检测课程取消、代课及其他变更
• 数据验证：检查日期格式并进行基本验证

课表变更支持

服务能够识别并正确处理：

• 课程取消：标记为 ❌，同时保留原始信息
• 代课：新教师，并附上原教师的引用
• 合并课程：将多节课程合并为一节
• 教室变更：更新上课地点

技术细节

• 协议：通过 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

支持

如果这个工具对你有帮助，你可以支持其开发：