ClassDojo Roster MCP

教師がExcel/XLSXの生徒名簿を検査し、変更をプレビューし、ClassDojoに生徒をインポートし、保存後の名簿を検証するための非公式のローカルファーストModel Context Protocol (MCP)サーバーです。Claude Desktop、Codex、Cursor、VS Codeなど、ローカルのstdioサーバーを起動できる任意のMCPクライアントで動作します。

[!IMPORTANT] このコミュニティプロジェクトは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が必要です。保存後、サーバーはクラスを読み戻して名前と数を比較します。

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 DevTools Protocol (CDP) を備えたChromeまたは別の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 and 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プロセス内でのみ有効で、最初の適用試行で消費されます。これにより、誤ったリプレイや重複インポートが減少します。1つのクラスが失敗した場合、結果は検証済みのクラスと、新しいプレビューを生成した後に再試行できるクラスを指定します。

プライバシーとセキュリティ

• ワークブックの解析とブラウザ自動化は教師のコンピュータ上でローカルに実行されます。

• このプロジェクトはホスト型MCPサービスを実行せず、資格情報や生徒名簿を永続化しません。

• 生徒名は選択したMCPクライアント/AIプロバイダーを通過する可能性があります。実際の生徒データを使用する前に、そのプロバイダーの保持期間とプライバシー条件を確認してください。

• 実際のワークブック、生徒のスクリーンショット、ブラウザプロファイル、Cookie、個人データを含む診断ログを公開イシューに添付しないでください。

• v0.1.0で書き込み可能なのは名簿インポートのみです。ポイント、出席、メッセージング、家族招待、その他のClassDojo機能は意図的に利用できません。

docs/PRIVACY.md、SECURITY.md、および脅威モデルを参照してください。

トラブルシューティング

プロジェクトの状態とロードマップ

バージョン 0.1.x は実験的です。Web UIアダプタは意図的に分離されており、将来の公式ClassDojo APIが公開MCPツールのワークフローを変更せずに置き換えることができます。

計画中の作業：

• 追加の合成ワークブックレイアウトとロケールカバレッジ

• MCPクライアント互換性マトリックスとInspectorスモークテスト

• ClassDojoが早期アクセスを許可した場合の公式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レジストリ名: io.github.Eason0in/classdojo-mcp

• npmパッケージ: classdojo-mcp

• トランスポート: stdio

• ライセンス: MIT

server.json と package.json#mcpName は意図的にMCPレジストリの所有権形式に一致しています。リリースワークフローは、保護されたGitHub Actions環境、npm Trusted Publishing、provenance、MCP Registry OIDCのために準備されています。メンテナーが明示的に release 環境とnpmパブリッシャーを設定するまで使用できません。このリポジトリには長期有効なnpmトークンは含まれません。

ライセンス

MIT © Eason0in