Canvas Agent

帆布代理

连接人工智能助手（谷歌的Gemini CLI、Claude Code和Claude Desktop）的MCP服务器 指令画布LMS。教师和管理员可以通过自然语言管理课程、作业、成绩等。

想安装Canvas Agent吗？ 请按照以下设置指南进行操作： **** --不需要技术背景。

______________________________________________________________________

建筑

Canvas Agent作为 三 主控程序 来自一个npm包的服务器，因意图而分裂。默认情况下，安装向导会注册所有三个；想要保存上下文的用户可以从MCP配置中删除admin或extra。

AI client (Claude Code / Claude Desktop / Gemini CLI)
  ├─ spawns canvas-agent          (core, 80 tools — daily teaching/grading)
  ├─ spawns canvas-agent-admin    (18 tools — course/section/enrollment lifecycle)
  └─ spawns canvas-agent-extras   (36 tools — outcomes, groups, pages, files, messaging, …)
        └─ MCP stdio transport
             └─ Canvas REST API (bearer token auth)

这三个箱子共享一个导入图和一个每门课程的保险库，因此匿名令牌在服务器之间保持一致。核心还包括 describe_canvas_mcps 工具，这样AI就可以在所需工具未加载时告诉用户要安装哪个其他箱子。

工具模块

从v1.x迁移

v2将v1单MCP表面划分为核心/管理/附加。如果你现有的配置只是 canvas-agent，您将继续工作，但无法访问任何移出核心的内容。将相关bin添加到MCP配置中：

{
  "mcpServers": {
    "canvas-agent":         { "command": "npx", "args": ["-y", "canvas-agent"] },
    "canvas-agent-admin":   { "command": "npx", "args": ["-y", "canvas-agent-admin"] },
    "canvas-agent-extras":  { "command": "npx", "args": ["-y", "canvas-agent-extras"] }
  }
}

安装向导(npx canvas-agent setup)默认情况下注册所有三个——再次运行它是最简单的升级路径。

Tool → bin查找（按字母顺序）

如果你在v1中使用了一个工具，这个表告诉你它在哪个v2 bin中。这里没有列出的工具在 canvas-agent （核心）。

保管库、匿名器和显示CLI没有变化——没有数据迁移。您还可以要求AI“描述画布代理的MCP”，它将通过 describe_canvas_mcps 核心工具。

发展

git clone https://github.com/hughsibbele/Canvas-Agent.git
cd Canvas-Agent
npm install
cp .env.example .env     # add your CANVAS_API_URL and CANVAS_API_TOKEN
npm run build
node dist/cli.js                 # start the core MCP server (default canvas-agent bin)
node dist/servers/admin.js       # start admin server directly
node dist/servers/extras.js      # start extras server directly
node dist/cli.js setup           # run the setup wizard
npm test                         # boot all three servers and assert routing

npm run dev 开始 tsc --watch 用于迭代工具模块。

添加工具

1. 确定它属于哪个bucket（核心/管理/附加）——有关现有工具的基本原理，请参阅V2_BUILD_PLAN.md。
2. 添加 server.tool(...) 注册到适当的 register*Core / register*Admin / register*Extras 功能在 src/tools/.ts.创建新的域名文件+注册商（如果需要）；从文件导出并在匹配中导入/调用 src/servers/.ts.
3. 更新中的路由清单 scripts/assert-tool-routing.mjs 如果工具落在admin或extra中。
4. npm test 以验证。
5. 重建(npm run build)并重新启动MCP客户端以获取新工具。

每个工具模块都遵循相同的模式——定义Zod输入模式并将其注册到 server.tool()。查看模板的任何现有模块。

隐私和安全管道

每个Canvas响应都流经一个三级编校管道 canvas-client.ts 在它到达AI助手之前：

