REQ-014 MCP/Streamlit adapter seam realignment and contract-preserving gateway

Status: Implemented
Type: Interface
Priority: High
Owner: 렛저장인
Source Discovery: docs/discovery/dcy-010_20260702_backend-core-layering-mcp-adapter-realignment.md
Batch: BAT-010
Created At (KST): 2026-07-03 00:15 KST
Approved At (KST): 2026-07-03 00:15 KST
Implemented At (KST): 2026-07-03 00:18 KST

1. 배경

dcy-010은 MCP server와 Streamlit dashboard가 giant service namespace에 직접 결합돼 있어 내부 구조 개선이 곧 external contract drift로 이어질 위험이 크다고 판단했다. Phase 0~3에서는 adapter를 얇게 만들되, tool names/response envelope/dashboard 핵심 페이지를 유지하는 것이 핵심이다.

2. Intent

이 REQ의 목적은 MCP와 Streamlit을 제거하는 것이 아니라, backend core 위에 얹힌 thin adapter로 재정렬하는 것이다. 즉 server.py와 dashboard/app.py가 더 좁은 seam을 통해 application core를 호출하면서도 기존 사용자의 운영 경험과 계약은 유지해야 한다.

3. 범위

In Scope

jarca_ledger_mcp/adapters/mcp/server.py를 도입하고 top-level server.py를 compatibility shim으로 유지한다.
jarca_ledger_mcp/adapters/streamlit/service_gateway.py를 도입하고 dashboard가 이 gateway를 통해 service functions를 호출하도록 정렬한다.
MCP tool discovery 결과(56 tools)와 success envelope contract를 유지한다.
Streamlit 핵심 페이지(요약, 자산/마감 포함)가 synthetic fixture DB에서 렌더링돼야 한다.
baseline docs와 batch verification evidence에 adapter seam을 반영한다.

Out of Scope

신규 MCP 도구 추가나 응답 schema 변경.
새로운 Streamlit IA/디자인 재구성.
HTTP adapter/REST route 추가.

4. Requirement

FR-1. MCP adapter thinness

실제 FastMCP registration은 jarca_ledger_mcp/adapters/mcp/server.py에 위치해야 한다.
top-level jarca_ledger_mcp/server.py는 CLI/script entrypoint 호환을 위한 shim이어야 한다.
MCP 도구명/설명/인자 contract는 유지돼야 한다.

FR-2. Streamlit gateway seam

dashboard/app.py는 giant service implementation이 아니라 명시적 gateway module을 통해 service functions를 사용해야 한다.
gateway는 dashboard가 실제로 필요한 surface만 노출해야 한다.
dashboard 렌더 결과는 synthetic fixture DB 기준 기존 핵심 페이지를 깨지 않아야 한다.

FR-3. Contract-preserving verification

full pytest regression과 MCP tool discovery가 PASS 해야 한다.
browser-level smoke는 synthetic fixture DB에서 요약과 구조 변경 영향 페이지(자산/마감)를 렌더링해야 한다.
브라우저 콘솔 JS 에러가 없어야 한다.

FR-4. Documentation alignment

docs/project-structure.md와 docs/runtime-flows.md는 adapter/gateway seam과 compatibility shim 구조를 반영해야 한다.
BAT verification 문서는 synthetic-only evidence와 잔여 Phase 4+ TODO를 기록해야 한다.

5. Acceptance Criteria

AC-1: jarca_ledger_mcp/adapters/mcp/server.py와 top-level server.py shim이 존재하고 hermes mcp test jarca-ledger가 PASS 한다.
AC-2: jarca_ledger_mcp/adapters/streamlit/service_gateway.py가 도입되고 dashboard/app.py가 이를 사용한다.
AC-3: full pytest가 PASS 하고 Streamlit AppTest smoke가 계속 PASS 한다.
AC-4: local browser smoke에서 요약과 자산/마감 페이지가 렌더링되고 console JS errors가 없다.
AC-5: baseline docs와 batch evidence 문서가 새 adapter seam을 반영한다.

6. Impacted Area

jarca_ledger_mcp/server.py
jarca_ledger_mcp/adapters/mcp/server.py
jarca_ledger_mcp/adapters/streamlit/service_gateway.py
dashboard/app.py
tests/test_dashboard_app.py
tests/test_contract_regression.py
docs/project-structure.md
docs/runtime-flows.md

7. Notes

이 REQ는 MCP/Streamlit surface와 operator-facing 호출 경계를 다루므로 Interface 타입으로 관리한다.
gateway는 현재 dashboard가 사용하는 surface만 노출하며, Phase 4+에서 더 좁은 domain-specific gateway로 재분할할 수 있다.

8. Change Log

2026-07-03 00:15 KST: dcy-010 confirmed 범위를 바탕으로 Proposed 초안을 생성.
2026-07-03 00:15 KST: 사용자 승인 방향(계약 동결, adapter thinness, Phase 0~3 우선)에 따라 Approved로 전환.
2026-07-03 00:18 KST: MCP adapter split, Streamlit gateway 도입, browser smoke, MCP discovery, full pytest PASS를 근거로 Implemented로 전환.

4.6 KiB Raw Blame History