mcp-ccnu-lib CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目定位

华中师范大学图书馆空间预约的 MCP 执行器。被上游"小青团"QQ 机器人当作工具调用：本服务只负责执行（登录、查座、约/取消、暂离/回座/退座、违约/历史/闸机记录），不做 NLU、不做调度、不做提醒——那些在调用方侧。纯 HTTP 实现，无浏览器（历史上用过 Playwright，2026-07 已全量重构为 httpx 直连 CAS + 后端 API）。详尽的对外 API 契约、错误码、部署说明都在 README.md，改动工具签名/返回结构时必须同步更新它。

关键约束：

• 真实系统 https://kjyy.ccnu.edu.cn/jsq-v/（Vue SPA，CAS 统一认证），仅校园网内可访问，部署机必须在校园网。
• 验证码/短信走人工输入（challenge 机制），不做 OCR/自动打码——这是产品决策，不要主动加。

常用命令

# 本地开发（不走 Docker）
pip install -e .                            # 装 httpx + cryptography + mcp，无浏览器
python -m ccnu_lib.server                   # 启动，监听 0.0.0.0:8010/mcp (streamable-http)

# Docker（生产推荐）— 轻量 python:slim 镜像，无 Chromium
docker compose up -d --build

# 冒烟测试（先在另一终端启动服务，再跑）— 走真实 MCP 协议，只读不下单
python scripts/smoke_mcp.py

无单元测试（pyproject.toml 列了 pytest 但仓库无 test 文件）。注意 scripts/ 下的老验证/probe 脚本（try_login/try_api/try_reserve/probe*）是 Playwright 时代的，重构后已失效，仅作接口反推的历史参考；真机验证改用临时脚本走 login.start_login/reservations.*。

Windows 本地连 127.0.0.1 的坑：必须设 NO_PROXY=127.0.0.1,localhost，否则系统代理把本地请求也转走 → 502。（WindowsProactorEventLoopPolicy 那条已随 Playwright 移除，纯 HTTP 不需要。）

架构（关键在于两条数据通路 + challenge 中断模型）

工具调用入口在 server.py（@mcp.tool() 装饰，17 个工具，全部接受可选 user_key 做多用户隔离，缺省 default）。每个工具是薄壳，转发到 login.py 或 reservations.py。

核心设计：纯 HTTP。登录复刻 CAS SSO 重定向链，查询/预约直连后端 JSON API 并在 Python 里现算 HMAC 签名。

1. http_client.py — 进程级单例 HttpManager，每个 user_key 一个 httpx.AsyncClient（cookie jar）。登录态保活载体 = 持久化的 cookie（关键是无过期的 CASTGC，支持静默 SSO 重登）+ 缓存的 app token，一起存 {user_dir}/session.json；建会话时回灌。Session 持有 client/token/realkey/syscfg/asyncio.Lock/pending/login_ctx。

2. login.py — 纯 HTTP CAS 状态机。ensure_syscfg 打 getSysSet 取配置(含 CASSSERVICE/VUESERVICE/hmacKey)并解出 realkey。_sso_walk GET {CAS}/static/sso/login?redirectUrl={VUE} 手动跟随重定向：落到 CAS 登录表单(200,含 execution)=未登录→抓 captcha.jpg 返回 challenge；直接跳回 VUESERVICE 带 ?token=<JWT>（CASTGC 有效时）=静默登录。submit_challenge POST CAS 表单(username/password/captcha/lt/execution)→跟随 ticket→拿 JWT→auth/cas 换 app token。判定真登录=拿到 app token，不是 URL。