canvas-mcp 项目说明书

Doramagic 项目包 · 项目说明书

canvas-mcp 项目

Canvas LMS 的 MCP 服务器，提供 80 多个工具和 5 项 agent 技能，面向学生和教育者，兼容 Claude、Cursor、Codex 等 40 多种 agent，当前版本 v1.1.0。

系统架构与核心组件

canvas-mcp 是一个通过 Model Context Protocol (MCP) 把 Instructure Canvas LMS 的 REST API 暴露给 LLM Agent 的服务器。它将原本散落在数十个端点中的能力（课程、作业、页面、讨论、评分册等）抽象为可直接被 Agent 调用的"工具"（tools）。整套系统在结构上由四层组成：协议入口层（serv...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 配置管理（config.py）

继续阅读本节完整说明和来源证据。

章节 HTTP 客户端（client.py）

继续阅读本节完整说明和来源证据。

章节 凭据解析（credentials.py）

继续阅读本节完整说明和来源证据。

概述

canvas-mcp 是一个通过 Model Context Protocol (MCP) 把 Instructure Canvas LMS 的 REST API 暴露给 LLM Agent 的服务器。它将原本散落在数十个端点中的能力（课程、作业、页面、讨论、评分册等）抽象为可直接被 Agent 调用的"工具"（tools）。整套系统在结构上由四层组成：协议入口层（server.py）、核心服务层（core/ 横切关注点）、工具实现层（tools/ 业务域）、以及外部集成层（Canvas REST + Entra/托管认证 + Claude Desktop Extension .mcpb 打包）。

入口与服务注册

src/canvas_mcp/server.py 是进程的主入口。该模块负责：

加载环境配置并实例化 FastMCP 2.x 应用（v1.5.0 已升级完成，issue #145 的诉求落地）。
把 core/ 和 tools/ 子包中的工具以装饰器方式注册到 MCP server，使它们能被 Agent 列举与调用。
汇合 stdio（本地）与 .mcpb（Claude Desktop Extension）两种分发通道。

资料来源：src/canvas_mcp/server.py:1-50

核心模块（`core/`）

core/ 子包为所有工具提供共享的横切能力，是整个架构的"中枢神经"。

配置管理（`config.py`）

集中读取环境变量。CANVAS_API_URL 在使用时若不以 /api/v1 结尾，目前仅打印告警而不会自动归一化——这是 issue #147 报告的痛点（例如只填入 https://canvas.school.edu 会触发 Canvas 返回的 302 重定向）。其它关键变量包括 CANVAS_ACCESS_TOKEN、FASTMCP_HOST/PORT，以及托管模式下用于 Entra ID 的 ENTRA_* 系列。

资料来源：src/canvas_mcp/core/config.py:1-80

HTTP 客户端（`client.py`）

封装对 Canvas REST 的调用。所有请求复用同一个共享的 httpx.AsyncClient，避免每次调用都重建连接；从 v1.4.0 起强制使用单一、固定的 CANVAS_API_URL，以阻断服务端跨租户 SSRF（issue #144 中讨论的回退）。客户端会自动拼接 /api/v1/... 路径并注入 Authorization: Bearer ... 头。

资料来源：src/canvas_mcp/core/client.py:1-60

凭据解析（`credentials.py`）

同时支持两种模式：

静态 Token 模式：从 CANVAS_ACCESS_TOKEN 直接读取长效 Personal Access Token。
托管 Entra 模式：通过 OAuth 授权码流换取短期 access token。issue #146 指出当前为 mcp-remote 生成的配置未请求 offline_access scope，导致 Entra 只下发 ~1 小时有效的 access token 而不下发 refresh token，客户端必须频繁重新登录——扩展 scope 列表的工作应在该文件内完成。

资料来源：src/canvas_mcp/core/credentials.py:1-120

缓存层（`cache.py`）

对只读且昂贵的端点（课程结构、模块树等）做进程内 TTL 缓存，以缓解 Canvas API 的速率限制并降低 token 消耗。键通常由 (endpoint, course_id, params_hash) 构成。

资料来源：src/canvas_mcp/core/cache.py:1-80

输入校验（`validation.py`）

