ku-portal-mcp

使用说明（Markdown 格式）

• 项目简介

  • 这是一个完整的 MCP 服务端实现，聚合了韩国대학교校园门户相关的资源与功能，并对外暴露为 MCP 工具集，供 LLM 客户端通过 JSON-RPC 调用进行上下文查询、数据访问与功能执行。

• 主要功能点

  • 登录与会话管理：通过 KU Portal SSO 实现会话并缓存，支持自动重新登录。
  • 公告/学사일정/장학공지/综合检索：提供多类公告、学术日程、奖学金信息等的获取与检索。
  • 图书馆座位实时查询：无认证即可访问的座位状态查询。
  • 个人课程表与 ICS 导出：获取个人课表并可导出 ICS 以便添加到日历。
  • 开设课程、课程教案检索：按学院/系检索课程并获取教案。
  • Canvas LMS 集成：通过 KSSO/SSO 连接 Canvas，获取课程、作业、模块等信息。
  • 部门公告站点聚合：对学科/学院公告站点进行聚合和查询。
  • 部门站点注册与解析：支持通过内置默认 registry 和环境变量 KU_DEPT_URLS 配置站点。
  • 多种数据源的 HTML 抓取与解析：使用 BeautifulSoup、lxml 等解析网页，提取标题、日期、作者、附件等元数据。
  • 安全性与缓存：会话缓存、TTL 检查、错误重试等机制，尽量在错误时进行再尝试。
  • MCP 框架对接：通过 FastMCP 框架实现工具注册、调用、以及服务暴露。

• 安装步骤

  1. 确认环境
     • 需要 Python 3.8+（仓库中示例使用 asyncio、httpx、BeautifulSoup 等）。
  2. 获取代码
     • 克隆仓库或安装包后进入项目目录。
  3. 安装依赖与运行
     • 使用仓库提供的入口直接启动 MCP 服务端（推荐方式）或以包安装方式运行入口脚本。
  4. 设置认证信息
     • 在运行时通过环境变量 KU_PORTAL_ID 和 KU_PORTAL_PW 提供考核用的 KU Portal 登录凭证。
     • 部门站点可以通过 KU_DEPT_URLS 环境变量覆盖默认站点列表。
  5. 启动后测试
     • 启动成功后，使用 MCP 客户端（如 Claude Code）连接该服务器，并通过示例自然语言请求检测连通性。

• 服务器配置（MCP 客户端需要该信息来启动并连接服务器） 注：以下为 JSON 格式的配置项，供 MCP 客户端在设置中使用。字段含义在括号中说明： { "serverName": "ku-portal", // MCP 服务端的标识名，客户端将以此作为命名空间 "command": "ku-portal-mcp", // 启动该 MCP 服务器的可执行命令 "args": [], // 启动命令的参数，当前实现不需要附加参数 "notes": "若使用 uvx 启动，请将 uvx 与服务器入口配合使用；若通过直接执行 Python 包，请确保环境变量 KU_PORTAL_ID 与 KU_PORTAL_PW 已正确设置。" } 说明：

  • serverName 为 Claude Code 等 MCP 客户端在设置中的服务器标识名，便于管理与切换。
  • command 为实际启动 MCP 服务器的程序名称。若使用 uvx，请按客户端文档将 uvx 与 serverName 结合在一起运行；若直接运行已安装的包，则使用 ku-portal-mcp。
  • args 为空时表示直接以默认方式启动，若需要额外启动参数，请按实际环境配置。
  • 该配置仅用于 MCP 客户端的连接管理，实际登录凭证通过 KU_PORTAL_ID 与 KU_PORTAL_PW 环境变量提供。

• 基本使用方法

  • 启动后，向 MCP 客户端发出自然语言请求，例如：
    • “도서관 좌석 현황 보여줘”（查询图书馆座位）
    • “최근 공지사항 보여줘” （获取最新公告）
    • “이번 주 시간표 보여줘” （查看本周课程表）
  • 客户端将通过该 MCP 服务器处理请求、调用相应工具、聚合返回数据。
  • 如需快速测试，先确保环境变量可用并重启客户端会话。

• 其他注意

  • 暴露的工具以字典形式返回，包含 success 字段用于判断请求是否成功，以及数据字段（如 notices, timetable, courses 等）。
  • 如遇会话过期，会自动进行重新登录尝试。