1. 结构化PII匿名器 (src/anonymizer.ts).浏览响应并将学生姓名、电子邮件、登录ID、SIS ID等交换为不透明令牌(Student_)在每个用户形状的物体上。将每个用户记录在由Canvas user_id键入的每门课程库中，并带有派生角色标签。
2. 自由文本名称检测器 (src/name-detector.ts).扫描自由文本字段（讨论正文、提交散文、评论、描述、文件名）以查找任何已知学生的全名或可排序表单("Jane Doe" / "Doe, Jane")并用学生现有的令牌替换匹配项。使用支持Unicode的边界，因此名称带有撇号(O'Brien)和连字符(Smith-Jones)正确匹配。当然，当vault发生变化时，正则表达式会被缓存并失效。
3. 即时注入沙盒 (src/sandbox.ts).用每个进程的随机数分隔符包裹同一组自由文本字段(…)因此，下游的法学硕士将学生撰写的内容视为数据，而不是指令。随机数是过程随机的——学生无法猜测它会伪造一个结束标签并“突破”沙盒。

在写入路径上， rehydrateText 将令牌交换回真实名称，并剥离LLM可能回显的任何沙盒标记，因此评论和公告会正确地发出，不会将保护标记泄漏到Canvas中。

角色——教师保持可读性

vault将每个用户标记为 student, teacher，或 unknown。角色来源于注册上下文(enrollments[].type, grader_* / assessor / edited_by / graded_by 字段位置）并单调合并(teacher > student > unknown，从不降级）。 知名教师完全跳过标记化 --他们的真实姓名会传递给人工智能。这使“我给这个评分了吗？”这样的工作流程保持正常，避免了将员工视为隐私保护的对象。

CLI工具

canvas-agent reveal Student_a4f2c1              # decode a token (any course)
canvas-agent reveal Student_a4f2c1 --course 42  # single course
canvas-agent reveal --all --course 42           # dump every entry for a course

canvas-agent vault-gc                           # dry-run report of orphan vault rows
canvas-agent vault-gc --apply                   # actually prune them
canvas-agent vault-gc --course 42 --verbose     # scope + show student-by-student detail

vault-gc 清理1.5.0之前版本下累积的孤立行 id-vs-user_id bug，其中每个讨论条目/提交/评论都会生成一个由条目id而不是用户id键入的幻影保险库行。默认模式为模拟运行。

整个管道可以通过以下方式禁用 CANVAS_AGENT_ANONYMIZE=0 （关闭匿名化和自由文本名称检测）或 CANVAS_AGENT_SANDBOX=0 （仅关闭提示注射包装）。

值得了解的极限

• search_term 查询命中了Canvas的实名索引。如果AI发送令牌，Canvas将一无所获——离线显示并搜索 user_id 相反。
• download_submissions 按设计将提交附件（Word文档、PDF等）作为原始字节写入磁盘。这些文件包含真实的学生姓名和提交内容；它们会保留在您的本地计算机上，但不会被编辑。
• 自由文本名称检测器只匹配全名和可排序的形式。只有名字和姓氏的引用不会发生变化（故意——常见英语单词上有太多误报）。
• 帐户级终结点(/accounts/*，顶级 /conversations 列表）不包含每门课程的上下文，因此每门课程库不适用于它们。

画布API gotchas

在添加或更新工具时，有几件事值得了解：

• 分级期 范围分数和提交到一个学期/学期。通过 grading_period_id 到 /courses/{id}/enrollments （每个周期的回报 current_score/current_grade)以及 /courses/{id}/students/submissions （仅返回该期间的提交内容）。没有它，你会得到累积数据，这对于每学期成绩册重置的一年制课程来说是错误的。
• /courses/{id}/grading_periods 返回包装好的响应 — {"grading_periods": [...], "meta": {...}} --所以 canvasAll 分页助手无法将其变平。请使用 canvas 并手动打开包装（参见 list_grading_periods 在 tools/courses.ts).
• 分析端点不支持 grading_period_id — get_student_summaries, get_course_assignment_analytics，以及 get_student_assignment_data 始终返回生命周期总计。对于学期范围的数据，请直接使用 grading_period_id.

链接

• npm: 帆布代理
• 安装指南:
• 画布API文档: canvas.instructure.com/doc/api

许可证

麻省理工学院