# @udondan/anton
[](https://www.npmjs.com/package/@udondan/anton)
[](https://www.npmjs.com/package/@udondan/anton)
[](https://github.com/udondan/anton/actions/workflows/test.yml)
[](https://codecov.io/gh/udondan/anton)
[][qlty]
[](LICENSE)
> [!NOTE]
> Inoffizielles Community-Projekt. Nicht mit der solocode GmbH (Anbieter von ANTON) verbunden, nicht von ihr unterstützt oder autorisiert.
Node.js-Paket zur Überwachung des Lernfortschritts von Kindern auf [anton.app](https://anton.app). Es kapselt die inoffizielle anton.app-API und bietet drei Schnittstellen über einen gemeinsamen Kern:
- **SDK** — importierbare `Anton`-Klasse für Node.js-Projekte
- **CLI** — `anton`-Befehl für das Terminal
- **MCP-Server** — `anton mcp` stellt alle Funktionen als Tools für KI-Assistenten bereit
Zusätzlich gibt es einen [Agent Skill](#agent-skill-für-ki-assistenten), der KI-Assistenten die Bedienung der CLI beibringt.
> [!IMPORTANT]
> Dieses Paket dient ausschließlich dazu, den Lernfortschritt von Kindern zu verfolgen und Lektionen zu planen — als Unterstützung für Eltern und Erziehungsberechtigte. Es kann **nicht** dazu genutzt werden, beim Lernen zu schummeln oder Lektionen automatisiert abzuschließen. Das Paket stellt dafür keine Funktionen bereit!
> [!WARNING]
> Dieses Paket nutzt eine inoffizielle, durch Reverse Engineering ermittelte API. Endpunkte können sich jederzeit ohne Vorankündigung ändern.
## Inhalt
- [Installation](#installation)
- [Konfiguration](#konfiguration)
- [Config-Datei (empfohlen)](#config-datei-empfohlen)
- [Umgebungsvariablen](#umgebungsvariablen)
- [SDK](#sdk)
- [Installation](#installation-1)
- [Schnellstart](#schnellstart)
- [API-Referenz](#api-referenz)
- [Authentifizierung](#authentifizierung)
- [Status & Gruppe](#status--gruppe)
- [Lektionen zuweisen](#lektionen-zuweisen)
- [Fortschritt & Ereignisse](#fortschritt--ereignisse)
- [Analysen](#analysen)
- [Lernkatalog](#lernkatalog)
- [Lokale Aufgaben](#lokale-aufgaben)
- [CLI](#cli)
- [Einstieg](#einstieg)
- [Befehle](#befehle)
- [Statusbefehle](#statusbefehle)
- [Kursbefehle](#kursbefehle)
- [Zuweisungsbefehle](#zuweisungsbefehle)
- [Fortschritt & Analysen](#fortschritt--analysen)
- [Aufgabenverwaltung](#aufgabenverwaltung)
- [Globale Optionen](#globale-optionen)
- [Agent Skill für KI-Assistenten](#agent-skill-für-ki-assistenten)
- [Skill installieren](#skill-installieren)
- [Skill verwenden](#skill-verwenden)
- [MCP-Server](#mcp-server)
- [Einrichtung in Claude Code](#einrichtung-in-claude-code)
- [Einrichtung in Claude Desktop](#einrichtung-in-claude-desktop)
- [Anwendungsbeispiele mit Claude](#anwendungsbeispiele-mit-claude)
- [Verfügbare MCP-Tools](#verfügbare-mcp-tools)
- [Lizenz](#lizenz)
- [Disclaimer](#disclaimer)
## Installation
```bash
# Globale Installation (empfohlen für CLI-Nutzung)
npm install -g @udondan/anton
# Ohne Installation direkt nutzen
ANTON_LOGIN_CODE=DEIN-CODE npx @udondan/anton status
```
## Konfiguration
### Config-Datei (empfohlen)
Credentials können dauerhaft in `~/.config/anton/config` gespeichert werden. Die Datei darf nicht für Gruppe oder andere lesbar sein (z.B. `0600`) – auf POSIX-Systemen wird die Datei mit einer Warnung ignoriert, wenn Gruppe- oder andere-Bits gesetzt sind (`chmod 0600 ~/.config/anton/config`):
```bash
# ~/.config/anton/config
ANTON_LOGIN_CODE=DEIN-CODE
ANTON_GROUP=Family
```
Die Datei enthält `KEY=VALUE`-Zeilen. Zeilen, die mit `#` beginnen, werden als Kommentar ignoriert. Umgebungsvariablen haben Vorrang vor der Config-Datei.
```bash
# Datei anlegen und absichern
touch ~/.config/anton/config
chmod 0600 ~/.config/anton/config
```
### Umgebungsvariablen
| Variable | Erforderlich | Beschreibung |
| ------------------------ | ------------------------ | --------------------------------------------------------------------------- |
| `ANTON_LOGIN_CODE` | Ja (oder `ANTON_LOG_ID`) | Der 8-stellige Eltern-Login-Code aus der Anton-App |
| `ANTON_LOG_ID` | Alternative zu obigem | Interne Log-ID (z. B. `L-...`) |
| `ANTON_GROUP` | Nein | Wählt die Standardgruppe bei mehreren Gruppen (Groß-/Kleinschreibung egal) |
| `ANTON_ASSIGNMENTS_FILE` | Nein | Pfad zur Aufgaben-JSON-Datei (Standard: `~/.config/anton/assignments.json`) |
| `ANTON_NO_SESSION_CACHE` | Nein | Auf `1` setzen, um den CLI-Session-Cache zu deaktivieren |
---
## SDK
### Installation
```bash
npm install @udondan/anton
```
### Schnellstart
```ts
import { Anton } from '@udondan/anton';
const anton = new Anton({ loginCode: 'DEIN-CODE' });
await anton.connect();
// Authentifizierungs- und Gruppenübersicht
console.log(anton.getStatus());
// Wochenzusammenfassung für ein Kind
console.log(await anton.getWeeklySummary({ childName: 'Emma' }));
```
### API-Referenz
#### Authentifizierung
```ts
const anton = new Anton({ loginCode: 'ABCD-1234' });
// oder
const anton = new Anton({ logId: 'L-...' });
await anton.connect(); // muss vor allen anderen Methoden aufgerufen werden
```
#### Status & Gruppe
```ts
// Authentifizierungsstatus + Gruppenübersicht (kein Netzwerkaufruf)
anton.getStatus();
// Familienmitglieder + aktuell zugewiesene Blöcke
await anton.getGroup();
// Lernende auflisten
anton.listChildren();
```
#### Lektionen zuweisen
```ts
// Block per Kurs + Thema + Block zuweisen (wird intern aufgelöst)
await anton.pinBlock({
project: 'c-mat-4',
topicIndex: 6, // 0-basiert, aus listTopics()
blockIndex: 1, // 0-basiert innerhalb des Themas
weekStartAt: '2025-09-01', // Montag; Standard: aktuelle Woche
childName: 'Emma', // weglassen = gesamte Gruppe
});
// Oder Block direkt über PUID angeben
await anton.pinBlock({
blockPuid: 'c-mat-4/ro9ajj',
blockPath: '/../c-mat-4/topic-07-brueche/block-02-brueche-zuordnen/block',
weekStartAt: '2025-09-01',
});
// Zuweisung entfernen
await anton.unpinBlock({
blockPuid: 'c-mat-4/ro9ajj',
weekStartAt: '2025-09-01',
});
// Aktuelle Gruppenzuweisungen abrufen
await anton.getGroupAssignments({ week: '2025-09-01', childPublicId: 'P-...' });
```
#### Fortschritt & Ereignisse
```ts
// Fortschrittsübersicht (abgeschlossene Level + Sterne)
await anton.getProgress({ childName: 'Emma', since: '2025-01-01' });
// Rohes Ereignisprotokoll
await anton.getEvents({
childName: 'Emma',
eventType: 'finishLevel',
limit: 50,
});
// Performance pro Level (reviewReport-API)
await anton.getLevelProgress({
levelPuid: 'c-mat-4/abc123',
childName: 'Emma',
});
```
#### Analysen
```ts
// Wochenrückblick: Level, Zeit, Sterne, zugewiesen vs. selbstgewählt
await anton.getWeeklySummary({ childName: 'Emma', weekStartAt: '2025-09-01' });
// Pro Fach: Trefferquote, Sterne, Zeit, Trend
await anton.getSubjectSummary({ childName: 'Emma', subject: 'mat' });
// Aktive Tage, Lernsträhnen, Lücken
await anton.getActivityTimeline({ childName: 'Emma', since: '2025-01-01' });
// Welche zugewiesenen Blöcke hat das Kind abgeschlossen?
await anton.checkAssignmentCompletion({
childName: 'Emma',
week: '2025-09-01',
});
// Alle Kinder im Vergleich
await anton.compareChildren();
```
#### Lernkatalog
```ts
// ~285 Kurse durchsuchen
await anton.listPlans({ subject: 'mat', grade: 4, language: 'de' });
// Themen eines Kurses (leichtgewichtig — vor getTopicBlocks verwenden)
await anton.listTopics({ project: 'c-mat-4' });
// Blöcke + Level eines einzelnen Themas
await anton.getTopicBlocks({ project: 'c-mat-4', topicIndex: 6 });
// oder per Titel:
await anton.getTopicBlocks({ project: 'c-mat-4', topicTitle: 'Brüche' });
// Vollständige Hierarchie Thema→Block→Level (groß — lieber listTopics + getTopicBlocks)
await anton.getPlan({ project: 'c-mat-4' });
// Lektionsinhalt (Aufgaben, Trainer)
await anton.getLesson({ fileId: 'level/c-mat-4/...' });
```
#### Lokale Aufgaben
Lokale Aufgaben werden in einer JSON-Datei gespeichert und sind unabhängig von der anton.app-API — nützlich für eigene Notizen und Tracking.
```ts
// Erstellen
const a = anton.assignLesson({
childName: 'Emma',
fileId: 'level/...',
lessonTitle: 'Brüche 1',
});
// Auflisten
anton.listAssignments({ childName: 'Emma', status: 'pending' });
// Aktualisieren
anton.updateAssignment(a.id, {
status: 'completed',
note: 'Auf Anhieb geschafft!',
});
// Löschen
anton.deleteAssignment(a.id);
```
---
## CLI
> [!TIP]
> **Agent Skill verfügbar:** Mit dem [Agent Skill](#agent-skill-für-ki-assistenten) kennen KI-Assistenten alle Befehle, Flags und den vollständigen Planungsprozess und können direkt `anton`-Befehle ausführen.
### Einstieg
```bash
export ANTON_LOGIN_CODE='DEIN-CODE'
anton status
```
### Befehle
#### Statusbefehle
```bash
anton status # Authentifizierungsinfo + Gruppenübersicht
anton group # Familiengruppe + aktuell zugewiesene Blöcke
anton children # Kinder auflisten
```
#### Kursbefehle
```bash
anton plans # alle ~285 Kurse
anton plans --subject mat --grade 4 # gefiltert nach Fach und Klasse
anton topics c-mat-4 # Themen eines Kurses
anton blocks c-mat-4 --topic-index 6 # Blöcke eines Themas (per Index)
anton blocks c-mat-4 --topic-title Brüche # Blöcke eines Themas (per Titel)
anton plan c-mat-4 # vollständige Hierarchie (große Ausgabe)
anton lesson level/c-mat-4/... # Lektionsinhalt
```
#### Zuweisungsbefehle
```bash
# Zuweisung per Thema-/Block-Index
anton pin c-mat-4 --topic-index 6 --block-index 1 --child Emma --week 2025-09-01
# Zuweisung per Titelsuche
anton pin c-mat-4 --topic-title Brüche --block-title "zuordnen" --child Emma
# Aktuelle Gruppenzuweisungen anzeigen
anton pins
anton pins --week 2025-09-01 --child Emma
# Zuweisung entfernen
anton unpin c-mat-4/ro9ajj 2025-09-01
```
#### Fortschritt & Analysen
```bash
anton progress Emma # alle abgeschlossenen Level + Sterne
anton events Emma --type finishLevel -n 20 # rohes Ereignisprotokoll
anton level-progress c-mat-4/abc123 Emma # Performance pro Level
anton weekly Emma # Zusammenfassung der aktuellen Woche
anton weekly Emma --week 2025-09-01
anton subjects Emma # Trefferquote + Trend pro Fach
anton subjects Emma --subject mat
anton timeline Emma # Lernsträhnen, aktive Tage, Lücken
anton timeline Emma --since 2025-01-01
anton completion Emma # Abschlussstatus zugewiesener Blöcke
anton compare # alle Kinder im Vergleich
```
#### Aufgabenverwaltung
```bash
anton assign Emma level/c-mat-4/... --title "Brüche 1"
anton assignments --child Emma --status pending
anton update-assignment <id> --status completed
anton delete-assignment <id>
```
#### Globale Optionen
```bash
anton --no-cache <befehl> # Session-Cache überspringen, immer neu anmelden
```
### Agent Skill für KI-Assistenten
Ein Skill, der KI-Assistenten beibringt, wie man alle `anton`-CLI-Befehle korrekt verwendet — inklusive Authentifizierung, Befehlssyntax, ID-Ermittlung und wöchentlicher Lernplanung pro Kind.
#### Skill installieren
```bash
npx skills add udondan/anton
```
Oder global für alle Projekte:
```bash
npx skills add udondan/anton -g
```
#### Skill verwenden
Sobald der Skill installiert ist, verstehen KI-Assistenten Anfragen wie:
- „Wie hat sich Emma diese Woche in Mathe geschlagen?"
- „Weise Emma und Jonas für nächste Woche passende Lektionen zu."
- „Ich bekomme einen 401-Fehler bei `anton progress` — wie behebe ich das?"
Der Assistent wählt automatisch die richtigen `anton`-Befehle, kennt alle Flags und führt bei Bedarf durch den vollständigen Planungsprozess.
---
## MCP-Server
Der MCP-Server stellt alle 24 Tools über stdio bereit und ermöglicht KI-Assistenten wie Claude, den Lernfortschritt der Kinder zu analysieren und Lektionen automatisch zuzuweisen.
> [!TIP]
> **Alternative ohne MCP:** KI-Assistenten mit Terminalzugriff können direkt die CLI nutzen. Der [Agent Skill](#agent-skill-für-ki-assistenten) bringt ihnen die Befehle bei.
### Einrichtung in Claude Code
**Mit globaler Installation:**
```bash
claude mcp add --env ANTON_LOGIN_CODE=DEIN-CODE anton -- anton mcp
```
**Ohne Installation, direkt über npx:**
```bash
claude mcp add --env ANTON_LOGIN_CODE=DEIN-CODE anton -- npx @udondan/anton mcp
```
Für eine projektweite Konfiguration (`.claude/settings.json`):
```bash
claude mcp add --scope project --env ANTON_LOGIN_CODE=DEIN-CODE anton -- npx @udondan/anton mcp
```
### Einrichtung in Claude Desktop
**Mit globaler Installation** — in `claude_desktop_config.json`:
```json
{
"mcpServers": {
"anton": {
"command": "anton",
"args": ["mcp"],
"env": {
"ANTON_LOGIN_CODE": "DEIN-CODE"
}
}
}
}
```
**Ohne Installation, direkt über npx:**
```json
{
"mcpServers": {
"anton": {
"command": "npx",
"args": ["@udondan/anton", "mcp"],
"env": {
"ANTON_LOGIN_CODE": "DEIN-CODE"
}
}
}
}
```
### Anwendungsbeispiele mit Claude
Sobald der MCP-Server eingerichtet ist, kann Claude automatisch auf alle Daten zugreifen und komplexe Aufgaben übernehmen. Hier sind einige Beispiele für Prompts:
---
**Fortschrittsanalyse:**
> „Wie hat sich Emma diese Woche beim Lernen geschlagen? Welche Fächer laufen gut, wo gibt es Schwächen?"
Claude ruft dabei `get_weekly_summary`, `get_subject_summary` und `get_activity_timeline` ab und liefert eine zusammenhängende Auswertung — Lernzeit, Trefferquoten, Lernsträhnen und Fächer mit Verbesserungs- oder Nachholbedarf.
---
**Automatische Lektionszuweisung basierend auf Lernhistorie:**
> „Schau dir an, was Emma in Mathematik diese Woche gemacht hat, und weise ihr für nächste Woche die nächsten passenden Lektionen zu."
Claude analysiert dafür:
1. `get_weekly_summary` — was wurde diese Woche bearbeitet
2. `get_subject_summary` — Stärken und Schwächen pro Fach
3. `check_assignment_completion` — wurden die zugewiesenen Blöcke abgeschlossen
4. `list_topics` + `get_topic_blocks` — welche Blöcke kommen als nächstes im Kurs
5. `pin_block` — die nächsten passenden Blöcke direkt zuweisen
---
**Alle Kinder auf einmal versorgen:**
> „Vergleiche alle Kinder und weise jedem für nächste Woche zwei Lektionen zu, die zu seinem aktuellen Stand passen — bei Schwächen Wiederholungsstoff, sonst das nächste Thema."
Claude nutzt `compare_children` für den Überblick, analysiert pro Kind die Fachtrends aus `get_subject_summary` und die Lernhistorie aus `get_events`, sucht dann in `list_topics` + `get_topic_blocks` passende Folgeblöcke oder Wiederholungseinheiten heraus und weist sie per `pin_block` zu.
---
**Lernrückstand erkennen:**
> „Hat Emma in letzter Zeit Lernlücken? Wann hat sie zuletzt Mathematik gemacht und gibt es Themen, bei denen sie viele Fehler hatte?"
Claude kombiniert `get_activity_timeline` (Lücken und Strähnen), `get_subject_summary` (Fachtrend) und `get_events` (Fehlerrate pro Lektion), um gezielte Hinweise zu geben.
---
**Wöchentlichen Lernplan erstellen:**
> „Erstelle für Emma und Jonas je einen Lernplan für die nächsten zwei Wochen — abgestimmt auf ihre bisherigen Fortschritte und offenen Lektionen."
Claude liest für jedes Kind den bisherigen Verlauf, prüft mit `check_assignment_completion` offene Aufgaben, sucht mit `list_topics` die nächsten Lernschritte und weist sie wochenweise per `pin_block` zu.
---
### Verfügbare MCP-Tools
| Tool | Beschreibung |
| ----------------------------- | ----------------------------------------------------------- |
| `get_status` | Authentifizierungsstatus, Gruppeninfo, konfigurierte Kinder |
| `list_groups` | Alle Gruppen, denen der Elternteil angehört |
| `get_group` | Familienmitglieder + aktuell zugewiesene Blöcke |
| `get_group_assignments` | Zugewiesene Blöcke, filterbar nach Kind/Woche |
| `pin_block` | Lektionsblock der Gruppe oder einem Kind zuweisen |
| `unpin_block` | Zuweisung entfernen |
| `list_children` | Kinder auflisten |
| `get_progress` | Abgeschlossene Level + Sterne für ein Kind |
| `get_events` | Rohes Ereignisprotokoll für ein Kind |
| `get_level_progress` | Performance pro Level (reviewReport-API) |
| `check_assignment_completion` | Welche zugewiesenen Blöcke hat ein Kind abgeschlossen |
| `get_weekly_summary` | Wochenrückblick: Level, Zeit, Sterne |
| `get_subject_summary` | Pro Fach: Trefferquote, Sterne, Zeit, Trend |
| `get_activity_timeline` | Aktive Tage, Lernsträhnen, Lücken |
| `compare_children` | Alle Kinder im Vergleich |
| `list_plans` | ~285 Kurse nach Fach/Klasse durchsuchen |
| `list_topics` | Thementitel + Indizes für einen Kurs |
| `get_topic_blocks` | Blöcke + Level für ein einzelnes Thema |
| `get_plan` | Vollständige Hierarchie Thema→Block→Level |
| `get_lesson` | Lektionsinhalt (Aufgaben, Trainer) per fileId |
| `list_assignments` | Lokale Aufgabenliste |
| `assign_lesson` | Lokale Aufgabe erstellen |
| `update_assignment` | Lokale Aufgabe aktualisieren |
| `delete_assignment` | Lokale Aufgabe löschen |
---
## Lizenz
MIT
## Disclaimer
Dieses Projekt ist ein inoffizielles, unabhängiges Open-Source-Projekt und steht in keiner Verbindung zur solocode GmbH. ANTON und anton.app sind Produkte bzw. Marken der solocode GmbH. Die Namen werden ausschließlich zur Beschreibung der Kompatibilität verwendet. Die Nutzung erfolgt auf eigenes Risiko und unter Beachtung der Nutzungsbedingungen von ANTON.
[qlty]: https://qlty.sh/gh/udondan/projects/anton