# 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` |
| 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` |
| Material / Musterlösung | attachment | `scobees_upload_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` (info, selbstkontrolle, abgabe_optional, abgabe_pflicht) und `arbeitsblatt_markdown`.
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_delete`.

## 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
```
```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.

## Entwicklung

```bash
npm test                    # Konverter- und Sperrlisten-Tests
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 gesetzt – vermutlich durch die Zuweisung an eine Lerngruppe; das ist nicht belegt und für den Server ohne Belang, da die Zuweisung bewusst außerhalb bleibt.

## Lizenz

MIT