ClassDojo Classroom MCP

ClassDojo Classroom MCP

一款非官方、本地优先的模型上下文协议（MCP）服务，面向需要检查和导入 Excel/XLSX 学生名册，或查看、同步和验证 ClassDojo 班级技能的教师。它适用于任何能够启动本地 stdio 服务的 MCP 客户端，包括 Claude Desktop、Codex、Cursor 和 VS Code。

重要

这个社区项目与 ClassDojo 无关联，未获其认可或支持。由于目前尚无官方公开的 ClassDojo API/MCP，它通过本地浏览器适配器使用已登录的 ClassDojo 教师网站。ClassDojo 界面发生变化时，可能需要更新适配器。

繁體中文文件：docs/README.zh-TW.md

为什么需要这个 MCP 服务

ClassDojo 的批量粘贴流程可能会将开头的数字识别为列表编号，而不是学生显示名称的一部分。此服务让名册变更可供审核，并支持两种明确的格式：

• seat_number_dot_name：逐个创建类似 1.Student A 的名称，以保留座位号。
• name_only：不需要座位号时，使用 ClassDojo 更快的批量粘贴流程；如果源班级中有重复姓名，则会拒绝此操作。

每次写入都需要一个有效期为 15 分钟的新预览 ID，以及 confirm: true。保存后，服务会重新读取班级，并比较姓名和人数。

功能

工具	写入数据	用途
classdojo_doctor	否	检查本地浏览器连接、登录状态和可见班级。
classdojo_list_classes	否	列出教师会话中可见的三位数班级。
classdojo_inspect_workbook	否	扫描每个工作表，查找可能的班级、座位号和学生姓名列。
classdojo_get_roster	否	读取当前 ClassDojo 班级名册。
classdojo_get_skills	否	读取正向技能和待改进技能及其分数和图标。
classdojo_get_ui_state	否	检测可能妨碍名册操作的对话框；不会关闭对话框。
classdojo_preview_roster_import	否	将工作簿中的学生与 ClassDojo 进行比较，并创建短期有效的预览 ID。
classdojo_apply_roster_import	是	使用 confirm: true 应用一项预览、保存，并重新读取以进行验证。
classdojo_verify_roster_against_workbook	否	比较预期人数和实际人数、缺失姓名及意外出现的姓名。
classdojo_preview_skill_sync	否	将预设、源班级或内联规则列表与目标班级进行比较，并创建短期有效的预览 ID。
classdojo_apply_skill_sync	是	使用 confirm: true 精确同步一项技能预览，然后重新读取每个班级。
classdojo_verify_skill_sync	否	独立地将当前技能与所选规则来源进行比较。

classdojo_configure_skill_rules MCP 提示词会引导客户端使用内置的 traditional_chinese_classroom_v1 预设，询问用户是否需要修改，显示完整的最终列表，并将预览、审批、应用和验证作为独立步骤处理。

工作簿检查器不会假定工作表名称或列位置固定。它会扫描整个工作簿，查找常见的中英文班级、座位号和姓名表头。预览和验证随后要求明确选择非空的 sheetNames，并提供班级映射，防止 Agent 在不知情的情况下合并重复或不相关的工作表。

安全工作流

1. 运行 classdojo_doctor。
2. 运行 classdojo_inspect_workbook，并选择目标工作表和检测到的班级区块。
3. 运行 classdojo_preview_roster_import，并明确指定 studentNameFormat。
4. 检查班级映射、人数、缺失的座位号和新增内容。
5. 仅在人类批准后，使用返回的 previewId 和 confirm: true 调用 classdojo_apply_roster_import。
6. 运行 classdojo_verify_roster_against_workbook，进行独立的回读检查。

预览	回读验证

所有截图仅包含合成数据。

安全的课堂技能工作流

内置的繁体中文预设包含 9 项正向技能和 6 项待改进技能。这是公开的程序包数据，使用中性的预设 ID；其中不含教师姓名、账号标识符或学生数据。

1. 从 classdojo_configure_skill_rules 提示词开始，或调用 classdojo_get_skills 检查源班级。
2. 检查完整预设，并根据需要添加、移除技能、调整分值或更改图标。
3. 调用 classdojo_preview_skill_sync，且只能指定一个来源：内置预设、三位数源班级，或完整的内联技能列表。
4. 检查每个目标班级的新增、更新和移除内容。
5. 仅在人类批准后，使用一次性 previewId 和 confirm: true 调用 classdojo_apply_skill_sync。
6. 调用 classdojo_verify_skill_sync 进行独立比对。

技能同步会精确替换内容。如果班级在预览后发生变化，应用操作会停止，而不会覆盖较新的状态。匹配的班级保持不变；如果操作部分失败，重试前必须重新生成预览。

要求

• Node.js 20 或更高版本
• Chrome 或其他支持 Chrome DevTools Protocol（CDP）的 Chromium 浏览器
• 由你本人登录的 ClassDojo 教师账号
• 支持本地 stdio 服务的 MCP 客户端

MCP 服务绝不会索要 ClassDojo 密码、Cookie 或 API 令牌。

启动本地浏览器适配器

使用专用浏览器配置文件，并在该窗口中登录 ClassDojo。

macOS

open -na "Google Chrome" --args \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.classdojo-mcp-chrome"

Linux

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.classdojo-mcp-chrome"

Windows PowerShell

