heorth-mcp

Единственный MCP-сервер домашнего хозяйства Wyrhta Labs, работающий в собственном контейнере.

Он не владеет ни данными, ни доменной логикой. Каждый вызов инструмента преобразуется в вызовы публичного REST API вышестоящего сервиса — поэтому MCP-инструмент может сделать только то, что уже мог бы сделать аутентифицированный член домохозяйства по HTTP.

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

Статус

Все 50 инструментов перенесены. 37 инструментов Heorth (household.*, calendar.*, meals.*, library.*, inventory.*, tasks.*, feoh.*) появились в задаче A5; 13 инструментов kith.* — в задаче B11. tools/list отдаёт то, что предоставляют настроенные вышестоящие сервисы — оба, один или (если не настроен ни один) вообще ничего. Код MCP по-прежнему живёт встроенным в Heorth и KithLedger и удаляется оттуда только после того, как эквивалентный инструмент здесь будет проверен на развёрнутом контейнере.

Конфигурация

heorth-mcp не хранит собственных учётных данных — ни для одного из вышестоящих сервисов. Вызовы Heorth несут Bearer he_... вызывающего абонента без изменений. Вызовы KithLedger несут кратковременный токен участника, который heorth-mcp обменивает в Heorth (POST /api/v1/auth/satellite-token, ADR 0009), используя те же учётные данные вызывающего, кэшируя их в памяти для каждого вызывающего чуть менее чем на 5 минут его жизни. Вот почему kith.* требует оба вышестоящих сервиса: Heorth является центром идентификации, поэтому, когда он недоступен, инструменты kith.* завершаются с ошибкой (IDENTITY_UNAVAILABLE), даже если KithLedger здоров.

KITH_API_KEY больше нет. KithLedger применяет контроль доступа на уровне участников (ADR 0004), и ни один из трёх типов учётных данных kl_ не является вызывающим участником: ключ member читает в рамках собственной области выдающего аккаунта, ключ household видит только срез домохозяйства, ключ ops вообще не имеет доступа к данным.

• docs/spec/tool-surface.md — контракт на 50 инструментов и его REST-сопоставление

• docs/spec/migration.md — что переносится из вышестоящих репозиториев, в каком порядке и что должно быть истинным перед каждым удалением

• CLAUDE.md — архитектура, модель аутентификации и соглашения

Создано по ADR 0008 — MCP как отдельный контейнер поверх REST в мета-репозитории Wyrhta-Labs/wyrhta-labs.

Образ контейнера

Публикуется в GitHub Container Registry как ghcr.io/wyrhta-labs/heorth-mcp с помощью .github/workflows/build-image.yml. Рабочий процесс сначала выполняет проверку типов и запускает полный набор тестов — красный набор блокирует публикацию — затем собирает Dockerfile этого репозитория для linux/amd64.

Публикуют только два события: push в main и git-тег v*. Больше ничего, поэтому реестр остаётся свободным от мусора веток.

Закрепление в продакшене. Мета-репозиторий deploy/compose.prod.yml требует явный тег в 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

Никогда не закрепляйте latest или main — оба перемещаются под работающим развёртыванием и сводят на нет смысл закрепления. Используйте точный main-<sha>, указанный в запуске рабочего процесса (или docker images), или semver релиза.

Образ является приватным, как и репозиторий. Хост, который его тянет, должен иметь вход в GHCR с read:packages для организации Wyrhta-Labs.

Связанные репозитории