Skip to main content
Glama
README.md
# scobees-mcp

[![Tests](https://github.com/wvssTobiKi/scobees-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/wvssTobiKi/scobees-mcp/actions/workflows/test.yml)

MCP-Server, der Claude mit der scobees-Lehrkräfte-App (teach.scobees.com) verbindet. Damit lassen sich aus Offline-Unterlagen, Arbeitsblättern und Ideen **Lernpfade in scobees anlegen und bestehende erweitern** – inklusive interaktiver Arbeitsblätter (Serlo-Editor) mit Quizfragen.

Erster Aufschlag der Werner-von-Siemens-Schule Hildesheim, orientiert am [Moodle-MCP](https://github.com/jtuttas/MoodleMcp) von Dr. Jörg Tuttas (MMBbS).

## Grundsätze

- **Keine Schülerdaten.** Der Server ruft ausschließlich Inhaltsfunktionen auf. Alle Pfade mit Schüler-, Klassen-, Lernstands-, Bewertungs- oder Personendaten stehen auf einer festen Sperrliste (`src/api.js`) und werden nicht aufgerufen – auch nicht auf Wunsch. Personennamen in Antworten werden auf IDs reduziert.
- **Verwaltung bleibt beim Admin.** Lernbereiche und Fächer werden nur gelesen; die Lehrkraft wählt das Fach, in dem ein Lernpfad entsteht.
- **Keine Schüler sehen etwas ohne Lehrkraft-Handlung.** Neue Lernpfade liegen nur in der schuleigenen Bib. Die Zuweisung an Lerngruppen ist Schülerverwaltung und erfolgt ausschließlich in der Weboberfläche.
- **Inoffizielle Schnittstelle.** scobees hat keine öffentliche API. Der Server nutzt dieselben Aufrufe wie die Weboberfläche (dokumentiert in [`docs/scobees-api-map.md`](docs/scobees-api-map.md)). Bei Änderungen an scobees muss nachgezogen werden – deshalb liegt das Projekt in Git.

## Begriffe

| scobees-Oberfläche | API | Werkzeug |
|---|---|---|
| Lernbereich (Kachel in der Bib) | workspace `LB-…` | `scobees_list_workspaces` |
| Fach / Kurs | subject `SUBJ-…` | `scobees_list_subjects` |
| Lernpfad | Wurzel-Lerninput `LI-…` | `scobees_create_lernpfad`, `scobees_update_lernpfad`, `scobees_get_lernpfad` |
| Gliederungsstruktur | folder | `scobees_create_gliederung`, `scobees_update_gliederung` |
| Kachelbild (Lernpfad, Gliederung, Wahlpflicht, Aufgabe) | `coverImage` | Parameter `cover_image_path` der jeweiligen create/update-Werkzeuge |
| Aufgabe (Pflicht/Wahl) | task | `scobees_create_aufgabe`, `scobees_update_aufgabe` |
| Wahlpflichtaufgabe | choice (Container) | `scobees_create_wahlpflicht`, `scobees_update_wahlpflicht` |
| Interaktives Arbeitsblatt | Serlo-Dokument in `taskDescription` | Markdown → `src/serlo.js`; gezielte Änderung: `scobees_patch_arbeitsblatt` |
| Material / Musterlösung | attachment | `scobees_upload_material`, `scobees_delete_material` |
| Bild im Arbeitsblatt | Serlo-Medienspeicher (editor.serlo.org) | `scobees_upload_bild` → `![…](url)` |

## Installation (Claude Desktop)

1. Node.js ≥ 18 installieren.
2. `scobees-mcp-vX.Y.Z.mcpb` von der [Releases-Seite](https://github.com/wvssTobiKi/scobees-mcp/releases) laden (oder selbst bauen: `npm run pack`).
3. Datei in Claude Desktop per Doppelklick installieren (Einstellungen → Erweiterungen) und scobees-Benutzername/Passwort eintragen. Die Zugangsdaten speichert Claude Desktop verschlüsselt; der Server nutzt sie nur für die Anmeldung bei `auth.scobees.com` und legt danach Tokens unter `~/.scobees-mcp/tokens.json` ab.

Manuell (Claude Code / andere Clients): Umgebungsvariablen `SCOBEES_USERNAME`, `SCOBEES_PASSWORD` setzen und `node src/server.js` als stdio-Server eintragen. Anmeldung testen mit `node src/server.js --login`.

> Hinweis: Konten, die sich nur per Microsoft 365 oder Eduplaces anmelden, werden derzeit nicht unterstützt (kein Passwort-Login bei Keycloak). Übergangsweise kann `SCOBEES_REFRESH_TOKEN` gesetzt werden.

## Typischer Ablauf

1. `scobees_list_subjects` → Fach wählen.
2. `scobees_create_lernpfad` (Name, Beschreibung, Jahrgang, Titelbild).
3. Je Phase `scobees_create_gliederung`.
4. Je Aufgabe `scobees_create_aufgabe` mit `art` (Abgabeform, s. u.), `aufgabentyp` (pflicht, extra, training, info) und `arbeitsblatt_markdown`. Hinweise für gute Lernpfade: [`docs/skill-notizen.md`](docs/skill-notizen.md).
5. Dateien mit `scobees_upload_material` anhängen (PDF, HTML-Simulationen, interaktive Seiten, GeoGebra-Dateien). Bilder, die *im* Arbeitsblatt erscheinen sollen, vorher mit `scobees_upload_bild` hochladen und die URL per `![…](url)` einbinden.
6. Ergebnis in scobees prüfen, Reihenfolge ggf. mit `scobees_move` anpassen, dann in der Weboberfläche einer Lerngruppe zuweisen.

Bestehende Kurse: `scobees_list_lernpfade` → `scobees_get_lernpfad` (Baum mit IDs) → `scobees_get_aufgabe` (Arbeitsblatt als Markdown) → `scobees_update_aufgabe` / `scobees_update_gliederung` / `scobees_move` / `scobees_copy_aufgabe` / `scobees_delete`.

## Abgabeformen (`art`) – scobees-Denke

| `art` | Lernende … | scobees-Felder |
|---|---|---|
| `info` | lesen/erkunden, schließen die Aufgabe ab | kind `task`, keine Abgabe |
| `selbstkontrolle` (Standard) | bearbeiten das Serlo-Arbeitsblatt, das Quiz prüft sich selbst | kind `task`, keine Abgabe |
| `abgabe_optional` | geben ein Ergebnis ab (`abgabeformen`: file, pen, link) | `task+upload-optional`, requiredSubmissions |
| `abgabe_pflicht` | müssen abgeben, sonst gilt die Aufgabe nicht als erledigt | `task+upload-required` |
| `abgabe_selbstkorrektur` | geben ab (optional) und vergleichen danach mit der Musterlösung | `task+upload-optional+sc`, Musterlösung per `scobees_upload_material als_musterloesung` |
| `abgabe_pflicht_selbstkorrektur` | müssen abgeben und vergleichen dann mit der Musterlösung | `task+upload-required+sc` |

„Selbstkorrektur“ ist in scobees ein eigener Schritt *nach* der Abgabe (Reiter „Selbstkorrektur“ in der Schüler-App) und hat nichts mit den sich selbst prüfenden Serlo-Quizzen zu tun. Steht in `requiredSubmissions` etwas, verlangt scobees die Abgabe zwingend („Zum Abgeben musst du eine Datei hochladen“).

## Differenzierungen (scobees-Denke)

Die Schule definiert Niveaus (bei der WvSS: Hauptschulabschluss, Realschulabschluss, Erweiterter Realschulabschluss). **Aufgaben** tragen ein oder mehrere Niveaus; Lernende sind einem Niveau zugeordnet und sehen nur Aufgaben mit ihrem Niveau. Der **Lernpfad** hat kein eigenes Niveau – was die Oberfläche dort anzeigt, ist die Zusammenfassung der enthaltenen Aufgaben. `scobees_create_aufgabe` setzt ohne Angabe **alle** Niveaus der Schule (Aufgabe für alle sichtbar); wer differenzieren will, gibt `differenzierungen` gezielt an. Die Weboberfläche verlangt beim Speichern mindestens ein Niveau.

## Markdown für Arbeitsblätter

```markdown
# Überschrift
Absatz mit **fett**, *kursiv*, `code`, [Link](https://…) und $U = R \cdot I$.

- Aufzählung          1. nummeriert
| Kopf | Kopf |        (Tabellen mit Trennzeile)
> Hinweis-Box          ![Bild](https://…)
https://www.geogebra.org/m/…   (Zeile nur mit URL → GeoGebra-Applet; YouTube/mp4 → Video)

:::spoiler Lösung
…
:::
:::box warning Achtung
…
:::

```cpp
void loop() {}
```

```quiz-sc            (quiz-mc für Mehrfachauswahl)
Frage?
- [x] richtig :: Feedback
- [ ] falsch
```
```quiz-input
Wie viel ist 6 · 7?
unit: Stück
= 42          (oder „= 42 V“ – Einheit wird abgetrennt)
≠ 41 :: Typischer Fehler mit Hinweis
```
```quiz-blanks        (quiz-blanks-dnd für Drag & Drop, Distraktoren mit „+ …“)
Strom wird in [[Ampere|A]] gemessen.
```
```quiz-text
Freitextaufgabe
```
```math               (Gleichungskette, LaTeX; Text nach „|“ erklärt den Schritt ZUR NÄCHSTEN Zeile)
| Ohmsches Gesetz anwenden
U = R \cdot I | nach I umstellen
I = \frac{U}{R} | Werte einsetzen
= 3\,\mathrm{A}
```
```

Alles, was Markdown nicht abbildet (Bild-Zuordnung, Gleichungen, interaktives Video …), kann als fertiges Serlo-JSON über `serlo_json` übergeben werden – Vorlage: [`docs/serlo-beispiel.json`](docs/serlo-beispiel.json). `scobees_markdown_vorschau` zeigt das Ergebnis, ohne zu speichern.

## Skill „Lernpfad mit scobees aufbauen“

Der Server stellt Werkzeuge bereit; **wie** daraus eine gute Lernsituation wird (Szenario, Gliederung, Aufgabenarten, Grobplan zur Freigabe, Zeiten, Abschlussbericht), steht im Skill [`skills/scobees-lernpfad`](skills/scobees-lernpfad/SKILL.md). Er deckt drei Einstiege ab: neu aus Thema und Bildungsgang, aus Offline-Unterlagen, Überarbeitung eines bestehenden Pfads – für BFS-dual, Fachschule Technik, Berufliches Gymnasium Technik, Fachoberschule Technik und Berufseinstiegsschule in Niedersachsen. Installation: ZIP aus dem Release herunterladen und in Claude Desktop unter *Skills* hochladen (oder den Ordner direkt verwenden). Der Skill ist auf die Server-Version abgestimmt, mit der er veröffentlicht wird.

## Kompatibilität

Der Server bildet eine inoffizielle Schnittstelle nach. Welche scobees-Version mit welcher Server-Version geprüft wurde, steht in der Tabelle „Kompatibilität“ in [CHANGELOG.md](CHANGELOG.md). `scobees_me` zeigt die aktuell laufende scobees-Version und warnt, wenn sie von der geprüften abweicht. Dann prüft `npm run test:live -- <Fach-ID>` in wenigen Minuten alle Werkzeuge gegen die neue Version (nur Inhalte in einem Test-Lernpfad, keine Schüler- oder Personendaten); bei Problemen ein Issue „scobees-Änderung“ anlegen.

## Wenn ein Werkzeug fehlschlägt

Die Fehlermeldung zeigt immer den Antworttext des fehlgeschlagenen Aufrufs, nicht nur den Statuscode. `SCOBEES_DEBUG=1` zeigt zusätzlich URL und Antwort-Header (Tokens/Signaturen maskiert). Für `scobees_upload_bild` gibt es außerdem `node scripts/diagnose-serlo-upload.js`, das die drei Schritte des Bild-Uploads einzeln prüft und sagt, wo es hakt – auch ohne scobees-Anmeldung lauffähig (ein Beispiel für so gefundene Ursache: Abschnitt 0.1.5 in [CHANGELOG.md](CHANGELOG.md)). Ein HTTP-402-Fehler bei diesem Werkzeug kommt in aller Regel nicht von scobees oder diesem Server, sondern vom externen Medienspeicher des Serlo-Editors; Fallback ist `scobees_upload_material` (Bild als gewöhnlicher Anhang statt im Arbeitsblatt).

## Entwicklung

```bash
npm test                    # Konverter- und Sperrlisten-Tests (ohne Netz)
npm run test:live -- SUBJ-… # Funktionstest aller Werkzeuge gegen das echte scobees (legt einen Test-Lernpfad an und löscht ihn wieder)
node src/server.js --tools  # Werkzeugliste
node src/server.js --login  # Anmeldung prüfen
npm run pack                # scobees-mcp.mcpb bauen
```

Erweitern, reparieren, Mitschneiden: siehe [CONTRIBUTING.md](CONTRIBUTING.md). Fehler nach scobees-Änderungen bitte als Issue mit der Vorlage „scobees-Änderung“ melden.

Testumgebung in scobees (WvSS): Lernbereich „testbereich“ `LB-9QX4VN79SPUN59XTXC`, Lernpfad „TEST MCP“ `LI-M1SUFLY8QBQBD65MHU`.

Status der Aufrufe: alles in `docs/scobees-api-map.md` mit „Mitschrift“ ist beobachtet. Am 27.10.2026 live geprüft: Anmeldung, Lesen, Gliederung/Aufgabe/Wahlpflicht anlegen, Aufgabe und Gliederung ändern, Material-Upload, Verschieben, Löschen. Nachtrag (2. Mitschnitt): Lernpfad-Wurzel und Wahlpflichtaufgabe ändern sowie Bild-Upload ins Arbeitsblatt ebenfalls live geprüft. Statusmodell: DRAFT = nicht in der Bib, INACTIVE = in der Bib (beides live geprüft über `in_bib`). ACTIVE wird vom Backend an der Wurzel gesetzt, sobald der Lernpfad einer Lerngruppe zugewiesen ist (am 12.11.2026 mit einem Dummy-Konto belegt). Die Zuweisung selbst bleibt bewusst außerhalb des Servers; er erkennt sie aber und warnt bei jedem Schreibzugriff auf einen zugewiesenen Lernpfad, weil Änderungen dann sofort bei den Lernenden ankommen.

## Lizenz

MIT

TDQS

A3.8/5.0

Scored across 23 tools

Disambiguation4/5

Each tool targets a distinct resource+action (Lernpfad, Gliederung, Wahlpflicht, Aufgabe, Material, Bild), and the descriptions explicitly disambiguate the tricky pairs (update_aufgabe vs. patch_arbeitsblatt, create_aufgabe vs. copy_aufgabe vs. move). Boundaries between move and the update tools, or between create_aufgabe/direct-in-Lernpfad and create_gliederung, take a careful read but are resolvable from the descriptions.

Naming Consistency4/5

All tools share the scobees_ prefix and a snake_case verb_noun pattern (list_lernpfade, get_aufgabe, create_gliederung, upload_material, delete_material). A few tools drop the noun and use bare generic verbs (me, move, delete, markdown_vorschau), and noun language mixes German and English, which is a minor inconsistency but still readable.

Tool Count4/5

23 tools is on the high side, but the domain (course authoring with four hierarchical entity types plus assets and metadata lookups) justifies most of them, since each resource gets its own create/update/delete coverage. A few generic tools (delete, move) consolidate what would otherwise be more tools, so the set is reasonably scoped.

Completeness4/5

The lifecycle is largely covered: create/update/delete for Lernpfad, Gliederung, Wahlpflicht and Aufgabe, plus copy, move, material upload/delete and read helpers (get_lernpfad returns the full tree). Minor gaps exist — there is no standalone get_wahlpflicht or get_gliederung detail read, no search, and Wahlpflicht copying/assignment is only handled via documented workarounds or the web UI.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues