marcus/mcp-familywall
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ffb8b062c86dff4e02c4854f6eebbae1db6c440e
mcp-familywall/CLAUDE.md
T
marcus ffb8b062c8 feat: get_categories tool, author resolution in get_activities, update CLAUDE.md (v0.4.8) 
- get_categories(list_id): new tool filtering taskcategorysync by
  sortingIndexByTaskList, returns {id, name, emoji} ordered by sort index
- get_activities: author IDs now resolved to display names (firstName) via
  famlistfamily members; raw author_id preserved as separate field; member
  lookup is non-fatal (falls back to raw ID on error)
- CLAUDE.md: tools table updated to reflect all implemented tools (v0.4.8)
- SPEC.md: full accgetallfamily response structure documented including
  categories[] on tasks and category parameter investigation findings
- Category assignment in create/update task: all tested parameter names
  ignored by API; still to verify (Service Worker blocks web inspection)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-15 17:04:35 +02:00

5.1 KiB
Raw Blame History

mcp-familywall

Kontext

Dieses Projekt entwickelt mcp-familywall – einen MCP-Server für den Lesezugriff auf Family Wall (familywall.com). Der MCP-Server läuft lokal und wird in Claude Desktop eingebunden.

Infrastruktur
Family Wall API https://api.familywall.com/api
Gitea https://gitea.gecheckt.de/marcus/mcp-familywall
Lokaler Code D:\Dev\Projects\mcp-familywall
Sprache Python 3.12+, uv, MCP SDK, httpx, keyring, click, rich

Deploy-Workflow (nach jeder Code-Änderung)

  1. Claude Code committet und pusht (bei Berechtigungsfehler: bis zu 2 Retries, je 1s warten)

Aktueller Stand

Implementierte Tools (v0.4.8)

Kategorie Tools
Kreise get_circles, get_members
Listen get_lists
Tasks (Lesen) get_tasks, get_categories
Wall get_activities, like_post
Tasks (Schreiben) create_task, update_task, toggle_task, delete_task

Roadmap

  • v0.x: Erweiterter Lese- + Schreibzugriff ← aktuell
  • Offen: Unlike (like_post(like=False)), Task-Kategorie-Zuweisung beim Erstellen/Aktualisieren

Referenzprojekt

Im Ordner reference/ liegen Dateien aus einem anderen MCP-Server-Projekt als Orientierung für Struktur und Patterns:

Datei Zweck
reference/pyproject.toml Projektstruktur, Dependencies, Entry-Points, Build-System
reference/config.py Config-Pattern: YAML laden, validieren, speichern
reference/auth.py Keyring-Integration, Credential-Resolution-Reihenfolge
reference/cli.py Setup-Wizard, check, serve – CLI-Struktur

Wichtig: Diese Dateien sind Referenz, kein Copy-Paste. Alle Synology/DSM-spezifischen Teile werden nicht übernommen. Family Wall nutzt ein anderes Auth-Schema – siehe SPEC.md.

Architektur-Entscheidungen

Session-Strategie

Kein Session-Caching. Jeder Tool-Call führt Login → API-Call → Logout durch. Credentials liegen im OS Keyring (nur email + password), kein session_id.

Kreise (Scopes)

Family Wall kennt mehrere Kreise (z.B. Familie, erweiterter Familienkreis). get_lists unterstützt optionalen scope-Parameter zur Filterung. Ohne scope werden alle Kreise zurückgegeben.

Listen-Namen

Systembezeichnungen (z.B. SYS-CAT-SHOPPINGLIST) werden in deutsche Klarnamen übersetzt. Mapping-Tabelle in modules/lists.py.

Claude Code – Implementierungsregeln

  • Keine destruktiven Operationen in v1.0 → kein Confirmation-Pattern erforderlich
  • Fehlerbehandlung: API-Fehler als verständliche Meldung zurückgeben, keine Stacktraces
  • Keine Secrets in stderr-Ausgaben (Passwort bei Debug-Logging maskieren)
  • Type Hints und Docstrings konsequent verwenden
  • Formatter: ruff format, Linter: ruff check, Tests: pytest
  • Alle Texte (Docstrings, Kommentare, README): Englisch
  • Debug-Logging via FW_DEBUG=1 Umgebungsvariable
  • Nach jeder Aufgabe: git commit + push. Bei Berechtigungsfehler: 1s warten, bis zu 2 Retries
  • .gitignore eigenständig pflegen (Credentials, pycache, .venv, .env, *.pyc etc.)
  • README.md im Projekt-Root pflegen und bei jedem Aufruf aktualisieren

Implementierungsreihenfolge

Gruppe 1 – Projektgerüst + Auth + CLI ✦ Prio: hoch

  • pyproject.toml: Package mcp-familywall, Entry-Point mcp-familywall
  • src/mcp_familywall/config.py: ~/.config/mcp-familywall/config.yaml, schema_version 1
  • src/mcp_familywall/auth.py: Keyring-Service mcp-familywall, Keys: email, password. Credential-Resolution:
    1. Umgebungsvariablen FW_EMAIL, FW_PASSWORD
    2. OS Keyring
  • src/mcp_familywall/fw_client.py: HTTP-Client mit httpx. Methoden: login(), logout(), call(endpoint, params). Debug-Logging wenn FW_DEBUG=1 (Passwort maskieren).
  • src/mcp_familywall/cli.py:
    • setup: fragt E-Mail + Passwort, führt Login/Logout durch, speichert Credentials im Keyring, gibt Claude-Desktop-Snippet aus
    • check: testet Auth und API-Erreichbarkeit
    • serve: startet MCP-Server

Config-Datei enthält nur:

schema_version: 1

Gruppe 2 – MCP Tools ✦ Prio: hoch

src/mcp_familywall/server.py + src/mcp_familywall/modules/lists.py

get_circles

  • Ruft famlistfamily auf
  • Gibt alle Kreise zurück: id, name
  • Confirmation: nein

get_lists

  • Signatur: get_lists(scope: str = None) -> str
  • Ruft accgetallfamily auf (Parameter: a01call=taskcategorysync, a02call=tasksync)
  • Gibt zurück: id (metaId), name (übersetzt), type, offene Einträge, Gesamteinträge, Kreis-Name
  • Ohne scope: alle Kreise; mit scope: nur dieser Kreis
  • Confirmation: nein

get_tasks

  • Signatur: get_tasks(list_id: str, only_open: bool = True) -> str
  • list_id: metaId aus get_lists
  • Gibt zurück: id, text, description, completed
  • Confirmation: nein

Test-Credentials (nur für Entwicklung)
E-Mail marcus@gecheckt.de
Passwort Lasdas1234

Hintergrund

Marcus ist Senior Software Engineer (Java, Jakarta EE). Präferenz: State-of-the-Art, Best Practices, saubere Architektur. Automatisierung spart Zeit für die Familie. 🌱

Reference in New Issue View Git Blame Copy Permalink