heorth-mcp

El servidor MCP único del hogar de Wyrhta Labs, que se ejecuta como su propio contenedor.

No posee datos ni lógica de dominio. Cada llamada de herramienta se traduce en llamadas a la API REST pública de un servicio upstream, de modo que una herramienta MCP solo puede hacer lo que un miembro autenticado del hogar ya podría hacer por HTTP.

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

Estado

Las 50 herramientas portadas. Las 37 herramientas de Heorth (household.*, calendar.*, meals.*, library.*, inventory.*, tasks.*, feoh.*) llegaron en la tarea A5; las 13 herramientas kith.* en la tarea B11. tools/list sirve lo que proporcionen los upstreams configurados: ambas, una o (con ninguna configurada) nada en absoluto. El código MCP sigue viviendo incrustado en Heorth y KithLedger y solo se elimina allí una vez que la herramienta equivalente aquí se verifica contra el contenedor desplegado.

Configuración

heorth-mcp no posee ninguna credencial propia, para ninguno de los dos upstreams. Las llamadas a Heorth llevan el Bearer he_... del llamante tal cual. Las llamadas a KithLedger llevan un token de miembro de corta duración que heorth-mcp intercambia en Heorth (POST /api/v1/auth/satellite-token, ADR 0009) usando esa misma credencial del llamante, almacenada en caché en memoria por llamante durante poco menos de sus 5 minutos de vida. Por eso kith.* necesita ambos upstreams: Heorth es la autoridad de identidad, así que si es inalcanzable, las herramientas kith.* fallan (IDENTITY_UNAVAILABLE) incluso cuando KithLedger está sano.

KITH_API_KEY ha desaparecido. KithLedger aplica control de acceso por miembro (ADR 0004) y ninguna de sus tres clases de credenciales kl_ es el miembro llamante: una clave member lee como el propio ámbito de la cuenta emisora, una clave household solo ve la porción del hogar, una clave ops no tiene acceso a datos en absoluto.

• docs/spec/tool-surface.md — el contrato de las 50 herramientas y su mapeo REST

• docs/spec/migration.md — qué sale de los repositorios upstream, en qué orden y qué debe ser cierto antes de cada eliminación

• CLAUDE.md — arquitectura, modelo de autenticación y convenciones

Creado por ADR 0008 — MCP como contenedor independiente sobre REST en el meta repositorio Wyrhta-Labs/wyrhta-labs.

Imagen del contenedor

Publicado en el GitHub Container Registry como ghcr.io/wyrhta-labs/heorth-mcp mediante .github/workflows/build-image.yml. El flujo de trabajo primero verifica tipos y ejecuta la suite de pruebas completa (una suite en rojo bloquea la publicación) y luego construye el Dockerfile de este repositorio para linux/amd64.

Solo dos cosas publican: un push a main y una etiqueta git v*. Nada más lo hace, así que el registro se mantiene libre de basura de ramas.

Fijándolo en producción. El deploy/compose.prod.yml del meta repositorio requiere una etiqueta explícita en 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

Nunca fijes latest ni main: ambos se mueven bajo el despliegue en ejecución y anulan el propósito de fijar. Usa el main-<sha> exacto que muestra la ejecución del flujo de trabajo (o docker images), o el semver de un lanzamiento.

La imagen es privada, como el repositorio. Un host que la extraiga necesita un inicio de sesión en GHCR con read:packages para la organización Wyrhta-Labs.

Repositorios relacionados