ClassDojo Roster MCP

Ein inoffizieller, lokaler Model Context Protocol (MCP)-Server für Lehrkräfte, die Excel/XLSX-Schülerlisten prüfen, Änderungen in der Vorschau ansehen, Schüler in ClassDojo importieren und die gespeicherte Liste anschließend verifizieren möchten. Er funktioniert mit jedem MCP-Client, der einen lokalen stdio-Server starten kann, einschließlich Claude Desktop, Codex, Cursor und VS Code.

[!IMPORTANT] Dieses Community-Projekt ist nicht mit ClassDojo verbunden, wird von ClassDojo nicht unterstützt oder befürwortet. Es verwendet die angemeldete ClassDojo-Lehrkraft-Website über einen lokalen Browser-Adapter, da eine offizielle öffentliche ClassDojo-API/MCP noch nicht verfügbar ist. Änderungen an der ClassDojo-Benutzeroberfläche können ein Update des Adapters erfordern.

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

Warum dieser MCP-Server existiert

ClassDojos Bulk-Paste-Flow kann eine führende Zahl als Listennummer interpretieren, anstatt als Teil des Anzeigenamens eines Schülers. Dieser Server hält Änderungen an der Liste nachvollziehbar und unterstützt zwei explizite Formate:

• seat_number_dot_name: erstellt Namen wie 1.Student A einzeln, sodass die Sitzplatznummer erhalten bleibt.

• name_only: verwendet ClassDojos schnelleren Bulk-Paste-Flow, wenn keine Sitzplatznummern benötigt werden; wird abgelehnt, wenn eine Quellklasse doppelte Namen enthält.

Jeder Schreibvorgang erfordert eine frische 15-Minuten-Vorschau-ID plus confirm: true. Nach dem Speichern liest der Server die Klasse erneut und vergleicht Namen und Anzahl.

Related MCP server: excel-mcp-server

Was er kann

Der Arbeitsmappen-Inspektor geht nicht von festen Blattnamen oder Spaltenpositionen aus. Er durchsucht die gesamte Arbeitsmappe nach gängigen chinesischen und englischen Klassen-/Sitzplatz-/Namensüberschriften. Vorschau und Verifizierung erfordern dann eine explizite, nicht leere sheetNames-Auswahl sowie Klassenmappings, um zu verhindern, dass ein Agent stillschweigend doppelte oder nicht zusammenhängende Blätter kombiniert.

Sicherer Arbeitsablauf

1. Führen Sie classdojo_doctor aus.

2. Führen Sie classdojo_inspect_workbook aus und wählen Sie das gewünschte Blatt und die erkannten Klassenblöcke aus.

3. Führen Sie classdojo_preview_roster_import mit einem expliziten studentNameFormat aus.

4. Überprüfen Sie Klassenmappings, Anzahl, fehlende Sitzplatznummern und Ergänzungen.

5. Nur nach menschlicher Genehmigung rufen Sie classdojo_apply_roster_import mit der zurückgegebenen previewId und confirm: true auf.

6. Führen Sie classdojo_verify_roster_against_workbook für eine unabhängige Rückleseprüfung aus.

Alle Screenshots enthalten nur synthetische Daten.

Anforderungen

• Node.js 20 oder neuer

• Chrome oder ein anderer Chromium-Browser mit Chrome DevTools Protocol (CDP)

• Ein ClassDojo-Lehrkonto, bei dem Sie sich selbst anmelden

• Ein MCP-Client, der lokale stdio-Server unterstützt

Der MCP-Server fragt niemals nach einem ClassDojo-Passwort, Cookie oder API-Token.

Lokalen Browser-Adapter starten

Verwenden Sie ein dediziertes Browserprofil und melden Sie sich in diesem Fenster bei ClassDojo an.

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"

Halten Sie den Debugging-Port auf Loopback. Jeder, der einen CDP-Endpunkt erreichen kann, könnte möglicherweise dessen Browsersitzung steuern.

In einem MCP-Client installieren

Installieren Sie aus dem öffentlichen npm-Paket mit demselben Befehl in jedem Client:

npx -y classdojo-mcp

