# 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 상태로 기록했다.