MCP 서버는 Google의 gemini-3.1-flash-lite-image 모델을 래핑하여 이미지 생성 및 편집 기능을 제공함
100% 단위 테스트 통과 및 코드 품질 검사에도 불구하고, 실제 API 계약 불일치로 인한 프로덕션 버그 발견됨
기본값(Default Value)의 API 계약 불일치로 인해 특정 API 호출 시 HTTP 400 오류 발생함
모의 테스트(Mock Test)의 한계로 인해 실제 API 계약 위반을 탐지하지 못함
데모 스크립트를 통해 실제 API와 상호작용하며 버그를 신속하게 발견하고 수정함
단위 테스트는 코드의 로직 자체를 검증하는 데 중점을 두므로, 외부 API와의 실제 계약(Contract) 불일치를 탐지하는 데 한계가 있음.
모의 객체(Mock Object)는 테스트 시나리오에 맞춰 미리 정의된 응답을 반환하므로, 실제 API의 유효하지 않은 입력값(Invalid Input Value)이나 변경 사항(Contract Drift)을 반영하지 못함.
본 사례에서는 `SUPPORTED_THINKING_LEVELS`가 API의 실제 허용 값과 달라졌음에도 불구하고, 모의 테스트는 이를 인지하지 못하고 성공적인 응답을 반환함.
결과적으로, 테스트 스위트가 녹색이더라도 실제 프로덕션 환경에서는 예기치 못한 오류가 발생할 수 있음을 시사함.
데모 스크립트는 실제 환경과 유사한 조건에서 최소한의 기능 흐름(Minimal Feature Flow)을 실행하여 잠재적 버그를 조기에 발견하는 효과적인 수단임.
실제 API 호출(Live API Call)을 포함하므로, 코드 내부의 모의 경계(Mock Boundary)를 벗어난 계약 불일치(Contract Mismatch)나 런타임 오류(Runtime Error)를 직접적으로 드러냄.
본 사례에서는 `minimal`이라는 지원되지 않는 `thinking_level` 값을 기본값으로 사용한 첫 번째 API 호출에서 즉시 오류를 발생시킴.
이처럼 저비용 고효율의 엔드투엔드 테스트(End-to-End Test)로서 데모 스크립트는 개발 초기 단계에서 치명적인 버그를 예방하는 데 기여함.
API 제공자는 API 계약(API Contract)을 변경할 때 하위 호환성(Backward Compatibility)을 유지하거나, 변경 사항을 명확히 문서화해야 함.
본 사례에서 `SUPPORTED_THINKING_LEVELS`는 API의 실제 허용 값(`low`, `high`)과 달리 로컬에 캐시된 오래된 정보(`minimal`, `low`, `medium`, `high`)를 포함하고 있었음.
특히, 명시적으로 값을 지정하지 않은 경우 사용되는 기본값(`medium`)이 실제 API에서 거부되는 값이었기에, 해당 기본값을 사용하는 모든 호출이 실패하는 결과를 초래함.
이는 원격 API의 상태(Remote API State)를 로컬에서 복제할 때 발생하는 데이터 동기화 문제(Data Synchronization Issue)이며, 주기적인 검증 없이는 버그의 온상이 될 수 있음.
Google의 gemini-3.1-flash-lite-image 모델은 이미지 생성 시 `thinking_level` 파라미터를 통해 생성 품질과 비용을 조절할 수 있음.
문서상으로는 `minimal`, `low`, `medium`, `high` 네 가지 값이 명시되어 있었으나, 실제 라이브 API에서는 `low`와 `high` 두 가지만 지원함.
`minimal` 값은 API 요청 시 `invalid_request` 오류 코드와 함께 거부되었으며, 이는 API 계약과 문서 간의 불일치를 명확히 보여줌.
이러한 파라미터 값의 불일치는 API 사용자가 예상치 못한 오류를 경험하게 하는 주요 원인이 되며, 정확한 문서화와 API 검증의 중요성을 강조함.
MCP(Model Context Protocol)는 다양한 AI 모델과 에이전트 간의 통신을 표준화하는 프로토콜임.
본 프로젝트는 MCP를 사용하여 Python 서버를 구축하고, 이를 Rust CLI, Claude Code, Google ADK Agent 등 세 가지 다른 에이전트에서 호출함.
특히 Google ADK Agent는 Gemini 모델을 사용하여 다른 Gemini 모델 기반 서버를 호출하는 Gemini-to-Gemini 통신 구조를 가짐.
이러한 상호 운용성(Interoperability)은 단일 모델에 종속되지 않고 다양한 AI 도구를 통합하여 복잡한 워크플로우를 구축할 수 있게 함.