Files

T

Jarca 2ccfc9c064 feat: deploy jarca ledger network mcp service

- add Docker deployment for independent jarca-ledger container
- enable FastMCP streamable-http runtime configuration
- document dcy-013, REQ-019, and BAT-015 verification evidence
- update structure/runtime baselines and deployment runbook

2026-07-07 23:04:42 +09:00

5.1 KiB

Raw Blame History

REQ-019 Docker network MCP deployment and operating DB migration

Status: Implemented
Type: Deployment
Priority: High
Owner: 렛저장인
Source Discovery: docs/discovery/dcy-013_20260707_docker-network-mcp-deployment.md
Batch: BAT-015
Created At (KST): 2026-07-07 22:23 KST
Approved At (KST): 2026-07-07 22:23 KST
Implemented At (KST): 2026-07-07 22:23 KST

1. 배경

재무관리 에이전트가 Jarca Ledger를 사용하려면 genichin-agent가 stdio 프로세스를 실행해 주는 구조가 아니라, jarca-ledger 자체가 독립 Docker 서비스로 실행되고 network MCP endpoint를 직접 제공해야 한다. 또한 기존 jarca 컨테이너의 운영 DB가 새 volume으로 이전되어야 빈 ledger를 운영 source로 오인하지 않는다.

2. Intent

jarca-ledger 컨테이너를 Synology Docker daemon 아래 독립 실행 서비스로 배포하고, streamable-http MCP endpoint와 /volume1/docker/jarca-ledger/data 영속 volume을 운영 기준으로 고정한다. 기존 jarca 운영 DB를 안전하게 이전하고, MCP smoke와 DB status evidence로 재무관리 에이전트 투입 가능 상태를 검증한다.

3. 범위

In Scope

FastMCP runtime transport 설정화: stdio 기본값 유지 + streamable-http 선택 가능
Dockerfile, .dockerignore, docker-compose.yml 추가
container_name=jarca-ledger, restart=unless-stopped, port 8000:8000, volume /volume1/docker/jarca-ledger/data:/data
기존 jarca DB snapshot 및 새 volume 교체
network MCP tool discovery / health / DB status smoke
Docker deployment runbook 및 baseline docs 갱신

Out of Scope

public internet exposure, TLS, reverse proxy, auth policy
별도 REST business API
dcy-012 review-decision persistence 기능
자동 backup scheduler

4. Requirement

FR-1. MCP runtime transport configuration

jarca-ledger-mcp는 기본 stdio 실행을 보존하면서 환경변수 JARCA_MCP_TRANSPORT=streamable-http, JARCA_MCP_HOST, JARCA_MCP_PORT, JARCA_MCP_STREAMABLE_HTTP_PATH로 network MCP endpoint를 제공할 수 있어야 한다.

FR-2. Independent Docker deployment

Repository는 jarca-ledger:latest image를 빌드하고 jarca-ledger 컨테이너를 restart: unless-stopped로 실행하는 Docker compose 정의를 제공해야 한다.

FR-3. Synology volume and DB path

컨테이너는 host /volume1/docker/jarca-ledger/data를 /data로 mount하고 JARCA_LEDGER_DB_PATH=/data/ledger.sqlite3를 사용해야 한다.

FR-4. Operating DB migration

기존 jarca 컨테이너의 /root/.local/share/jarca/ledger.sqlite3 운영 DB를 SQLite backup snapshot으로 복사해 새 /data/ledger.sqlite3로 이전해야 하며, 이전 전 빈 DB 백업을 남겨야 한다.

FR-5. Deployment documentation and baselines

docs/runbooks/docker-network-mcp-deploy.md, docs/project-structure.md, docs/runtime-flows.md는 network MCP endpoint, Docker service, volume, 운영 검증 절차를 설명해야 한다.

5. Acceptance Criteria

AC-1: tests/test_mcp_http_runtime.py가 stdio default, streamable-http env, invalid transport rejection을 검증하고 통과한다.
AC-2: docker compose build와 docker compose up -d --no-build 후 jarca-ledger가 running, healthy, restart=unless-stopped 상태다.
AC-3: Docker inspect에서 /volume1/docker/jarca-ledger/data -> /data bind mount가 확인된다.
AC-4: MCP streamable-http smoke가 http://192.168.55.253:8000/mcp에서 56개 tool discovery와 ledger_health_check 성공을 확인한다.
AC-5: get_ledger_db_status가 /data/ledger.sqlite3, integrity_check=ok, accounts=8, transactions=6312, import_batches=13, category_rules=46, ledger_categories=62를 보고한다.
AC-6: 전체 python -m pytest -q가 통과한다.
AC-7: 배포 runbook과 baseline docs가 network MCP 운영 구조를 반영한다.

6. Impacted Area

jarca_ledger_mcp/adapters/mcp/server.py
tests/test_mcp_http_runtime.py
Dockerfile
.dockerignore
docker-compose.yml
docs/runbooks/docker-network-mcp-deploy.md
docs/project-structure.md
docs/runtime-flows.md
Synology host path /volume1/docker/jarca-ledger/data

7. Verification Evidence Summary

Full pytest: python -m pytest -q → PASS (........................ss..................ss... [100%])
Runtime config tests: python -m pytest tests/test_mcp_http_runtime.py -q → PASS (... [100%])
Docker image build: docker compose build → PASS, image jarca-ledger:latest built
Container start: docker compose up -d --no-build → container jarca-ledger started
Health: state=running health=healthy restart=unless-stopped
MCP smoke: tool_count 56, ledger_health_check success true, db_path /data/ledger.sqlite3
DB status after migration: integrity_check ok, accounts=8, transactions=6312, import_batches=13, category_rules=46, ledger_categories=62

8. Change Log

2026-07-07 22:23 KST: dcy-013 범위를 바탕으로 REQ-019를 생성하고, 이미 수행된 Docker network MCP 구현/배포/DB 이전 evidence를 근거로 Implemented 상태로 기록했다.

5.1 KiB Raw Blame History