tongji-canvas-mcp

面向同济大学 Canvas LMS 的本地 MCP（Model Context Protocol）服务。
该项目通过 Canvas Access Token 访问 https://canvas.tongji.edu.cn 的 API，并把常用能力暴露为 MCP 工具，供 Codex/Agent 调用。

功能概览

当前仓库已实现的核心功能：

1. Canvas 连接与身份验证
   • 检查基础地址与令牌是否已配置（canvas_connection_info）
   • 获取当前登录用户信息（canvas_get_self）
2. 课程查询
   • 列出当前用户课程（支持状态、搜索词、数量限制）
3. 作业查询
   • 查询课程作业（支持 upcoming / missing / all 分桶）
   • 按截止时间排序并处理分页
4. 跨课程即将截止任务聚合
   • 在指定天数窗口内聚合所有活跃课程作业（canvas_list_upcoming_assignments）
5. 运行与部署支持
   • 支持 stdio 与 streamable-http 两种 MCP 传输模式
   • 支持本地 .env 自动加载
   • 提供 macOS launchd 安装/卸载脚本
6. 运维与诊断脚本
   • Canvas 接口连通性快速验证脚本
   • Token 失效轮询监控脚本（输出 CSV 日志）

技术栈

• Python >=3.11
• mcp
• httpx
• setuptools（构建与打包）

目录结构

.
├── pyproject.toml
├── references/
│   └── canvas-api-notes.md
├── scripts/
│   ├── install_mcp_http_launchd.sh
│   ├── run_mcp_http_local.sh
│   ├── uninstall_mcp_http_launchd.sh
│   ├── validate_canvas.py
│   └── watch_token_expiry.py
├── skills/
│   └── tongji-canvas/SKILL.md
└── src/
    └── tongji_canvas_mcp/
        ├── __init__.py
        └── server.py

快速开始

1) 安装依赖

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

2) 配置环境变量

最少需要配置 Canvas Token：

export TONGJI_CANVAS_TOKEN="你的_canvas_access_token"

可选配置：

export TONGJI_CANVAS_BASE_URL="https://canvas.tongji.edu.cn"
export MCP_TRANSPORT="stdio"            # 或 http / streamable-http
export MCP_HTTP_HOST="127.0.0.1"
export MCP_HTTP_PORT="8000"
export MCP_HTTP_PATH="/mcp"

也可以在项目根目录创建 .env，服务启动时会自动读取（简单 KEY=VALUE 格式）。

3) 启动服务

stdio 模式（默认）

tongji-canvas-mcp

HTTP 模式（streamable-http）

MCP_TRANSPORT=http tongji-canvas-mcp

或使用脚本：

./scripts/run_mcp_http_local.sh

MCP 工具说明

项目当前暴露以下工具：

• canvas_connection_info：返回基础地址与令牌是否存在
• canvas_get_self：获取当前用户信息
• canvas_list_courses：列出课程
• canvas_list_assignments：列出课程作业（upcoming / missing / all）
• canvas_list_upcoming_assignments：跨课程聚合近期截止作业

常用脚本

• scripts/validate_canvas.py
  快速验证连通性，输出用户信息、课程样本和近期作业样本。

• scripts/watch_token_expiry.py
  周期性请求 users/self，检测 Token 何时失效，并写入 token_watch_log.csv。

• scripts/install_mcp_http_launchd.sh / scripts/uninstall_mcp_http_launchd.sh
  在 macOS 上安装/卸载本地 launchd 常驻 HTTP 服务。

故障排查

1. 报错 Missing TONGJI_CANVAS_TOKEN
   • 未设置或未正确导出 TONGJI_CANVAS_TOKEN
2. 返回 401/403
   • Token 过期或权限不足，请重新生成并确认作用域
3. HTTP 启动失败
   • 检查 MCP_HTTP_PORT 是否被占用
   • 检查 MCP_HTTP_PATH 是否以 / 开头（项目会自动修正）
4. 分页数据不完整
   • 调大工具 limit 参数；服务内部已处理 Link 分页

安全建议

• 不要在日志、截图或提交记录中暴露完整 Token
• 优先使用环境变量或本地 .env，避免把密钥硬编码到源码
• 若共享机器，建议定期轮换 Token

开发说明

• 入口函数：src/tongji_canvas_mcp/server.py 中的 main()
• 命令行入口：tongji-canvas-mcp
• 打包配置：pyproject.toml

如需扩展能力，建议沿用现有模式：

1. 在 server.py 中新增 @mcp.tool() 异步函数
2. 统一复用 _get / _paginate / _normalize_datetime 等辅助函数
3. 返回结构中保留 meta，方便上层排查速率限制与分页信息