内容
# Canvas LMS for Codex
[](https://github.com/hunterschep/canvas-lms-codex-plugin/stargazers)
[](./LICENSE)
[](https://developers.openai.com/codex/plugins)
[](https://www.instructure.com/canvas)
[](https://github.com/hunterschep/canvas-lms-codex-plugin)
适用于 Codex 的学生优先的 Canvas LMS 工作流程，作为带有捆绑 MCP 服务器的本地插件提供。
此插件帮助 Codex 读取和总结 Canvas 学生和课程团队实际使用的部分：课程、成绩、计划事项、日历事项、用户、小组、章节、页面、文件、文件夹、讨论、对话、搜索、作业、测验、同伴评审、评分标准、结果、模块、提交、预约、协作、会议、媒体、分析、内容导出、迁移和公告。
该插件在 Codex 中作为交互式生产力插件呈现，带有捆绑的 Canvas MCP 工具。
## 社区免责声明
这是一个由独立用户创建的社区构建插件。
- 它不是官方 Instructure 产品。
- 它与 Instructure 无关，也不受 Instructure 认可或维护。
- `Canvas` 和 `Canvas LMS` 是 Instructure 的商标。
## 插件功能
- 显示当前课程，附带成绩上下文
- 总结计划和日历中的即将到来的工作
- 读取和总结课程首页和页面
- 检查课程用户、小组、章节、选项卡、文件、文件夹和讨论
- 检查作业、测验、测验提交、同伴评审、提交和评分工作
- 检查作业组、评分标准和结果
- 搜索 Canvas 收件人、公共课程和课程内容
- 检查对话、书签、收藏、预约组、协作、会议、媒体和外部工具
- 检查课程分析、学习对象日期、停课日期、内容导出、内容迁移和异步进度
- 总结模块和学生进度数据
- 拉取跨课程的最新公告
- 在不支持的学生相关 Canvas REST 端点 `/api/v1/...` 和 `/api/quiz/v1/...` 下回退
## 安装
选择一种安装模式。
发布的安装程序支持 `curl | bash` 和直接 `./install.sh` 使用。
### 个人安装
为您的用户帐户安装插件，并在所有项目中使其可用。
```bash
curl -fsSL https://raw.githubusercontent.com/hunterschep/canvas-lms-codex-plugin/main/install.sh | bash
```
这会将插件复制到 `~/.codex/plugins/canvas-lms` 并更新 `~/.agents/plugins/marketplace.json`。
### 仓库安装
仅为一个工作空间安装插件。
从仓库根目录：
```bash
curl -fsSL https://raw.githubusercontent.com/hunterschep/canvas-lms-codex-plugin/main/install.sh | bash -s -- --repo-root "$PWD"
```
从仓库内的插件目录：
```bash
cd /absolute/path/to/your/repo/plugins/canvas-lms
./install.sh --repo-root /absolute/path/to/your/repo --force
```
这将插件放置在 `/absolute/path/to/your/repo/plugins/canvas-lms` 或重用它，并更新 `/absolute/path/to/your/repo/.agents/plugins/marketplace.json`。
如果您想要仅限仓库行为，请不要运行个人安装。
已提交的源代码 `.mcp.json` 在 git 中保持可移植。工作空间安装保留相对于插件根目录的 MCP 路径，而个人安装重写家目录本地插件副本以使用 Node 二进制文件和 `scripts/canvas-mcp-server.mjs` 的绝对路径。安装程序保持仓库市场名称为 `canvas-local-plugins`，清除过时的缓存 `canvas-lms` 包，并从 `~/.codex/config.toml` 中删除过时的 `canvas-lms@...` 启用块。它不会在 `~/.codex/config.toml` 中注册 `canvas` 作为全局 `[mcp_servers.canvas]` 条目。
如果您正在从旧版本的插件升级，请再次运行安装程序。它会从 `~/.codex/config.toml` 中删除旧的 `canvas-lms managed MCP server` 块。
如果您从个人安装切换到仅限仓库安装，请删除旧的个人副本：
```bash
rm -rf ~/.codex/plugins/canvas-lms
```
然后从 `~/.agents/plugins/marketplace.json` 中删除 `canvas-lms` 条目，或删除该市场文件如果它只包含此插件。
## 安装范围
Codex 中的仓库市场范围和已安装插件范围不同：
- 仓库市场控制插件在何处显示以供发现和安装。
- 在 `/plugins` 中安装后，Codex 在 `~/.codex/plugins/cache/...` 下缓存已安装的包。
- 插件启用存储在 `~/.codex/config.toml` 中。
这意味着从仓库市场安装的插件仍然可以在您从 `/plugins` 禁用或卸载它之前，在其他项目中启用。
## Canvas 设置
在启动 Codex 之前，请在启动它的 shell 中导出 Canvas 环境变量：
```bash
export CANVAS_BASE_URL="https://your-school.instructure.com"
export CANVAS_ACCESS_TOKEN="your_canvas_access_token"
```
可选配置：
```bash
export CANVAS_TIMEOUT_MS="30000"
export CANVAS_USER_AGENT="canvas-lms-codex-plugin/0.4.0"
export CANVAS_ACCEPT_STRING_IDS="1"
```
注意：
- `CANVAS_BASE_URL` 必须使用 HTTPS，除非您正在针对 localhost 进行测试。
- `CANVAS_ACCEPT_STRING_IDS` 默认启用，以便大型 Canvas ID 不会在 JavaScript 中失去精度。
- `CANVAS_ACCESS_TOKEN` 应限定为您的 Canvas 设置允许的最低权限。
## 启动 Codex
安装或更新后：
1. 完全重启 Codex。
2. 打开 `/plugins`。
3. 从您已更新的市场安装或启用 `Canvas LMS`。
4. 启动新线程。
## 在 Codex 中使用它
示例提示：
- `显示我的当前 Canvas 课程和成绩。`
- `总结本周我的即将到来的作业和测验。`
- `读取课程 123 的首页和模块并总结它们。`
- `显示课程 123 中哪些作业已评分、缺失或仍未提交。`
- `总结我活跃班级的最新公告。`
## 工具表面
插件通过 MCP 暴露 103 个 Canvas 工具：
- 身份、课程和成绩：
`canvas_get_current_user_profile`、`canvas_list_student_courses`、`canvas_get_student_course`、`canvas_get_course_grade_summary`
- 用户和工作流：
`canvas_get_user_profile`、`canvas_list_course_users`、`canvas_get_course_user`、`canvas_list_user_activity_stream`、`canvas_get_user_activity_summary`、`canvas_list_user_todo_items`、`canvas_get_user_todo_item_count`、`canvas_list_user_missing_submissions`、`canvas_list_user_page_views`
- 计划和日历：
`canvas_list_upcoming_planner_items`、`canvas_list_calendar_items`
- 页面、模块和公告：
`canvas_list_course_pages`、`canvas_get_page`、`canvas_get_front_page`、`canvas_list_course_modules`、`canvas_list_announcements`
- 作业、作业组、评分标准和结果：
`canvas_list_course_assignments`、`canvas_get_assignment`、`canvas_list_assignment_groups`、`canvas_get_assignment_group`、`canvas_list_course_rubrics`、`canvas_get_course_rubric`、`canvas_list_outcome_results`
- 测验、测验提交、同伴评审和评分：
`canvas_list_course_quizzes`、`canvas_get_quiz`、`canvas_get_new_quiz`、`canvas_list_quiz_submissions`、`canvas_get_current_quiz_submission`、`canvas_get_quiz_submission`、`canvas_get_quiz_submission_time`、`canvas_list_peer_reviews`、`canvas_list_submission_peer_reviews`、`canvas_list_student_submissions`、`canvas_list_graded_assignments`、`canvas_get_submission`
- 小组、章节和选项卡：
`canvas_list_current_user_groups`、`canvas_list_course_groups`、`canvas_get_group`、`canvas_list_group_users`、`canvas_list_course_sections`、`canvas_get_section`、`canvas_list_section_users`、`canvas_list_context_tabs`
- 文件、文件夹、讨论：
`canvas_get_files_quota`、`canvas_list_context_files`、`canvas_list_folder_files`、`canvas_get_file`、`canvas_get_file_public_url`、`canvas_list_context_folders`、`canvas_get_folder`、`canvas_list_discussion_topics`、`canvas_get_discussion_topic`、`canvas_get_discussion_topic_view`、`canvas_list_discussion_entries`、`canvas_list_discussion_entry_replies`
- 对话、搜索、书签和收藏：
`canvas_list_conversations`、`canvas_get_conversation`、`canvas_get_conversations_unread_count`、`canvas_find_conversation_recipients`、`canvas_search_recipients`、`canvas_search_all_courses`、`canvas_search_course_content`、`canvas_list_bookmarks`、`canvas_get_bookmark`、`canvas_list_favorite_courses`、`canvas_list_favorite_groups`
- 协作、调度、媒体和外部工具：
`canvas_list_collaborations`、`canvas_list_collaboration_members`、`canvas_list_potential_collaborators`、`canvas_list_conferences`、`canvas_list_appointment_groups`、`canvas_get_appointment_group`、`canvas_list_appointment_group_users`、`canvas_list_appointment_group_groups`、`canvas_get_next_appointment`、`canvas_list_context_media_objects`、`canvas_list_context_media_attachments`、`canvas_list_media_tracks`、`canvas_list_external_tools`、`canvas_get_external_tool`、`canvas_get_external_tool_sessionless_launch`、`canvas_list_visible_course_nav_tools`
- 分析、操作、导出和迁移：
`canvas_get_progress`、`canvas_get_course_analytics_activity`、`canvas_get_course_analytics_assignments`、`canvas_list_course_analytics_student_summaries`、`canvas_get_course_analytics_student_activity`、`canvas_get_course_analytics_student_assignments`、`canvas_get_course_analytics_student_communication`、`canvas_get_learning_object_date_details`、`canvas_list_blackout_dates`、`canvas_get_blackout_date`、`canvas_list_content_exports`、`canvas_get_content_export`、`canvas_list_content_migrations`、`canvas_get_content_migration`、`canvas_list_content_migration_issues`、`canvas_get_content_migration_issue`
- 回退：
`canvas_request`
回退故意受到限制。它只允许 `/api/v1/...` 和 `/api/quiz/v1/...` 下的同源 Canvas REST 路径，并且仍然需要 `allow_mutation: true`。
## 开发
此仓库是插件根目录：
- `.codex-plugin/plugin.json` 包含 Codex 插件清单
- `API_COVERAGE.md` 记录 Canvas 文档覆盖策略
- `.mcp.json` 连接本地 MCP 服务器
- `skills/canvas-lms/SKILL.md` 包含 Canvas 特定的操作指南
- `scripts/canvas-mcp-server.mjs` 是_stdio MCP 入口点
- `scripts/canvas-mcp-core.mjs` 重新导出核心帮助模块
- `scripts/core/` 包含共享验证、HTTP、分页和摘要帮助程序
- `scripts/tools/` 包含 Canvas API 系列工具处理程序
- `scripts/canvas-mcp-tools.mjs` 组装工具注册表
- `scripts/validate-plugin.mjs` 验证包形状和 MCP 握手
- `install.sh` 安装插件并更新适当的市场文件
验证插件：
```bash
node ./scripts/validate-plugin.mjs
```
## 故障排除
如果 Codex 在安装或首次使用期间显示 `canvas` 的 MCP 启动超时：
- 从 `/plugins` 卸载插件
- 重启 Codex
- 使用实际想要的安装模式重新安装插件
- 重新安装后启动新线程
- 确认您的 shell 在启动 Codex 之前导出了 `CANVAS_BASE_URL` 和 `CANVAS_ACCESS_TOKEN`
- 如果 `/plugins` 仍然显示重复项，请删除任何陈旧的家目录本地 `canvas-lms` 市场条目
- 如果已安装插件但您不想在其他项目中启用它，请从 `/plugins` 禁用或卸载它
如果您之前安装了使用市场名称 `local-repo-plugins` 的仓库副本，请在重新安装 `/plugins` 之前再次运行最新的安装程序。那次迁移将清除旧插件标识，以便 Codex 停止尝试安装陈旧的包。
此插件依赖于 Codex 插件文档中描述的标准捆绑 `.mcp.json` 流。它不会在 `~/.codex/config.toml` 中安装全局 `canvas` MCP 服务器。
个人安装重写家目录本地 `.mcp.json` 以使用绝对 `node` 和服务器路径。工作空间安装故意保持 `.mcp.json` 插件根目录相对，以便仓库副本保持可移植和可审查。
捆绑的 MCP 服务器接受：
- 带有 CRLF 分隔符的 `Content-Length` 帧化 MCP 消息
- 带有 LF 分隔符的 `Content-Length` 帧化 MCP 消息
- 原始 JSON 和换行分隔的 JSON-RPC
它还会在回复中镜像客户端的传输样式。这很重要，因为当前的 Codex 本地插件启动路径可能会发送原始 JSON `initialize` 请求而不是框架化的 MCP 信封。
## 为什么它会损坏
两个问题相互影响：
- 启动路径解析：个人本地插件安装如果 Codex 在没有预期的工作目录或 shell `PATH` 的情况下启动捆绑的 MCP 服务器，则可能会失败
- 传输不匹配：原始服务器只理解框架化的 MCP 输入，并且总是以框架化的输出回复，而 Codex 的本地插件启动路径发送原始 JSON `initialize`
## 为什么现在有效
- 安装程序将绝对 `node` 和服务器路径渲染到个人家目录本地插件副本中
- 服务器接受框架化和原始启动消息
- 服务器以客户端使用的传输样式回复
- 验证器练习所有支持的启动样式，以便在发布前捕获回归
## 安全说明
- 此插件仅将您的 Canvas bearer token 发送到配置的 Canvas 源。
- 原始请求回退仅限于 `/api/v1/...` 和 `/api/quiz/v1/...` 下的 Canvas REST 路径。
- 该插件是为学生集中的 Canvas 工作流程而构建的，而不是广泛的管理员自动化。
- 在使用机构数据之前，请查看代码和权限范围。
## 当前限制
- 尚无专门的文件上传工作流程
- 尚无专用的 New Quizzes 列表工作流程
- 除了明确的 `canvas_request` 回退之外，尚无一级写入工作流程
- 实际租户行为仍然取决于您的机构的范围、权限和功能标志
## 许可证
该项目根据 MIT 许可证获得许可。参见 [LICENSE](./LICENSE)。