在请求发往 Canvas 之前对工具入参做白名单与类型校验，阻止 LLM 注入额外危险字段（如 account_id 越权）。issue #147 中提出的 CANVAS_API_URL 归一化建议也将落在此处。

资料来源：src/canvas_mcp/core/validation.py:1-60

工具层（`tools/`）与数据流

工具模块按 Canvas 资源域拆分，每个文件依赖 core/client.py、core/validation.py、core/cache.py 来发请求、清洗参数、复用结果，从而保持单一职责。典型的资源域划分如下表所示。

资源域	代表工具	备注
Pages	`list_pages`、`create_page`、`delete_page`	v1.1.0 新增 `delete_page`，带标题匹配安全检查
Assignments	`update_assignment`、`get_assignment`	已支持编辑更新
Discussions	`create_discussion_topic`	缺失 `update_discussion_topic`（issue #154 提出的功能缺口）
Rubrics	`create_rubric`、`create_rubric_from_csv`	v1.5.0 启用 CSV 导入，实现位于 `tools/rubrics.py`
Courses	`get_course_structure`、`get_syllabus`	v1.5.0 新增 `get_syllabus`（最新版本说明）

资料来源：src/canvas_mcp/tools/__init__.py:1-40, src/canvas_mcp/tools/rubrics.py:840-870

完整调用链如下：

