Feature #907
openFeature #866: [MASTER] ICN Solar CAD Agent — Autodesk MCP 및 L2→L1 태양광 자동설계 시스템 구축
Feature #867: Phase 1 — MCP 기반 태양광 CAD 자동설계 플랫폼 구축 및 통합 검증
[INT-02] MCP 및 주요 모듈 통합 실행 검증
0%
Description
INT-02. MCP 및 주요 모듈 통합 실행 검증¶
1. 작업 개요¶
본 작업은 INT-01에서 정의한 통합 인터페이스 계약을 기준으로 Python FastMCP 서버와 주요 태양광 CAD 자동설계 모듈을 실제로 연결하여 MCP Tool 호출, 데이터 전달, 실행 결과, 오류 처리 및 승인 Gate가 정상적으로 동작하는지 검증하는 작업이다.
사용자는 VSCode Copilot 등 MCP Client에서 자연어로 요청하고, MCP 서버는 해당 요청에 필요한 Tool을 제공한다.
본 단계에서는 각 모듈의 개별 테스트에 그치지 않고, 실제 모듈 간 요청·응답을 연결하여 데이터와 실행 상태가 올바르게 전달되는지 확인한다.
GitHub Issue: https://github.com/GilbertMoon/icn-solar-cad-agent/issues/168
상위 Redmine 일감: #867
담당: 이상재
PM 및 검토: 문길래
협력: 황수아, 조영우
계획 기간: 2027-02-03 ~ 2027-02-08
선행 작업: INT-01, PoC-02~03, PoC-25
2. 세부 작업¶
STEP 1. 기존 인터페이스 계약과 구현 상태 확인¶
- INT-01의 Interface Matrix 확인
- MCP Tool 목록과 Tool ID 확인
- 각 Tool의 입력·출력 JSON Schema 확인
- 구현 완료·부분 완료·미구현 모듈 구분
- 모듈별 담당자 및 테스트 방법 확인
- 기존 PoC 테스트 Evidence 재사용 범위 확인
STEP 2. FastMCP 서버 구동 검증¶
- Python 가상환경 및 의존성 확인
- FastMCP 서버 정상 구동
- Tool Discovery 및 목록 조회
- Tool 이름·설명·입력 Schema 확인
- 실행 로그 및 오류 메시지 확인
- 서버 종료·재시작 및 예외 처리 검증
STEP 3. VSCode Copilot MCP 연결 검증¶
- VSCode MCP 서버 설정 확인
- Copilot에서 MCP 서버 연결
- 사용 가능한 Tool 목록 확인
- 자연어 요청에 따른 실제 Tool 호출
- Tool 입력값 및 반환값 확인
- 연결 실패·호출 실패 상황 검증
CLI 호출, 자동 테스트 및 실제 Copilot MCP 호출 결과는 서로 구분하여 기록한다.
STEP 4. L2 Source 및 Knowledge 모듈 통합¶
검증 대상:
- Source Manifest 조회
- Source 권한 및 무결성 검증
- CAD DXF 분석
- 계산서·BOQ 분석
- CAD ↔ 문서 Evidence 연결
- Engineering Knowledge 조회
- Knowledge 승인 상태 및 버전 확인
Source 접근 권한이 없거나 Knowledge 승인이 확인되지 않으면 후속 단계 진행을 차단한다.
STEP 5. 신규 L1 설계 모듈 통합¶
검증 대상:
- L1 Site Geometry 조회
- Site Boundary 및 좌표계 검증
- 장애물·설치 제외영역 조회
- 모듈 사양 및 배치 파라미터 검증
- Approved Knowledge 적용 가능성 판단
- Solver 실행 요청
- Layout Candidate 반환
STEP 6. CAD 도면 생성 및 QA 모듈 통합¶
검증 대상:
- Layout Candidate → CAD Entity 변환
- DXF Candidate 생성
- DXF 재열기 및 Audit
- Authorized Delta 적용 승인 확인
- 변경 전후 Diff 검증
- Quantity / BOQ Report 생성
- CAD QA Report 반환
기존 CAD 원본을 수정하지 않고 별도 Candidate 출력으로 검증한다.
STEP 7. 공통 데이터 및 실행 이력 검증¶
다음 항목의 전달 여부를 확인한다.
| 항목 | 검증 내용 |
|---|---|
| Run ID | 동일 실행 흐름 추적 |
| Request ID | 개별 호출 식별 |
| Schema Version | 데이터 계약 버전 |
| Source SHA | 원본 무결성 |
| Source Revision | 도면·문서 버전 |
| Rule ID / Version | 적용 규칙 추적 |
| Candidate ID | 설계 결과 식별 |
| Stage Status | PASS/FAIL/HOLD 등 |
| Evidence Locator | 결과 근거 조회 |
Tool 호출 과정에서 필수 추적 정보가 소실되지 않도록 한다.
STEP 8. 오류 및 HOLD 전파 검증¶
다음 상황을 시험한다.
- MCP 서버 연결 실패
- 존재하지 않는 Tool 호출
- JSON Schema 불일치
- Source 접근 권한 거부
- Source SHA 또는 Revision 불일치
- Engineering Knowledge 승인 누락
- Solver 입력값 오류
- CAD Writer 실행 실패
- Authorized Delta 승인 누락
- QA 검증 실패
- Tool Timeout
- 중복 요청 및 재시도
필수 Gate에서 오류가 발생하면 후속 단계가 임의로 실행되지 않아야 한다.
STEP 9. 통합 Smoke Test 작성¶
합성 Golden Fixture로 다음을 테스트한다.
- 정상 Tool 호출
- 정상 Tool Chain
- 필수값 누락
- 입력·출력 계약 불일치
- 미구현 단계
- 승인 누락
- 중복 Request
- 실패 후 재시도
- 후속 모듈 오류
- 최종 결과 반환
pytest 등 자동 테스트 도구로 반복 실행 가능하게 구성한다.
STEP 10. 통합 실행 Matrix 작성¶
예상 산출물: mcp-tool-execution-matrix.csv
주요 항목:
- Tool ID
- 담당자
- 입력 Schema
- 출력 Schema
- 실행 가능 여부
- 실제 MCP 호출 여부
- 정상 테스트 결과
- 오류 테스트 결과
- 주요 의존성
- Evidence 위치
- 미해결 이슈
STEP 11. 실행 및 검증 보고서 작성¶
예상 산출물: tool-chain-smoke-report.md
보고 항목:
- 실행환경
- MCP Client 및 Server 버전
- 테스트 일시 및 실행 ID
- Tool별 실행 결과
- 데이터 전달 검증 결과
- 오류/HOLD 처리 결과
- 연결 실패·미구현 모듈
- 개발자별 조치 필요사항
- INT-03 후속 검증 대상
STEP 12. GitHub 반영 및 결과 제출¶
- MCP 통합 Smoke Test 작성
- 계약 검증 코드 및 Fixture 추가
- 실제 MCP Client 호출 Evidence 기록
- Tool 실행 Matrix 작성
- 통합 실행 보고서 작성
- 미완료 및 HOLD 항목 정리
- GitHub 작업 브랜치 및 PR 생성
- 개발자별 검토 및 PM 승인
- main 병합 후 INT-03으로 인계
3. 업무분장¶
| 담당자 | 역할 |
|---|---|
| 이상재 | MCP 서버·Client 연계, Tool Chain 실행, CAD 모듈 연결 |
| 황수아 | Source·BOQ·Engineering Knowledge Tool 검증 |
| 조영우 | L1 Geometry·Constraints·Solver·Quantity Tool 검증 |
| 문길래 | 통합 실행 범위, 오류 Gate, 최종 결과 및 PR 검토 |
4. 제출 산출물¶
- MCP Client–Server 실제 연결 검증 결과
- 주요 MCP Tool 호출 및 응답 Evidence
- 주요 모듈 간 Tool Chain Smoke Test
- 공통 Run ID 및 Source·Rule 버전 전달 검증
- 오류·HOLD·재시도 테스트
- Golden Fixture 및 pytest 결과
mcp-tool-execution-matrix.csvtool-chain-smoke-report.md- 미구현·불일치·후속 수정 항목 목록
- INT-03 인계 자료
- GitHub PR 및 PM 검토 결과
5. 완료 기준 (PASS)¶
- INT-01 계약 및 구현 상태 확인
- FastMCP 서버 정상 구동
- MCP Tool Discovery 성공
- VSCode Copilot 실제 MCP 연결 확인
- 주요 Tool 실제 호출 및 응답 확인
- Source·Knowledge Tool 연계 검증
- L1 Site·Solver Tool 연계 검증
- CAD Writer·Delta·QA Tool 연계 검증
- Run ID 및 필수 Version·Evidence 정보 보존
- 입력·출력 JSON Schema 검증
- FAIL/HOLD 상태 정상 전파
- 미승인·미확정 조건에서 후속 실행 차단
- Timeout·중복 요청·재시도 처리 테스트
- Golden Fixture 및 통합 Smoke Test PASS
- 실제 MCP 호출과 Mock 결과 구분
- 미구현·실패 구간 별도 기록
- 개발자 3명 전문 영역 검토
- GitHub PR 제출 및 PM 검토 완료
- main 병합 및 INT-03 인계 완료
전체 필수 Tool Chain에 미검증 구간이 남아 있다면 전체 실행 결과를 PASS로 표시하지 않고 HOLD 또는 PARTIAL로 기록한다.
6. 개발 및 검증 원칙¶
- 실제 MCP 호출과 직접 Python 테스트 결과를 구분한다.
- 기존 PoC 산출물을 최대한 재사용한다.
- 구현되지 않은 기능을 Mock 결과만으로 완료 처리하지 않는다.
- Source·Knowledge·Delta 승인 Gate를 우회하지 않는다.
- Tool 간 데이터 계약 오류를 숨기지 않는다.
- 중복 실행으로 CAD 객체가 중복 생성되지 않도록 검증한다.
- 원본 CAD 및 설계문서를 변경하지 않는다.
- 고객 자료를 승인 없이 외부로 전송하지 않는다.
- 승인 없는 Autodesk APS 유료 API 호출을 수행하지 않는다.
- 본 단계의 통합 실행 PASS와 최종 설계·운영 승인을 구분한다.
7. 참고 문서¶
GitHub Issue
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/168
INT-01 통합 인터페이스 계약
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/167
PoC-25 End-to-End 통합
https://github.com/GilbertMoon/icn-solar-cad-agent/issues/166
전체 PoC 로드맵
8. 후속 작업¶
INT-02에서 주요 Tool Chain의 실제 연결 및 기본 실행을 검증한 후, INT-03에서 신규 L1 설계 시나리오의 실제 End-to-End 결과와 단계별 정합성을 확대 검증한다.