Mitwirkende können alternativ dieses Repository klonen, npm ci && npm run build ausführen und den Befehl durch node plus den absoluten Pfad zu dist/cli.js ersetzen.

Claude Desktop und 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

Fügen Sie dies zu ~/.codex/config.toml hinzu:

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

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

Client-Benutzeroberfläche und Konfigurationsorte ändern sich im Laufe der Zeit; lesen Sie die aktuelle Dokumentation des Clients. Der Transport selbst ist Standard-MCP-stdio und nicht Codex-spezifisch.

Beispiel-Tool-Eingaben

Untersuchen Sie zuerst eine Arbeitsmappe:

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

Erstellen Sie eine Vorschau mit synthetischen Klassenmappings:

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

Wenden Sie erst nach Überprüfung der Vorschau an:

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

Vorschau-IDs laufen nach 15 Minuten ab, leben nur im laufenden MCP-Prozess und werden durch den ersten Anwendungsversuch verbraucht. Dies reduziert versehentliche Wiederholungen und doppelte Importe. Wenn eine Klasse fehlschlägt, benennt das Ergebnis die verifizierten Klassen und die Klassen, die nach Generierung einer neuen Vorschau erneut versucht werden können.

Datenschutz und Sicherheit

• Arbeitsmappen-Parsing und Browser-Automatisierung laufen lokal auf dem Computer der Lehrkraft.

• Das Projekt betreibt keinen gehosteten MCP-Dienst und speichert keine Anmeldeinformationen oder Schülerlisten.

• Schülernamen können dennoch über den ausgewählten MCP-Client/AI-Anbieter laufen. Überprüfen Sie die Aufbewahrungs- und Datenschutzbedingungen dieses Anbieters, bevor Sie echte Schülerdaten verwenden.

• Hängen Sie niemals echte Arbeitsmappen, Schüler-Screenshots, Browserprofile, Cookies oder Diagnoseprotokolle mit personenbezogenen Daten an ein öffentliches Issue an.

• Nur der Listenimport ist in v0.1.0 schreibbar. Punkte, Anwesenheit, Nachrichten, Familieneinladungen und andere ClassDojo-Funktionen sind absichtlich nicht verfügbar.

Siehe docs/PRIVACY.md, SECURITY.md und das Bedrohungsmodell.

Fehlerbehebung

Projektstatus und Roadmap

Version 0.1.x ist experimentell. Der Web-UI-Adapter ist bewusst isoliert, sodass eine zukünftige offizielle ClassDojo-API ihn ersetzen kann, ohne den öffentlichen MCP-Tool-Workflow zu ändern.

Geplante Arbeiten:

• zusätzliche synthetische Arbeitsmappen-Layouts und Locale-Abdeckung

• MCP-Client-Kompatibilitätsmatrix und Inspector-Smoke-Tests

• offizieller API-Adapter, falls ClassDojo Early Access gewährt

• optionale Nur-Lese-Tools erst nach einer Datenschutz- und Berechtigungsprüfung

Dieses Projekt wird keine undokumentierten ClassDojo-REST-Endpunkte als stabile öffentliche API zurückentwickeln oder versprechen.

Entwicklung

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

Das stdio-Protokoll verwendet stdout; fügen Sie dem Server niemals console.log-Aufrufe hinzu. Verwenden Sie stderr für Diagnosen. Siehe CONTRIBUTING.md, bevor Sie einen Pull-Request öffnen.

Community-Metadaten und Veröffentlichung

• MCP-Registry-Name: io.github.Eason0in/classdojo-mcp

• npm-Paket: classdojo-mcp

• Transport: stdio

• Lizenz: MIT

server.json und package.json#mcpName stimmen absichtlich mit dem MCP-Registry-Besitzformat überein. Der Release-Workflow ist für eine geschützte GitHub-Actions-Umgebung, npm Trusted Publishing, Provenance und MCP-Registry-OIDC vorbereitet; er ist nicht nutzbar, bis der Maintainer explizit die release-Umgebung und den npm-Publisher konfiguriert. Kein langlebiges npm-Token gehört in dieses Repository.

Lizenz

MIT © Eason0in