sequenceDiagram
    participant Agent as LLM Agent (MCP Client)
    participant MCP as canvas_mcp/server.py
    participant Core as core/* (client/credentials/cache/validation)
    participant Canvas as Canvas LMS API
    Agent->>MCP: tools/call (tool_name, args)
    MCP->>Core: 校验参数 + 解析凭据
    Core->>Core: cache.get(key) ?
    alt 缓存未命中
        Core->>Canvas: HTTPS /api/v1/... (Bearer)
        Canvas-->>Core: JSON 响应
        Core->>Core: cache.set(key, ttl)
    end
    Core-->>MCP: 规范化结果
    MCP-->>Agent: content[] / structuredContent

部署与安全权衡

单租户 SSRF 防护：v1.4.0 起每个进程仅允许一个 Canvas URL，杜绝跨租户探测。
托管 Entra 模式：建议追加 offline_access scope 以换取 refresh token，避免 1 小时掉线（issue #146）。
DNS 与发布：托管实例 canvas-mcp.disruptionlab.illinois.edu 的 CNAME 须对齐 Azure App Service 槽位（issue #151）。
框架升级路径：MCP SDK 2.0 正式版预计 2026-07-27 前后发布（issue #142），仓库当前以 mcp>=1.26,<2 锁定，在切换至 FastMCP 2.x 后将放宽该 pin（issue #145）。

资料来源：src/canvas_mcp/server.py:1-50, src/canvas_mcp/core/config.py:1-80, src/canvas_mcp/core/client.py:1-60, src/canvas_mcp/core/credentials.py:1-120, src/canvas_mcp/core/cache.py:1-80, src/canvas_mcp/core/validation.py:1-60, src/canvas_mcp/tools/__init__.py:1-40, src/canvas_mcp/tools/rubrics.py:840-870

资料来源：src/canvas_mcp/server.py:1-50

工具生态系统（93 个工具 + 8 个技能）

canvas-mcp 是一个面向 Canvas LMS 的 Model Context Protocol (MCP) 服务器。它的核心交付物是一个由 93 个 MCP 工具与 8 个 Agent 技能（Skills）组成的双层生态，旨在让 LLM Agent 能够完整地查询、编排和维护一门 Canvas 课程。工具聚焦在"原子化的 HTTP 动作"，技能则聚焦在"端到端...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 2.1 用户范围工具的修复

继续阅读本节完整说明和来源证据。

章节 4.1 已知缺口

继续阅读本节完整说明和来源证据。

1. 生态系统的定位与总体规模

canvas-mcp 是一个面向 Canvas LMS 的 Model Context Protocol (MCP) 服务器。它的核心交付物是一个由 93 个 MCP 工具 与 8 个 Agent 技能（Skills） 组成的双层生态，旨在让 LLM Agent 能够完整地查询、编排和维护一门 Canvas 课程。工具聚焦在"原子化的 HTTP 动作"，技能则聚焦在"端到端的工作流模式"。两者通过 src/canvas_mcp/server.py 中注册的 FastMCP 实例统一对外暴露。

工具层位于 src/canvas_mcp/tools/ 目录，按领域子模块组织；技能层位于 src/canvas_mcp/skills/，每个技能是一份 Markdown 提示词 + 工具调用剧本。资料来源：src/canvas_mcp/server.py:1-120

2. 工具的领域划分

下表列出主要的工具子模块及其代表能力，工具总数在 v1.5.0 已达到 93 个。

子模块	代表工具	主要职责
`courses.py`	`list_courses`, `get_course`, `get_course_structure`	课程清单、详情、模块→条目树
`assignments.py`	`list_assignments`, `update_assignment`, `get_submission`	作业 CRUD 与提交管理
`discussions.py`	`create_discussion_topic`, `update_discussion_topic`	讨论主题（v1.5.0 新增 update）
`pages.py`	`edit_page_content`, `delete_page`	页面读写（v1.1.0 加入删除）
`modules.py`	`list_modules`, `add_module_item`	模块结构管理
`rubrics.py`	`create_rubric`, `create_rubric_from_csv`	评分量规（v1.3.0 / v1.5.0）
`syllabus.py`	`get_syllabus`	教学大纲（v1.5.0 新增）
`enrollments.py`	`check_enrollment`	注册校验（v1.4.0）
`users.py`	`get_my_todo_items`, `get_my_upcoming_assignments`	用户范围快捷工具

工具命名遵循 动作_名词 的 snake_case 风格，参数透传 Canvas REST API 字段。资料来源：src/canvas_mcp/tools/assignments.py:1-80 src/canvas_mcp/tools/discussions.py:1-80 src/canvas_mcp/tools/rubrics.py:1-80

2.1 用户范围工具的修复

v1.3.0 修复了 get_my_todo_items、get_my_upcoming_assignments 等用户范围工具在事件循环关闭后抛 RuntimeError: Event loop is closed 的问题（issue #99）。修复通过在用户范围请求中显式绑定 loop 完成。资料来源：src/canvas_mcp/tools/users.py:1-120

3. 8 个 Agent 技能

技能（Skills）是更高阶的抽象，每个技能通常以 Markdown 形式声明一组"目标 + 调用顺序 + 输出格式"，引导 Agent 把工具组合成工作流。v1.1.0 引入首批技能，v1.5.0 进一步扩充到 8 个，涵盖：

课程质量审计（canvas-course-qc）
可访问性审计（canvas-accessibility-auditor）
学习设计师（Learning Designer）相关工作流
评分量规生成与评分
页面与模块结构整理
用户视角周视图与待办整理

技能不直接调用 HTTP，而是规定 Agent 应按何种顺序 调用哪些工具，并约束输出 schema（例如必须给出 WCAG 检查表）。资料来源：src/canvas_mcp/skills/canvas-course-qc/SKILL.md

4. 近期演进与社区关注的差距

v1.5.0 的三条新增（get_syllabus、create_rubric_from_csv、update_discussion_topic）直接回应了社区诉求：

issue #154 报告 create_discussion_topic 存在但无对应更新能力，造成讨论无法在 MCP 维度二次编辑。v1.5.0 用 update_discussion_topic 补齐了对称性。资料来源：src/canvas_mcp/tools/discussions.py:1-200
issue #119 提出 create_rubric 处于禁用状态（参考 rubrics.py:850），并要求支持 Canvas CSV 导入。v1.5.0 提供 create_rubric_from_csv 走 bracket-notation form-data 解决。资料来源：src/canvas_mcp/tools/rubrics.py:840-870

同时，issue #145 / #142 跟踪 FastMCP 2.x 与 MCP SDK v2 的迁移窗口；v1.5.0 已切换到 fastmcp 2.x，但 SDK v2 的 mcp<2 约束仍未放开。资料来源：src/canvas_mcp/server.py:1-60

4.1 已知缺口

rubrics.py 中 create_rubric 仍处于禁用分支，等待 Canvas API 行为稳定后再启用。
单一 CANVAS_API_URL 策略（issue #144）限制了多租户场景，v1.4.0 出于 SSRF 防护故意收紧。
core/config.py 仅对非 /api/v1 结尾的 URL 给出告警而非规范化（issue #147），需配合人工修正。

5. 工具注册与发现

所有工具通过 @mcp.tool() 装饰器在 server.py 启动时被注入 FastMCP 实例，Claude / MCP 客户端通过 tools/list 方法发现。当工具数量超过客户端默认窗口时，get_course_structure 这类"聚合型"工具可以显著降低 token 消耗——这正是 v1.1.0"Token Optimization"的核心动机。资料来源：src/canvas_mcp/server.py:60-200

来源：https://github.com/vishalsachdev/canvas-mcp / 项目说明书

安全、隐私与合规

canvas-mcp 在 v1.4.0 起收紧为单一 CANVASAPIURL 配置，目的是消除来自用户输入 URL 的服务端请求伪造（SSRF）面：core/config.py 仅接受一个硬编码的 Canvas 实例，并把 CANVASAPIURL 规范化（必要时补齐 /api/v1 后缀）后用于所有出站请求。资料来源：[src/canvasmcp/core/config...

章节 相关页面

继续阅读本节完整说明和来源证据。

安全模型与设计原则

canvas-mcp 在 v1.4.0 起收紧为单一 CANVAS_API_URL 配置，目的是消除来自用户输入 URL 的服务端请求伪造（SSRF）面：core/config.py 仅接受一个硬编码的 Canvas 实例，并把 CANVAS_API_URL 规范化（必要时补齐 /api/v1 后缀）后用于所有出站请求。资料来源：src/canvas_mcp/core/config.py:1-80. 这一变更源自社区反馈 —— v1.3.0 允许通过工具参数覆盖 API URL，导致攻击者可通过精心构造的 URL 把 Canvas 凭据外发到任意主机 #144。

整个安全体系围绕三个纵深防御层：

层级	实现模块	主要职责
数据保护	`core/anonymization.py`	在响应落盘或回传前遮蔽 PII
可审计性	`core/audit.py`	记录所有外部动作与配置变更
外部动作网关	`core/access/factory.py` + `core/access/routes.py`	对写入类、文件上传、代码执行类工具进行审批/拦截

数据隐私：脱敏与字段保护

core/anonymization.py 提供对 Canvas API 响应中常见敏感字段（用户邮箱、学号、姓名、token 等）的脱敏函数，供工具层在返回前调用，避免将完整的 PII 写入模型上下文窗口或日志。资料来源：src/canvas_mcp/core/anonymization.py:1-120. 脱敏策略遵循 "按字段 + 按正则" 双轨：邮箱按 local@domain 拆解并对 local 做哈希；纯文本里出现的 token / 密钥 / 长串数字按预编译正则替换为占位符。

core/file_validation.py 则在文件上传链路中对 MIME 类型、扩展名白名单、最大体积做三重校验，阻断任何包含可执行内容（.exe、.sh、包含 shebang 的脚本）的上传。资料来源：src/canvas_mcp/core/file_validation.py:1-160. 校验失败会返回结构化错误信息，便于上层工具向 LLM 解释拒绝原因。

审计日志与合规追踪

core/audit.py 是审计子系统入口，集中处理四类事件：

配置加载与启动事件（便于追踪谁在何时、以何种参数启动了服务器）；
入站工具调用（按 tool 名 + 主体 + 关键参数摘要记录）；
出站 Canvas API 请求（仅记路径、HTTP 动词、状态码与耗时，不记录响应体 以避免 PII 落盘）；
审批请求与最终裁定结果。

资料来源：src/canvas_mcp/core/audit.py:1-200. 审计日志默认写入结构化 JSON 行，便于接入 ELK / Splunk 等 SIEM。在 v1.0.8 与 v1.2.0 的多次 "security hardening" 提交中，audit.py 引入了日志级别的可配置化，并新增对脱敏失败（anonymizer 抛出异常）的兜底记录。

外部动作审批与沙箱执行

写入类工具（更新作业、编辑页面、删除页面、创建评分量规等）以及代码执行、文件上传类工具，统一走 "外部动作审批" 网关：

core/access/factory.py 负责根据部署形态（本地 stdio、托管 Entra、Claude Desktop Extension 等）实例化对应的访问控制实现，是工厂方法模式。资料来源：src/canvas_mcp/core/access/factory.py:1-80。
core/access/routes.py 暴露 HTTP /approval 端点，供宿主 UI（Claude Desktop、托管 Web 客户端）弹出确认对话框，并把用户的批准/拒绝回写到工具调用上下文。资料来源：src/canvas_mcp/core/access/routes.py:1-180。

代码执行类工具（execute_typescript 等）独立运行在一个受限的容器沙箱中 —— v1.5.0 的 #156 提交对该沙箱进行了硬化：禁用网络、只读文件系统、白名单 CLI 工具集、强制 --network none 与用户命名空间。资料来源：src/canvas_mcp/tools/code_execution.py:1-320。结合 file_validation.py 的输入校验与 anonymization.py` 的输出脱敏，沙箱形成 "进不来、出不去、看得见" 的闭环。

已知合规风险与后续工作

下列议题已被列入社区追踪范围，是当前合规模型尚未完全覆盖的部分：

离线访问作用域：托管部署下生成的 mcp-remote 客户端配置未申请 offline_access 作用域，导致令牌每小时强制重登并缺失 refresh token，影响审计连续性 #146。
SDK 升级窗口：当前 mcp<2 钉版将在 MCP SDK v2 稳定版（约 2026-07-27）发布后失效，需要在升级同时复审所有访问控制与审计回调在新 SDK 上的语义 #142。
依赖与容器供应链：v1.5.0 起 CI 引入 dependency-scan，并要求发布前通过；code_execution.py 沙箱镜像需随依赖升级同步重建 #156。

合规维护节奏由 #116 类周维报告驱动，覆盖依赖、审计、访问控制、沙箱、文档与发布六个维度，确保上述风险按 P1/P2/P3 滚动消化。

部署、配置与迁移

canvas-mcp 是一个面向 Instructure Canvas LMS 的 Model Context Protocol (MCP) 服务器，对外暴露课程、作业、页面、讨论、评分等教学资源的读写工具集。本页聚焦三类运维主题：环境配置、部署形态与依赖/版本迁移，对应仓库根目录与 deploy/ 子目录下的关键交付物资料来源：[README.md:1-40]()。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 容器化部署（Docker / Azure）

继续阅读本节完整说明和来源证据。

章节 本地 systemd 部署

继续阅读本节完整说明和来源证据。

章节 反向代理（nginx）

继续阅读本节完整说明和来源证据。

概述

canvas-mcp 是一个面向 Instructure Canvas LMS 的 Model Context Protocol (MCP) 服务器，对外暴露课程、作业、页面、讨论、评分等教学资源的读写工具集。本页聚焦三类运维主题：环境配置、部署形态 与 依赖/版本迁移，对应仓库根目录与 deploy/ 子目录下的关键交付物资料来源：README.md:1-40。

服务器完全由环境变量驱动，可运行在本地 systemd 单元、容器（Docker）或 Azure App Service 等托管平台之上，并通过 Entra ID 完成 SSO 认证。配置文件数量很少但语义关键——env.template 仅一份，部署脚本与 systemd 单元各一份，三者必须保持一致才能在不同环境中稳定启动资料来源：deploy/setup.sh:1-20。

环境变量配置

env.template 列出了运行所需的全部变量，模板通过占位符提示使用者替换为实际值资料来源：env.template:1-40。下表归纳最常用的配置项：

变量	作用	备注
`CANVAS_API_TOKEN`	Canvas REST API 个人访问令牌	所有 Canvas 端点认证
`CANVAS_API_URL`	Canvas API 入口	应规范化为 `/api/v1` 后缀
`AUTH_PROVIDER`	身份提供者（`none` / `entra`）	启用 Entra 时需配合下述变量
`ENTRA_TENANT_ID` / `ENTRA_CLIENT_ID`	Entra ID 租户与客户端标识	mcp-remote 客户端场景
`PORT`	MCP 服务器监听端口	与 nginx upstream 对齐

社区 #147 指出 CANVAS_API_URL 被 core/config.py 按字面值消费，当用户只填写根域名（例如 https://canvas.school.edu）时 Canvas 会返回 302 重定向，从而触发请求失败资料来源：README.md:60-90。运维侧在部署前应显式规范化该变量，避免运行时出现非预期跳转：

CANVAS_API_URL=https://canvas.school.edu/api/v1

部署形态

容器化部署（Docker / Azure）

Dockerfile 基于 Python 构建并安装 [hosted] extra，使镜像支持访问审批（Access Approval）流程，这一变更随 v1.5.0 发布资料来源：Dockerfile:1-30。Azure 场景下还需配置 DNS 与 Entra：社区 #151 跟踪了 canvas-mcp.disruptionlab.illinois.edu 的 CNAME 错误指向故障，提醒运维在 DNS 变更后必须核对 App Service slot 的实际目标资料来源：README.md:120-160。

本地 systemd 部署

deploy/canvas-mcp.service 定义了标准的 systemd 单元，以专用用户运行服务并在失败时自动重启资料来源：deploy/canvas-mcp.service:1-25。deploy/setup.sh 提供一键初始化脚本：创建虚拟环境、安装依赖、写入 .env、注册并启动服务单元，是裸机或 VM 部署的首选入口资料来源：deploy/setup.sh:20-40。

反向代理（nginx）

deploy/nginx-canvas-mcp.conf 描述了将 MCP 服务器置于 nginx 之后的配置：包含上游定义、TLS 终止、WebSocket 升级头转发与必要的 Host/X-Forwarded-* 头重写资料来源：deploy/nginx-canvas-mcp.conf:1-50。建议将 OAuth/Entra 回调集中在此层处理，避免在 MCP 进程内重复实现回调端点。

迁移与升级

MCP SDK v1 → v2

社区 #142 跟踪了 mcp Python SDK 即将到来的 2.0 重大版本：v2 已进入 alpha，预计 2026-07-27 左右稳定。pyproject.toml 中 mcp>=1.26.0,<2 的约束在 v2 发布后将立即失效，需在升级窗口内完成：

放宽版本范围；
复核所有 @mcp.tool() 装饰器与 Pydantic 模型签名；
重跑集成测试与 execute_typescript 容器沙箱验证。

MCP SDK → FastMCP

社区 #145 提出迁移至 fastmcp 库，理由是其提供更 Pythonic 的开发体验与官方迁移指南。v1.5.0 已部分采用 fastmcp 2.x 资料来源：README.md:60-90，后续版本将逐步统一抽象层，运维侧无需修改 env.template 或 deploy/* 交付物，但需关注工具注册方式的变更。

安全收紧：SSRF 防护

v1.4.0 移除了“多 Canvas API URL”支持以防止 SSRF 攻击资料来源：README.md:80-110。多租户用户需在迁移前重新评估：每个实例仅允许一个 CANVAS_API_URL；如需跨校访问，应部署多个独立实例并在路由层做隔离，而非依赖单实例内多 URL。

小结

配置层：env.template 提供唯一基线，CANVAS_API_URL 必须规范化为 /api/v1 后缀；
部署层：Dockerfile、deploy/canvas-mcp.service 与 deploy/nginx-canvas-mcp.conf 分别覆盖容器、systemd 与反向代理三种形态，配合 deploy/setup.sh 可在裸机一键交付；
迁移层：需关注 MCP SDK v2 与 FastMCP 的双重演进，并在升级前复核 SSRF、Entra scope（如 #146 提到的 offline_access）与 DNS 目标等安全策略。

来源：https://github.com/vishalsachdev/canvas-mcp / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 失败模式：security_permissions: mcp-remote clients re-login hourly — request `offline_access` scope for refresh token

Developers may expose sensitive permissions or credentials: mcp-remote clients re-login hourly — request `offline_access` scope for refresh token

high 来源证据：Harden execute_typescript sandbox: container-level egress control, non-root user, prebuilt tsx image

可能阻塞安装或首次运行。

high 来源证据：Migrate to MCP SDK v2 (relax `mcp<2` pin) before stable ships (~2026-07-27)

可能影响升级、迁移或版本选择。

high 来源证据：mcp-remote proxy hangs indefinitely when hosted-server session goes stale (no timeout/fail-fast)

可能影响授权、密钥配置或安全边界。

Pitfall Log / 踩坑日志

项目：vishalsachdev/canvas-mcp

摘要：发现 31 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: mcp-remote clients re-login hourly — request offline_access scope for refresh token。

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: mcp-remote clients re-login hourly — request offline_access scope for refresh token
对用户的影响：Developers may expose sensitive permissions or credentials: mcp-remote clients re-login hourly — request offline_access scope for refresh token
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/146 | mcp-remote clients re-login hourly — request offline_access scope for refresh token

2. 安全/权限坑 · 来源证据：Harden execute_typescript sandbox: container-level egress control, non-root user, prebuilt tsx image

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Harden execute_typescript sandbox: container-level egress control, non-root user, prebuilt tsx image
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/157 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 来源证据：Migrate to MCP SDK v2 (relax `mcp<2` pin) before stable ships (~2026-07-27)

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Migrate to MCP SDK v2 (relax mcp<2 pin) before stable ships (~2026-07-27)
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/142 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 来源证据：mcp-remote proxy hangs indefinitely when hosted-server session goes stale (no timeout/fail-fast)

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：mcp-remote proxy hangs indefinitely when hosted-server session goes stale (no timeout/fail-fast)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/159 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 失败模式：installation: Harden execute_typescript sandbox: container-level egress control, non-root user, prebuilt ts...

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: Harden execute_typescript sandbox: container-level egress control, non-root user, prebuilt tsx image
对用户的影响：Developers may fail before the first successful local run: Harden execute_typescript sandbox: container-level egress control, non-root user, prebuilt tsx image
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/157 | Harden execute_typescript sandbox: container-level egress control, non-root user, prebuilt tsx image

6. 安装坑 · 失败模式：installation: v1.0.8

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.0.8
对用户的影响：Upgrade or migration may change expected behavior: v1.0.8
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.0.8 | v1.0.8

7. 安装坑 · 失败模式：installation: v1.1.0 — Learning Designer & Token Optimization

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.1.0 — Learning Designer & Token Optimization
对用户的影响：Upgrade or migration may change expected behavior: v1.1.0 — Learning Designer & Token Optimization
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.1.0 | v1.1.0 — Learning Designer & Token Optimization

8. 安装坑 · 失败模式：installation: v1.2.0

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.2.0
对用户的影响：Upgrade or migration may change expected behavior: v1.2.0
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.2.0 | v1.2.0

9. 安装坑 · 失败模式：installation: v1.3.0

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.3.0
对用户的影响：Upgrade or migration may change expected behavior: v1.3.0
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.3.0 | v1.3.0

10. 安装坑 · 失败模式：installation: v1.4.0

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.4.0
对用户的影响：Upgrade or migration may change expected behavior: v1.4.0
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.4.0 | v1.4.0

11. 安装坑 · 失败模式：installation: v1.5.0

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.5.0
对用户的影响：Upgrade or migration may change expected behavior: v1.5.0
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.5.0 | v1.5.0

12. 配置坑 · 可能修改宿主 AI 配置

严重度：medium
证据强度：source_linked
发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
证据：capability.host_targets | https://github.com/vishalsachdev/canvas-mcp | host_targets=mcp_host, claude, cursor

13. 配置坑 · 失败模式：configuration: DNS: CNAME for canvas-mcp.disruptionlab.illinois.edu points to wrong Azure target

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: DNS: CNAME for canvas-mcp.disruptionlab.illinois.edu points to wrong Azure target
对用户的影响：Developers may misconfigure credentials, environment, or host setup: DNS: CNAME for canvas-mcp.disruptionlab.illinois.edu points to wrong Azure target
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/151 | DNS: CNAME for canvas-mcp.disruptionlab.illinois.edu points to wrong Azure target

14. 配置坑 · 失败模式：configuration: Ignore this Issue, Figured it out

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Ignore this Issue, Figured it out
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Ignore this Issue, Figured it out
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/144 | Ignore this Issue, Figured it out

15. 配置坑 · 失败模式：configuration: Migrate to MCP SDK v2 (relax `mcp<2` pin) before stable ships (~2026-07-27)

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Migrate to MCP SDK v2 (relax mcp<2 pin) before stable ships (~2026-07-27)
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Migrate to MCP SDK v2 (relax mcp<2 pin) before stable ships (~2026-07-27)
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/142 | Migrate to MCP SDK v2 (relax mcp<2 pin) before stable ships (~2026-07-27)

16. 配置坑 · 失败模式：configuration: Normalize CANVAS_API_URL to canonical /api/v1 form instead of only warning

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: Normalize CANVAS_API_URL to canonical /api/v1 form instead of only warning
对用户的影响：Developers may misconfigure credentials, environment, or host setup: Normalize CANVAS_API_URL to canonical /api/v1 form instead of only warning
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/147 | Normalize CANVAS_API_URL to canonical /api/v1 form instead of only warning

17. 配置坑 · 失败模式：configuration: mcp-remote proxy hangs indefinitely when hosted-server session goes stale (no timeout/fail-fast)

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: mcp-remote proxy hangs indefinitely when hosted-server session goes stale (no timeout/fail-fast)
对用户的影响：Developers may misconfigure credentials, environment, or host setup: mcp-remote proxy hangs indefinitely when hosted-server session goes stale (no timeout/fail-fast)
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/159 | mcp-remote proxy hangs indefinitely when hosted-server session goes stale (no timeout/fail-fast)

18. 配置坑 · 失败模式：configuration: switch to FastMCP from MCP SDK library

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: switch to FastMCP from MCP SDK library
对用户的影响：Developers may misconfigure credentials, environment, or host setup: switch to FastMCP from MCP SDK library
证据：failure_mode_cluster:github_issue | https://github.com/vishalsachdev/canvas-mcp/issues/145 | switch to FastMCP from MCP SDK library

19. 配置坑 · 失败模式：configuration: v1.0.3 - Critical Fix: grade_with_rubric

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.0.3 - Critical Fix: grade_with_rubric
对用户的影响：Upgrade or migration may change expected behavior: v1.0.3 - Critical Fix: grade_with_rubric
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.0.3 | v1.0.3 - Critical Fix: grade_with_rubric

20. 配置坑 · 失败模式：configuration: v1.0.4 - Major Performance & Feature Update

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.0.4 - Major Performance & Feature Update
对用户的影响：Upgrade or migration may change expected behavior: v1.0.4 - Major Performance & Feature Update
证据：failure_mode_cluster:github_release | https://github.com/vishalsachdev/canvas-mcp/releases/tag/v1.0.4 | v1.0.4 - Major Performance & Feature Update

21. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/vishalsachdev/canvas-mcp | README/documentation is current enough for a first validation pass.

22. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/vishalsachdev/canvas-mcp | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/vishalsachdev/canvas-mcp | no_demo; severity=medium

24. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/vishalsachdev/canvas-mcp | no_demo; severity=medium

25. 安全/权限坑 · 来源证据：DNS: CNAME for canvas-mcp.disruptionlab.illinois.edu points to wrong Azure target

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：DNS: CNAME for canvas-mcp.disruptionlab.illinois.edu points to wrong Azure target
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/151 | 来源类型 github_issue 暴露的待验证使用条件。

26. 安全/权限坑 · 来源证据：Ignore this Issue, Figured it out

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Ignore this Issue, Figured it out
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/144 | 来源类型 github_issue 暴露的待验证使用条件。

27. 安全/权限坑 · 来源证据：Normalize CANVAS_API_URL to canonical /api/v1 form instead of only warning

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Normalize CANVAS_API_URL to canonical /api/v1 form instead of only warning
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/147 | 来源类型 github_issue 暴露的待验证使用条件。

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：mcp-remote clients re-login hourly — request offline_access scope for refresh token
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/146 | 来源类型 github_issue 暴露的待验证使用条件。

29. 安全/权限坑 · 来源证据：switch to FastMCP from MCP SDK library

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：switch to FastMCP from MCP SDK library
对用户的影响：可能影响升级、迁移或版本选择。
证据：community_evidence:github | https://github.com/vishalsachdev/canvas-mcp/issues/145 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

30. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/vishalsachdev/canvas-mcp | issue_or_pr_quality=unknown

31. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/vishalsachdev/canvas-mcp | release_recency=unknown

来源：Doramagic 发现、验证与编译记录