heorth-mcp

Der einzelne MCP-Server des Wyrhta-Labs-Haushalts, der als eigener Container läuft.

Er besitzt keine Daten und keine Domänenlogik. Jeder Tool-Aufruf wird in Aufrufe gegen die öffentliche REST-API eines vorgelagerten Dienstes übersetzt – ein MCP-Tool kann also nur das tun, was ein authentifiziertes Haushaltsmitglied bereits über HTTP tun könnte.

MCP client ──Streamable HTTP──▶ heorth-mcp ──▶ Heorth REST      (37 tools)
                                           └─▶ KithLedger REST  (13 tools)

Status

Alle 50 Tools portiert. Die 37 Heorth-Tools (household.*, calendar.*, meals.*, library.*, inventory.*, tasks.*, feoh.*) landeten in Aufgabe A5; die 13 kith.*-Tools in Aufgabe B11. tools/list liefert, was die konfigurierten vorgelagerten Dienste bereitstellen – beide, einer oder (wenn keiner konfiguriert ist) nichts. Der MCP-Code lebt weiterhin eingebettet in Heorth und KithLedger und wird dort erst gelöscht, sobald das entsprechende Tool hier gegen den bereitgestellten Container verifiziert ist.

Konfiguration

heorth-mcp besitzt keine eigenen Anmeldeinformationen – für keinen der beiden vorgelagerten Dienste. Heorth- Aufrufe tragen das Bearer he_... des Aufrufers unverändert. KithLedger-Aufrufe tragen ein kurzlebiges Mitglieder-Token, das heorth-mcp bei Heorth austauscht (POST /api/v1/auth/satellite-token, ADR 0009), unter Verwendung derselben Aufrufer- Anmeldeinformationen, pro Aufrufer im Speicher zwischengespeichert für knapp unter dessen 5-minütiger Lebensdauer. Deshalb benötigt kith.* beide vorgelagerten Dienste: Heorth ist die Identitätsinstanz, also schlagen bei nicht erreichbarem Heorth die kith.*-Tools fehl (IDENTITY_UNAVAILABLE), selbst wenn KithLedger erreichbar ist.

KITH_API_KEY ist weg. KithLedger erzwingt zugriffsbezogene Mitgliederkontrolle (ADR 0004) und keine seiner drei kl_-Anmeldeinformationsarten ist das aufrufende Mitglied: ein member-Schlüssel liest als der Umfang des ausstellenden Kontos, ein household-Schlüssel sieht nur den Haushaltsausschnitt, ein ops-Schlüssel hat gar keinen Datenzugriff.

• docs/spec/tool-surface.md – der 50-Tool-Vertrag und seine REST-Zuordnung

• docs/spec/migration.md – was aus den vorgelagerten Repos herauswandert, in welcher Reihenfolge und was vor jeder Löschung zutreffen muss

• CLAUDE.md – Architektur, Authentifizierungsmodell und Konventionen

Erstellt durch ADR 0008 – MCP als eigenständiger Container über REST im Meta- Repo Wyrhta-Labs/wyrhta-labs.

Container

Veröffentlicht in der GitHub Container Registry als ghcr.io/wyrhta-labs/heorth-mcp durch .github/workflows/build-image.yml. Der Workflow typprüft und führt zuerst die vollständige Testsuite aus – eine rote Suite blockiert die Veröffentlichung – und baut dann das Dockerfile dieses Repos für linux/amd64.

Nur zwei Dinge veröffentlichen: ein Push auf main und ein v*-Git-Tag. Sonst nichts – so bleibt die Registry frei von Branch-Müll.

In der Produktion festpinnen. Das deploy/compose.prod.yml des Meta-Repos verlangt ein explizites Tag in deploy/.env:

HEORTH_MCP_IMAGE_TAG=main-a1b2c3d   # a main build, by short commit sha
HEORTH_MCP_IMAGE_TAG=0.2.0          # a release, once a v0.2.0 tag exists

Pinnen Sie niemals latest oder main – beide bewegen sich unter dem laufenden Deployment und machen das Festpinnen zunichte. Verwenden Sie das exakte main-<sha>, das im Workflow- Lauf angezeigt wird (oder docker images), oder die Semver eines Releases.

Das Image ist privat, wie das Repo. Ein Host, der es zieht, benötigt einen GHCR-Login mit read:packages für die Wyrhta-Labs-Organisation.

Verwandte Repos