AIツールサーバーでAPIコントラクトのバグが判明
- •デモスクリプトにより、単体テストをすり抜けていた本番環境のAPIバグが特定された。
- •サーバーが4段階の思考レベルを許可していた一方、実際のGemini APIは2段階のみをサポートしていた。
- •開発者は不適切なローカルの許可リストを修正し、API要件に合わせた回帰テストを追加した。
AIツールサーバーにおけるAPIコントラクトのバグが、ライブデモのスクリプトによって発見された。このシステムはModel Context Protocol (MCP) を使用して「gemini-3.1-flash-lite-image」モデルをラップしており、10件中10件の単体テストを通過し安定していると見なされていた。しかし、デモスクリプトが「minimal」の思考レベルで画像を生成しようとした際、HTTP 400エラーが発生した。調査の結果、サーバーの思考レベルの検証ロジックが古く、「minimal」「low」「medium」「high」の4段階を許可していた一方、実際のGemini APIは「low」と「high」の2段階しかサポートしていないことが判明した。さらにデフォルト設定値が「medium」であったため、デフォルト値に依存するすべてのリクエストが失敗していた。
このバグがテストスイートで見逃されていたのは、テストがサポート対象外の値を含めて成功をシミュレートするモックに依存していたためである。テストはサーバーがパラメータ値を転送できることのみを確認し、実際のAPIとの契約（APIコントラクト）の整合性を検証できていなかった。加えて、これまでの利用者が常にデフォルト以外の思考レベルを指定していたため、本番環境でこのエラーが表面化することもなかった。これは、コード内のローカル許可リストと、リモートAPIが強制する現在の要件との間に大きな乖離が生じていたことを示している。
この問題を解決するため、開発者はサポートレベルを「low」と「high」のみに限定し、デフォルト値を「low」に変更した。また、APIへリクエストを送信する前に、「medium」をローカルで明示的に拒否して分かりやすいエラーメッセージを表示する回帰テストが追加された。修正後、サーバーは再構築されDocker Hubへ再デプロイされた。開発者は、単体テストはローカルロジックの確認には有用だが、実際のAPI資格情報を使用したエンドツーエンドのスモークテストの代わりにはならないと結論付けている。実際のユースケースを想定したシンプルなデモスクリプトを維持することは、モックベースのテストで見落とされがちなコントラクトの乖離を低コストで特定する有効な手法である。