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가 ID 권한 기관이므로, 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 — REST 위의 독립 컨테이너로서의 MCP에 의해 생성됨.

컨테이너 이미지

.github/workflows/build-image.yml에 의해 GitHub Container Registry에 ghcr.io/wyrhta-labs/heorth-mcp 로 게시됩니다. 워크플로는 먼저 타입 검사와 전체 테스트 스위트를 실행합니다 — 실패한 스위트는 게시를 차단합니다 — 그런 다음 이 저장소의 Dockerfile을 linux/amd64용으로 빌드합니다.

두 가지 경우에만 게시됩니다: 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을 고정하지 마십시오 — 둘 다 실행 중인 배포 아래에서 이동하므로 고정의 의미가 없습니다. 워크플로 실행(또는 docker images)에 표시된 정확한 main-<sha> 또는 릴리스의 semver를 사용하십시오.

이미지는 저장소와 마찬가지로 비공개입니다. 이미지를 가져오는 호스트는 Wyrhta-Labs 조직에 대한 read:packages 권한이 있는 GHCR 로그인이 필요합니다.

관련 저장소