ClassDojo Classroom MCP

ClassDojo 教室 MCP

Excel／XLSX の生徒名簿を調べてインポートしたり、ClassDojo の教室スキルを確認、同期、検証したりする必要がある教師向けの、非公式でローカルファーストな Model Context Protocol（MCP）サーバーです。Claude Desktop、Codex、Cursor、VS Code など、ローカルの stdio サーバーを起動できるあらゆる MCP クライアントで動作します。

重要

このコミュニティプロジェクトは、ClassDojo とは提携、承認、サポート関係にありません。公式の公開 ClassDojo API／MCP がまだ提供されていないため、ローカルのブラウザーアダプターを介して、サインイン済みの ClassDojo 教師用ウェブサイトを使用します。ClassDojo の UI に変更があると、アダプターの更新が必要になる場合があります。

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

この MCP サーバーが作られた理由

ClassDojo の一括貼り付けでは、先頭の数字が生徒の表示名の一部ではなく、リスト番号として解釈されることがあります。このサーバーでは名簿の変更を確認できるようにし、次の 2 つの明示的な形式をサポートしています。

• seat_number_dot_name：1.Student A のような名前を一度に 1 つずつ作成し、座席番号を保持します。
• name_only：座席番号が不要な場合に ClassDojo の高速な一括貼り付けを使用します。元のクラスに重複する名前がある場合は拒否されます。

書き込みにはすべて、有効期間が 15 分の最新のプレビュー ID と confirm: true が必要です。保存後、サーバーはクラスを読み戻し、名前と人数を比較します。

できること

ツール	データを書き込む	目的
classdojo_doctor	いいえ	ローカルのブラウザー接続、ログイン状態、表示可能なクラスを確認します。
classdojo_list_classes	いいえ	教師のセッションに表示される 3 桁のクラスを一覧表示します。
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 とクラスのマッピングが必須です。これにより、エージェントが重複したシートや無関係なシートを暗黙のうちにまとめることを防ぎます。

安全なワークフロー

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 を実行します。

プレビュー	読み戻し検証

すべてのスクリーンショットには合成データのみが含まれています。

安全なクラスルームスキルのワークフロー

組み込みの繁体字中国語プリセットには、9 個の肯定的なスキルと 6 個の要改善スキルが含まれています。これは公開パッケージデータであり、中立的なプリセット ID を使用しています。教師名、アカウント識別子、生徒データは含まれていません。

1. classdojo_configure_skill_rules プロンプトから始めるか、classdojo_get_skills を呼び出して元のクラスを確認します。
2. プリセット全体を確認し、必要に応じて項目の追加や削除、ポイントの変更、アイコンの変更を行います。
3. 元データを 1 つだけ指定して classdojo_preview_skill_sync を呼び出します。元データには、組み込みプリセット、3 桁の元クラス、または完全なインラインスキルリストを指定できます。
4. 各対象の追加、更新、削除をすべて確認します。
5. 人による承認後に限り、1 回限りの 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"

クライアントの UI や設定場所は時間とともに変わります。最新の情報はクライアントのドキュメントを参照してください。トランスポート自体は標準の 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 プロセス内でのみ有効で、最初の適用試行で消費されます。これにより、誤った再実行や重複インポートを減らせます。クラスの処理に失敗した場合、結果には検証済みのクラスと、新しいプレビューの生成後に再試行できるクラスが示されます。

複数の対象に対して、組み込みの classroom-skill プリセットをプレビューします。

{
  "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、診断ログを、公開 issue に添付しないでください。
• 書き込み可能な操作は、確認済みの名簿インポートと確認済みの classroom-skill 同期に限られます。ポイント付与、出欠、メッセージ送信、家族の招待、その他の ClassDojo 機能は引き続き利用できません。

docs/PRIVACY.md、SECURITY.md、脅威モデルをご覧ください。

トラブルシューティング

症状	確認事項
ブラウザーに接続できない	--remote-debugging-port=9222 を指定して専用の Chrome ウィンドウが引き続き実行中であることを確認してください。
ログインしていない	専用ウィンドウで手動でサインインしてから、classdojo_doctor を再実行してください。
クラスが表示されない	教師用クラスページを開き、アカウントにアクセス権があることを確認してください。
インポートがブロックされる	classdojo_get_ui_state を実行し、家族の招待やウェルカムダイアログを手動で閉じてください。
座席番号が消える	studentNameFormat: "seat_number_dot_name" を使用してください。一括貼り付けは name_only の場合にのみ使用されます。
ワークブックの列が検出されない	ヘッダーの配置を再現する合成ワークブックを添えて issue を作成してください。
検証結果が一致しない	書き込みを停止し、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 を使用してください。pull request を作成する前に 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 publisher を明示的に設定するまでは使用できません。このリポジトリに長期間有効な npm トークンを置かないでください。

ライセンス

MIT © Eason0in