ClassDojo 花名册 MCP

一个非官方的、本地优先的模型上下文协议（MCP）服务器，专为需要检查 Excel/XLSX 学生花名册、预览更改、将学生导入 ClassDojo 并在之后验证已保存花名册的教师而设计。它可与任何能够启动本地 stdio 服务器的 MCP 客户端配合使用，包括 Claude Desktop、Codex、Cursor 和 VS Code。

[!IMPORTANT] 此社区项目与 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。保存后，服务器会重新读取班级并比较名称和人数。

Related MCP server: excel-mcp-server

它能做什么

工作簿检查器不假定固定的工作表名称或列位置。它会扫描整个工作簿，查找常见的中英文班级/座位/姓名表头。预览和验证随后要求明确选择非空的 sheetNames 以及班级映射，防止代理静默合并重复或不相关的工作表。

安全工作流程

1. 运行 classdojo_doctor。

2. 运行 classdojo_inspect_workbook 并选择预期的工作表和检测到的班级块。

3. 使用明确的 studentNameFormat 运行 classdojo_preview_roster_import。

4. 审查班级映射、人数、缺失的座位号和新增项。

5. 仅在人工批准后，使用返回的 previewId 和 confirm: true 调用 classdojo_apply_roster_import。

6. 运行 classdojo_verify_roster_against_workbook 进行独立的读回检查。

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

要求

• Node.js 20 或更高版本

• Chrome 或其他支持 Chrome DevTools 协议（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 进程中，并且会被第一次应用尝试消耗。这减少了意外重放和重复导入。如果某个班级失败，结果会指出已验证的班级以及生成新预览后可重试的班级。

隐私与安全

• 工作簿解析和浏览器自动化在教师的计算机上本地运行。

• 该项目不运行托管的 MCP 服务，也不持久化凭据或学生花名册。

• 学生姓名仍可能经过所选的 MCP 客户端/AI 提供商。在使用真实学生数据之前，请审查该提供商的保留和隐私条款。

• 切勿将包含个人数据的真实工作簿、学生截图、浏览器配置文件、cookie 或诊断日志附加到公开问题中。

• 在 v0.1.0 中，只有花名册导入是可写的。积分、考勤、消息、家庭邀请和其他 ClassDojo 功能有意保持不可用。

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

故障排除

项目状态与路线图

版本 0.1.x 处于实验阶段。Web 界面适配器有意保持隔离，以便未来官方的 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、provenance 和 MCP Registry OIDC 做好准备；在维护者明确配置 release 环境和 npm 发布者之前，它不可用。此仓库中不应存在长期有效的 npm 令牌。

许可证

MIT © Eason0in