2-02 · 모의 MCP 만들기
1. 실습 목표
로컬 mock-erp MCP 서버를 연결해 Claude Code가 조회 Tool 3개와 생성 Tool 1개를 발견하게 합니다. 웹에서 합성 모집단 한 건을 만들고 기존 조회 Tool로 30건이 31건이 되는 흐름도 확인합니다.
2. 시작 지점
Python·MCP·Agent의 책임 경계를 정했고 첫 과정 결과를 확인했습니다.
아래 입출력 예시를 기준으로 MCP 서버와 네 Tool을 구현하고, 구현이 끝난 뒤 서버가 Tool 이름과 입력 스키마를 공개하는지 확인합니다.
3. 구현 범위 및 요구사항
Tool 기능과 입출력 예시
| Tool | 기능 | 입력값 |
|---|---|---|
create_control_population | 기존 합성자료와 연결되는 거래처 변경 모집단 한 건을 생성합니다. | 없음 |
get_control_population | 첫 과정 모집단과 R-01–R-04 판정 요약을 상태별로 조회합니다. | status 선택: all(기본값), normal, review, error 중 하나 |
select_day2_samples | 정상 4건과 검토 필요 8건, 총 12건을 정해진 순서와 선정 이유로 반환합니다. | 없음 |
get_case_evidence | 권한 확인 후 한 사례의 변경·거래처·승인·증빙·지급·첫 과정 규칙을 조회합니다. | change_id 필수: CHG-2608-023 형식, requester_user_id 필수: U701 같은 실습 사용자 ID |
create_control_population
입력: 없음
출력: status="success", row.change_id="CHG-2608-031"
get_control_population
입력: status="review"
기준 출력: status="success", summary=30/29/21/8/1, rows=검토 필요 8건
1건 생성 후 출력: status="success", summary=31/30/21/9/1, rows=검토 필요 9건
select_day2_samples
입력: 없음
출력: status="success", summary=12/4/8, rows=001–004와 022–029
get_case_evidence
입력: change_id="CHG-2608-023", requester_user_id="U701"
출력: status="success", approval_ids=[], evidence_ids=["EVD-2608-023"], payment_ids=["PAY-2608-023"]
권한 실패: requester_user_id="U601"이면 status="permission_denied"구현 원칙
- 기존
backend/app/main.py의 CSV·판정 로직과 기존 의존성 관리 방식을 재사용하고 MCP 패키지만 추가합니다. - stdio 서버 이름은
mock-erp입니다. - Tool은
create_control_population,get_control_population,select_day2_samples,get_case_evidence네 개입니다. create_control_population만vendor_changes.csv에 교육용 합성 행을 추가합니다. 기존 행과 나머지 CSV를 수정·삭제하지 않습니다.- 생성 행은 승인 기록이 없어 R-02 검토 대상으로 보이며 고정 표본 12건과 Agent 검토자료에는 자동 포함되지 않습니다.
- 연결 실패, 잘못된 입력과 권한 거부를 정상 조회와 다른 상태로 반환합니다.
4. 실습 프롬프트
합성 모집단을 한 건 생성하고 기존 검토 결과에서 다시 조회하는 로컬 `mock-erp` MCP 서버를 연결해 주세요.
현재 웹앱은 거래처 변경 요청을 읽고 규칙을 판정해 SQLite에 저장하지만, Agent가 이 결과를 조회할 수 있는 Tool은 없습니다. 기존 백엔드 함수와 의존성 관리 방식을 먼저 확인하고 같은 데이터를 읽는 로컬 MCP 서버를 추가해 주세요.
구현이 끝나면 웹과 MCP 클라이언트에서 모집단 한 건을 생성한 뒤 기존 조회 결과에 포함됐는지 확인할 수 있어야 합니다. Agent 검토 절차는 계속 조회 Tool만 사용합니다.
- `backend/mcp_server.py`와 `.mcp.json`을 이용한 로컬 stdio 서버 연결
- `create_control_population()`: 기존 거래처·활성 사용자 마스터를 참조해 새로운 거래처 계좌변경 사례 한 건을 생성하고 `vendor_changes.csv`에 추가
- `get_control_population(status="all")`: `all`, `normal`, `review`, `error` 중 선택한 상태로 모집단을 조회하고 요약을 현재 데이터에서 계산
- `select_day2_samples()`: 기존 선정 기준에 따라 이후 검토 대상을 조회하고 각 대상의 선정 이유를 반환
- `get_case_evidence(change_id, requester_user_id)`: 요청자 권한을 확인한 뒤 해당 사례의 변경·거래처·승인·증빙·지급·규칙 근거를 조회
- 건수, ID와 상태별 결과는 예시를 하드 코딩하지 말고 CSV와 SQLite의 현재 데이터에서 계산
- 실제 데이터에서 계산한 요약과 승인·증빙·지급·규칙 근거 반환
- 응답에 원본을 확인할 수 있는 source ID 포함
- 잘못된 입력, 없는 사례와 권한 오류의 구분
- 기존 행 수정·삭제, 나머지 CSV 쓰기와 불필요한 공통 계층 생성 금지
- 웹 버튼은 FastAPI가 실제 stdio MCP로 create 후 get을 호출하고 생성 행을 화면에서 선택
- 기존 화면과 완료 상태 유지
Tool 목록과 대표 호출만 확인하고 기존 검사 명령을 실행해 주세요. 구현 후에는 변경 파일, Tool별 실제 입출력·오류, 읽기 전용 보장과 남은 위험만 간단히 알려 주세요.5. 예상 결과
Success
- 체크포인트:
student/06-mcp-connected- MCP 서버
mock-erp, 조회 Tool 3개와 생성 Tool 1개- 모집단
30 / 29 / 21 / 8 / 1- 생성 1회 후 모집단
31 / 30 / 21 / 9 / 1, 생성 행이 기존 get과 웹 예외 목록에 표시됨- 기존 행·나머지 CSV·고정 표본 12건과 첫 과정 SQLite 계약 유지
- 네 Tool의 이름·입력 스키마와 예시 응답이 구현 결과와 일치함
6. 대표 실패 사례 및 복구
Failure
- MCP 설정이 다른 작업 폴더를 가리킴
- stdout 로그가 stdio 프로토콜을 깨뜨림
- 생성 Tool이 기존 행이나
vendor_changes.csv외 입력을 수정함
Info
실습 폴더에서 Claude Code를 다시 열고 서버 경로를 확인합니다. 같은 오류가 두 번 나거나 10분 지연되면
student/06-mcp-connected로 이동합니다.
7. 다음 실습
검토할 표본 정하고 조회하기에서 반복해서 확인할 12건을 정합니다.