heorth-mcp

Wyrhta Labs 家庭的单一 MCP 服务器，以独立容器运行。

它不拥有任何数据，也不包含任何领域逻辑。每个工具调用都会被转换为对上游服务公共 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 是身份权威，因此当 Heorth 不可达时，即使 KithLedger 健康，kith.* 工具也会失败（IDENTITY_UNAVAILABLE）。

KITH_API_KEY 已移除。KithLedger 强制执行按成员访问控制（ADR 0004），其三种 kl_ 凭据类型均不代表调用成员：member 密钥以签发账户自身的范围读取，household 密钥仅能看到家庭切片，ops 密钥完全没有数据访问权限。

• docs/spec/tool-surface.md — 50 个工具的契约及其 REST 映射

• docs/spec/migration.md — 从上游仓库移出什么、按什么顺序，以及每次删除前必须满足的条件

• CLAUDE.md — 架构、认证模型和约定

由元仓库 Wyrhta-Labs/wyrhta-labs 中的 ADR 0008 — MCP 作为独立容器通过 REST 运行 创建。

容器镜像

由 .github/workflows/build-image.yml 发布到 GitHub 容器注册表，名称为 ghcr.io/wyrhta-labs/heorth-mcp。该工作流首先进行类型检查并运行完整测试套件——测试失败会阻止发布——然后为 linux/amd64 构建此仓库的 Dockerfile。

只有两种情况会发布：推送到 main 和 v* git 标签。其他任何情况都不会发布，因此注册表不会出现分支垃圾。

在生产环境中固定版本。 元仓库的 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），或使用发布版本的语义化版本号。

该镜像与仓库一样是私有的。拉取它的主机需要具有 Wyrhta-Labs 组织的 read:packages 权限的 GHCR 登录。

相关仓库