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로 전환했다.

3.6 KiB Raw Blame History