mcp-familywall/SPEC.md

Family Wall API – Spezifikation

Erarbeitet durch Browser-Traffic-Analyse (April 2026). Es gibt keine offizielle API-Dokumentation.

Base URL

https://api.familywall.com/api

Authentifizierung

Login

POST https://api.familywall.com/api/log2in Content-Type: application/x-www-form-urlencoded

Request-Parameter:

Parameter	Wert
identifier	E-Mail-Adresse
password	Passwort
type	nicht senden — wird als undefined ignoriert (verifiziert per JS-Analyse)
clientId	weglassen
clientSecret	weglassen
generateAutologinToken	weglassen
countryCode	weglassen

Response (Erfolg):

{ "a00": { "r": { "r": <SessionObject> }, "cn": "log2in" } }

SessionObject enthält u.a. tokenCsrf und webApiUrl. tokenCsrf ist die Session-ID – identisch zur JSESSIONID im Cookie.

Response (Fehler):

{ "ex": { "ex": <ErrorObject> } }
{ "un": { "un": <ErrorObject> } }

Der Server setzt nach erfolgreichem Login ein Session-Cookie: Set-Cookie: JSESSIONID= (= tokenCsrf)

Folgecalls (nach Login)

Alle API-Calls nach dem Login benötigen:

Cookie	JSESSIONID=<session-id>
Header	Tokencsrf: <session-id> (identisch zur JSESSIONID)
Content-Type	application/x-www-form-urlencoded

Logout

POST https://api.familywall.com/api/log2out Content-Type: application/x-www-form-urlencoded

Keine Parameter. Session wird serverseitig invalidiert.

Session-Strategie

Kein Session-Caching. Jeder MCP-Tool-Call führt folgende Sequenz aus:

POST /api/log2in → Session-ID POST /api/ → Nutzdaten POST /api/log2out → Session invalidieren

Credentials (E-Mail + Passwort) werden einmalig via mcp-familywall setup im OS Keyring gespeichert (Keys: email, password). Kein Keyring-Eintrag für session_id.

Bekannte Endpoints

famlistfamily – Kreise abrufen

POST https://api.familywall.com/api/famlistfamily Content-Type: application/x-www-form-urlencoded

Body-Parameter: keine (verifiziert)

Response-Struktur (verifiziert):

a00.r.r[]       → Kreise
  .metaId       → eindeutige Kreis-ID
  .name         → Kreisname

accgetallfamily – Listen + Tasks abrufen

POST https://api.familywall.com/api/accgetallfamily Content-Type: application/x-www-form-urlencoded

Body-Parameter:

Parameter	Wert
a01call	"taskcategorysync"
a02call	"tasksync"
a03call	"tasklistsync"

Hinweis: partnerScope, a03id, withStateBean werden weggelassen.

Response-Struktur (verifiziert):

a00             → famlistfamily-Daten (Kreise) – Nebeneffekt, nicht verwendet
a01.r.r[]       → taskcategorysync (Einkaufskategorien/Abteilungen)
a02.r.r.updatedCreated[]  → tasksync (Tasks)
  .metaId       → eindeutige Task-ID
  .text         → Aufgabentext
  .description  → optionale Beschreibung
  .taskListId   → Zugehörigkeit zur Liste (= metaId der Liste)
  .complete     → "true" / "false" (String, nicht Boolean!)
a03.r.r.updatedCreated[]  → tasklistsync (Listen)
  .metaId       → eindeutige Listen-ID
  .name         → Name (ggf. Systembezeichnung, s.u.)
  .taskListType → Typ der Liste
  .remainingTaskNumber  → offene Einträge (String)
  .totalTaskNumber      → Gesamteinträge (String)

Systembezeichnungen für Listen-Namen

Bekannte Systembezeichnungen werden deutsch übersetzt:

Systembezeichnung	Deutsch
SYS-CAT-SHOPPINGLIST	Einkaufsliste

Unbekannte Bezeichnungen werden unverändert zurückgegeben. Mapping-Tabelle bei Bedarf erweitern.

Debug-Logging

Wenn die Umgebungsvariable FW_DEBUG=1 gesetzt ist, loggt fw_client.py vollständige Request-Bodies und Responses nach stderr. Dient zur Verifikation offener Punkte (z.B. type-Parameter beim Login, Kreis-Felder in Response).

Wichtig: Keine Secrets in Debug-Ausgaben (Passwort maskieren).

Noch zu verifizieren

• Exakter Wert für type-Parameter beim Login → nicht senden (verifiziert per JS-Analyse)
• Response-Struktur von famlistfamily (Kreise) → a00.r.r[], metaId + name (verifiziert)
• Ob a03call=tasklistsync benötigt wird → ja, liefert Listen unter a03.r.r.updatedCreated[] (verifiziert)
• Kreis-Zuordnung in accgetallfamily-Response → noch offen (Feld in Listen-Objekten unbekannt)
• Ob partnerScope / withStateBean benötigt werden → nein (verifiziert)
• Session-Lebensdauer (irrelevant da kein Caching)