Bakaláři MCP 服务器

关键词

学校信息系统课程表出勤成绩自然语言接口

使用说明内容（Markdown格式）

  • 项目简介

    • 该仓库实现了一套基于 MCP（Model Context Protocol）的 Bakaláři v3 API 后端服务器，旨在为大型语言模型客户端提供结构化的上下文信息和功能访问。通过该服务器，LLM 客户端能够读取课程表、固定日程、缺勤信息、成绩等资源，并注册/执行相关“工具”来完成对 Bakaláři 系统的读取与处理。

  • 主要功能点

    • 支持多种传输方式：标准输入输出（stdio/CLI）、HTTP Streaming、通过 MCP 代理的 HTTP 传输等，适配不同的客户端接入方式。
    • 提供可被调用的“工具（Tools）”，包括：
      • rozvrh：获取指定日期的课程表（若不指定日期则使用今天）；
      • staly_rozvrh：获取固定/基础日程表；
      • absence：获取学生缺勤信息（按日和按科目整理）；
      • znamky：获取各科目成绩与统计信息。
    • 内置自动化的认证与 API 调用逻辑：通过 Bakaláři API 进行身份认证，支持 access_token/refresh_token 的自动刷新。
    • 以 MCP 规范封装数据输出，适用于与 LLM 客户端的 JSON-RPC 交互，输出包含日期、时段、教师、科目、教室、变更信息等字段。
    • 提供 HTTP 版本的服务器实现（server_http.py）以支持原生 HTTP 流式传输，并在 main() 的实现中完成参数解析与服务启动。

  • 安装步骤

    • 环境与依赖
      • 需要 Python 3.8+ 环境
      • 安装依赖：fastmcp、aiohttp 等
    • 运行入口（stdio 模式，直接与 LLM 客户端通过 stdin/stdout 交互）
      • 运行命令示例（需替换用户名、密码、URL）（非执行代码，仅示意）：
        • python3 src/bakalari_mcp_server/server.py --user YOUR_USERNAME --password YOUR_PASSWORD --url https://your-school.bakalari.cz
    • 运行入口（HTTP Streaming 模式）
      • 运行命令示例（需替换用户、密码、URL；监听 8806 端口）：
        • python3 src/bakalari_mcp_server/server_http.py --user YOUR_USERNAME --password YOUR_PASSWORD --url https://your-school.bakalari.cz
    • 运行入口（通过 MCP Proxy 的 SSE/HTTP 传输模式）
      • 参考环境变量与启动参数，按 README 中的说明进行 Docker 运行或本地启动
    • 额外资源
      • 该仓库提供 GHCR 的预构建镜像（CLI、Proxy、HTTP Streaming），可直接用于生产或测试
    • 开发与测试（可选）
      • 进入源码目录，安装开发依赖并直接运行 main() 入口进行快速验证

  • 服务器配置（MCP 客户端配置示例，JSON 格式）

    • 该配置用于描述 MCP 客户端如何连接本仓库实现的服务器（server name、command、args 等）。请将 YOUR_USERNAME、YOUR_PASSWORD、YOUR_URL 替换为实际值。 { "mcpServers": { "bakalari-mcp-server": { "autoApprove": [ "rozvrh", "staly_rozvrh", "absence", "znamky" ], "disabled": false, "timeout": 60, "command": "python3", "args": [ "src/bakalari_mcp_server/server.py", "--user", "YOUR_USERNAME", "--password", "YOUR_PASSWORD", "--url", "https://your-school.bakalari.cz" ], "transportType": "stdio" } } }

  • 基本使用方法

    • 连接与调用
      • 使用 MCP 客户端的标准方式，连接到 bakalari-mcp-server，并按需调用工具，例如 rozvrh、staly_rozvrh、absence、znamky。
    • 常见操作示例
      • 读取今天的日程：调用工具 rozvrh（不传日期）
      • 读取指定日期的日程：调用工具 rozvrh，传入 datum 的参数（格式 YYYY-MM-DD）
      • 获取固定日程：调用工具 staly_rozvrh
      • 获取成绩单：调用工具 znamky
    • 错误处理
      • 服务器端输出包含错误信息时，请检查 Bakaláři API 的网络连通性、用户名/密码、以及 API 的响应格式是否符合预期。
    • 调试与扩展
      • 通过 server.py 与 server_http.py 的实现，可以扩展新的工具或对现有工具进行增强，适配更多 Bakaláři API 的端点。

  • 备注

    • 服务器会自动处理 Bakaláři API 的身份认证、令牌刷新等细节，避免客户端重复的认证流程。
    • 支持多种传输协议，方便在不同的 LLM 客户端中嵌入和部署。

关键词 学校信息系统, 课程表, 出勤, 成绩, 自然语言接口

分类 5

服务器信息

访问项目