& "$env:ProgramFiles\\Google\\Chrome\\Application\\chrome.exe" \`
  --remote-debugging-port=9222 \`
  --user-data-dir="$env:LOCALAPPDATA\\classdojo-mcp-chrome"

请将调试端口限制在回环地址上。任何能够访问 CDP 端点的人都可能控制该浏览器会话。

在 MCP 客户端中安装

在所有客户端中，使用相同命令从公开 npm 程序包安装：

npx -y classdojo-mcp

贡献者也可以克隆此仓库，运行 npm ci && npm run build，然后将命令替换为 node 和 dist/cli.js 的绝对路径。

Claude Desktop 和 Cursor

{
  "mcpServers": {
    "classdojo": {
      "command": "npx",
      "args": ["-y", "classdojo-mcp"],
      "env": {
        "CLASSDOJO_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

VS Code

{
  "servers": {
    "classdojo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "classdojo-mcp"],
      "env": {
        "CLASSDOJO_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Codex

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.classdojo]
command = "npx"
args = ["-y", "classdojo-mcp"]

[mcp_servers.classdojo.env]
CLASSDOJO_CDP_URL = "http://127.0.0.1:9222"

客户端界面和配置位置会随时间变化；请参阅客户端当前的文档。传输本身采用标准 MCP stdio，并非 Codex 专用。

工具输入示例

先检查工作簿：

{
  "workbookPath": "/absolute/path/to/students.xlsx"
}

使用合成班级映射创建预览：

{
  "workbookPath": "/absolute/path/to/students.xlsx",
  "sheetNames": ["Grade 5"],
  "studentNameFormat": "seat_number_dot_name",
  "includeStudentDetails": false,
  "mappings": [
    {
      "classdojoClassName": "503",
      "sourceClassName": "Grade 5 Class 3"
    }
  ]
}

查看预览后再应用：

{
  "previewId": "00000000-0000-4000-8000-000000000000",
  "confirm": true
}

预览 ID 会在 15 分钟后过期，仅在运行中的 MCP 进程内有效，并会在首次尝试应用时被消耗。这有助于减少意外重放和重复导入。如果某个班级失败，结果会列出已验证的班级，以及生成新预览后可重试的班级。

预览适用于多个目标的内置课堂技能预设：

{
  "rulesSource": {
    "type": "preset",
    "presetId": "traditional_chinese_classroom_v1"
  },
  "targetClassNames": ["502", "503", "504"]
}

使用 {"type":"class","className":"501"} 复制实时源班级。若要修改预设，请发送 {"type":"inline","skills":[...]}，并提供完整的最终列表；每条规则都需要 category、name 和整数 points，iconId 为可选项。正向积分必须在 0..5 范围内，需要改进的积分必须在 -5..0 范围内，名称必须唯一。

隐私与安全

• 工作簿解析和浏览器自动化在教师的电脑本地运行。
• 本项目不运行托管式 MCP 服务，也不会持久保存凭据或学生名册。
• 学生姓名仍可能经由所选的 MCP 客户端／AI 提供商传输。使用真实学生数据前，请先查看该提供商的数据保留和隐私条款。
• 切勿在公开问题中附上真实工作簿、学生截图、浏览器配置文件、Cookie 或包含个人数据的诊断日志。
• 可写操作仅限于已确认的名册导入和已确认的课堂技能同步。积分奖励、考勤、消息、家庭邀请及其他 ClassDojo 功能仍不可用。

请参阅 docs/PRIVACY.md、SECURITY.md 和威胁模型。

故障排除

症状	检查项
浏览器连接失败	确认专用 Chrome 窗口仍在运行，并使用了 --remote-debugging-port=9222。
未登录	在专用窗口中手动登录，然后重新运行 classdojo_doctor。
看不到班级	打开教师班级页面，并确认该账号有访问权限。
导入被阻止	运行 classdojo_get_ui_state；自行关闭家庭邀请或欢迎对话框。
座位号消失	使用 studentNameFormat: "seat_number_dot_name"；仅当使用 name_only 时才会使用批量粘贴。
未检测到工作簿列	提交一个能复现表头布局的合成工作簿，并创建问题。
验证结果不一致	停止写入，比较 missingStudents 和 unexpectedStudents，然后创建新的预览。

项目状态与路线图

版本 0.2.x 仍处于实验阶段。Web UI 适配器经过有意隔离，以便未来可由官方 ClassDojo API 替换，而无需更改公开的 MCP 工具工作流。

计划中的工作：

• 增加合成工作簿布局并扩展区域设置覆盖范围
• MCP 客户端兼容性矩阵和 Inspector 冒烟测试
• 如果 ClassDojo 授予 Early Access，则添加官方 API 适配器
• 仅在完成隐私和权限审查后添加可选的只读工具

本项目不会对未公开的 ClassDojo REST 端点进行逆向工程，也不会承诺将其作为稳定的公共 API。

开发

npm ci
npm test
npm run build
npm audit --omit=dev
npm pack --dry-run

stdio 协议使用 stdout；切勿在服务端添加 console.log 调用。诊断信息请使用 stderr。创建拉取请求前，请参阅 CONTRIBUTING.md。

社区元数据与发布

• MCP Registry 名称：io.github.Eason0in/classdojo-mcp
• npm 包：classdojo-mcp
• 传输方式：stdio
• 许可证：MIT

server.json 和 package.json#mcpName 有意采用与 MCP Registry 所有权格式一致的值。发布工作流已为受保护的 GitHub Actions 环境、npm Trusted Publishing、来源证明和 MCP Registry OIDC 做好准备；只有维护者明确配置 release 环境和 npm 发布者后才能使用。此仓库中不得存放长期有效的 npm 令牌。

许可证

MIT © Eason0in