DTA-WI 문서 MCP 사이드카 개발 계획

목표 및 범위

배치: 동일 Pod에 doc-web(Nginx) + doc-mcp(Node) 사이드카. ReadOnly 공유 볼륨에 dist/apps/dta-wi-doc 마운트.
프로젝트 구성: Nx 별도 애플리케이션 apps/dta-wi-doc-mcp를 추가해 MCP 서버(런타임·의존성·테스트·배포 타깃)를 정적 사이트와 분리. 정적 사이트(apps/dta-wi-doc)는 그대로 유지해 Nginx 빌드 파이프라인 영향 최소화.
네트워크: Pod 내부 localhost 통신. 외부 노출은 내부망 Service/Ingress로 분리된 경로 또는 포트 사용(/mcp/*).
데이터 소스: 기본은 정적 빌드 결과물(HTML/asset). 필요 시 MD/MDX 직접 파싱 옵션을 플래그로 제공.
버전 단일 소스: libs/shared/version.json + apps/dta-wi-doc/versions.json을 읽어 MCP 리소스 메타에 반영.

프로토콜: @modelcontextprotocol/sdk HTTP(S)/SSE 서버. 로컬 개발용 stdio 옵션 유지.
트랜스포트: 기본 SSE, 프록시/방화벽 제약 시 streamable HTTP(NDJSON chunked 응답) 경로 제공. 클라이언트는 StreamableHTTPClientTransport로 접속 가능하도록 엔드포인트 명시.
리소스 URI: doc:<version>:<slug> (예: doc:0.3.0:domains/chat/requirements).
listResources: 버전/섹션(Architecture, Domains 등) 필터, 태그에 버전·섹션·언어 정보 포함.
readResource: 본문(마크다운/텍스트), 원본 경로, 상대 링크를 반환. 요청 파라미터로 빌드본 vs 원본 선택.
툴:
- searchDocs: 키워드·태그·버전 필터, 스니펫 상한/하이라이트.
- getDocBySlug: 정확 매칭 반환.
- listVersions: 사용 가능한 버전 및 기본 버전 노출.
- health: 인덱스 해시, 로드 시각, 리소스 개수, 버전 일치 여부.

Nx 타깃 추가:
- dta-wi-doc:build (기존) → dist/apps/dta-wi-doc.
- dta-wi-doc:index (신규) → 빌드 산출물/MDX 읽어 index.json 생성 후 dist/apps/dta-wi-doc/index.json에 저장.
인덱서 기능:
- 사이드바/버전 정보 동기화, 슬러그 생성 규칙 정렬.
- 본문 정제(코드블록/테이블 유지, HTML 제거 최소화), 메타데이터 태깅.
- 파일 경로 allowlist 적용으로 경로 탈출 방지.
품질 검증: 인덱스 생성 후 SHA/리소스 수/버전 매칭 스모크 테스트 실행.

메트릭: mcp_requests_total, mcp_errors_total, mcp_index_version, mcp_index_loaded_at, resource_hits.
로깅: JSON 구조화, 요청 ID/latency/쿼리 길이 기록, 슬로우 로그(예: 500ms 이상) 경고.
헬스체크: /health에서 버전 일치 여부와 인덱스 해시 제공.