# REQ-018 MCP/Streamlit adapter surface narrowing and baseline refresh for dcy-011 completion

- Status: Implemented
- Type: Interface
- Priority: High
- Owner: 렛저장인
- Source Discovery: `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md`
- Batch: BAT-014
- Created At (KST): 2026-07-03 08:03 KST
- Approved At (KST): 2026-07-03 08:03 KST
- Implemented At (KST): 2026-07-03 08:23 KST

## 1. 배경

`REQ-015`~`REQ-017`으로 write/import/advanced workflow owning services는 분리되었지만, adapter 계층은 아직 broad surfaces를 유지한다. `adapters/mcp/server.py`는 모든 tool wrapper가 직접 `service.py`에 의존하고, `dashboard/app.py`는 flat `service_gateway` namespace에 넓게 결합되어 있다. dcy-011의 마지막 단계는 이 adapter surfaces를 더 좁히고 baseline 문서를 실제 구조에 맞춰 갱신하는 것이다.

## 2. Intent

MCP adapter는 contract/registration helper를 통해 service facade 의존을 더 국소화하고, Streamlit dashboard는 page/domain gateway를 명시적으로 사용하도록 재구성한다. 동시에 `docs/project-structure.md`와 `docs/runtime-flows.md`를 Phase 4~7 완료 상태에 맞게 refresh 해 dcy-011을 완결한다.

## 3. 범위

### In Scope
- `adapters/mcp/tool_contracts.py` 또는 동등 helper를 도입해 MCP tool wrappers의 broad service dependency를 줄임
- `adapters/streamlit/*_gateway.py` page/domain gateways를 도입/확장해 `dashboard/app.py`의 flat gateway 결합을 줄임
- `adapters/streamlit/service_gateway.py`는 compatibility aggregator로 유지 가능
- `docs/project-structure.md`, `docs/runtime-flows.md`, dcy-011 metadata/status 갱신

### Out of Scope
- MCP tool 이름/응답 shape 변경
- Streamlit UX redesign
- HTTP adapter 구현

## 4. Requirement

### FR-1. MCP contract helper narrowing
- `adapters/mcp/server.py`는 직접 `service`에 광범위하게 결합하지 않고 helper/contract layer를 통해 tool contract를 호출해야 한다.

### FR-2. Streamlit page/domain gateways
- `dashboard/app.py`는 flat broad gateway 대신 overview/assets/transfers/categories/import/accounts 등 page/domain gateway를 사용해야 한다.
- hot-reload fallback은 유지하되, broad implementation module 직접 import로 되돌아가면 안 된다.

### FR-3. Baseline refresh
- `docs/project-structure.md`와 `docs/runtime-flows.md`는 Phase 4~7 완료 후 구조/흐름을 반영해야 한다.

## 5. Acceptance Criteria
- AC-1: MCP adapter helper/contract seam과 Streamlit page/domain gateway modules가 존재한다.
- AC-2: `dashboard/app.py`가 flat broad gateway 의존을 줄이고 page/domain gateway 호출로 동작한다.
- AC-3: `pytest tests/test_dashboard_app.py`, full pytest, MCP discovery, 필요 시 browser/HTTP smoke가 PASS 한다.
- AC-4: baseline docs와 dcy-011 status/links가 완료 상태를 반영한다.

## 6. Impacted Area
- `jarca_ledger_mcp/adapters/mcp/server.py`
- `jarca_ledger_mcp/adapters/mcp/tool_contracts.py`
- `jarca_ledger_mcp/adapters/streamlit/*.py`
- `dashboard/app.py`
- `docs/project-structure.md`
- `docs/runtime-flows.md`
- `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md`

## 7. Change Log
- 2026-07-03 08:03 KST: dcy-011 Phase 7 adapter narrowing + baseline refresh 범위를 바탕으로 REQ-018을 생성하고 BAT-014 입력으로 즉시 승인했다.
- 2026-07-03 08:23 KST: MCP tool_contracts, Streamlit page/domain gateways, baseline 문서 refresh, AppTest/full pytest/MCP discovery evidence를 근거로 REQ-018을 Implemented로 전환했다.