mcp-api-tester Tools & Interfaces

mcp-api-tester ツールとインターフェース

このドキュメントでは、LLM（大規模言語モデル）が API テストを自動化するためのツールやインターフェースについてまとめています。これらのツールを活用することで、LLM は API ドキュメントを読み取り、net/http を使用して特定のエンドポイントを選択・テストし、開発者が潜在的な問題をすばやく特定できるよう支援します。

コアツール（最小限の実用ツール）

次の 3 つのツールは、LLM が最小限の実用的な自動テストを実施するための、最も基本的かつ重要なインターフェースです。

1. listAllAPIFromDocument

   • 目的: ドキュメントから利用可能なすべての API（名前、URL、HTTP メソッドなど）を一覧表示します。
   • 例: 戻り値の例は次のようになります。

     [
       { "name": "getUser", "method": "GET", "url": "/users/{id}" },
       { "name": "createUser", "method": "POST", "url": "/users" }
       ...
     ]
     

   • LLM の使用場面: 利用可能な API を確認し、テスト対象を選択するために使用します。

2. getSingleAPIDetail

   • 目的: 名前またはパスを指定して、特定の API の詳細なドキュメントを取得します。例：
     • リクエストパラメーター（クエリ、パス、本文など）
     • レスポンスの構造（スキーマ）
     • 想定されるステータスコードとエラーの定義
   • 例: 戻り値の例は次のようになります。

     {
       "name": "getUser",
       "method": "GET",
       "url": "/users/{id}",
       "parameters": [
         { "in": "path", "name": "id", "type": "string", "required": true }
       ],
       "responses": {
         "200": {
           "description": "成功時にユーザーデータを返します",
           "schema": { ... }
         },
         "404": {
           "description": "ユーザーが見つかりません"
         }
       }
     }
     

   • LLM の使用場面: 特定のエンドポイントに対するテストパラメーターと、期待されるレスポンスを生成するために使用します。

3. callNetHTTP

   • 目的: LLM が実際の HTTP リクエストを送信し、結果（ステータスコード、ヘッダー、本文）を受け取れるようにします。
   • 例:

     {
       "request": {
         "method": "POST",
         "url": "/users",
         "headers": { "Content-Type": "application/json" },
         "body": { "name": "NewUser", "age": 30 }
       },
       "response": {
         "status": 201,
         "headers": { ... },
         "body": { "id": "123", "name": "NewUser", "age": 30 }
       }
     }
     

   • LLM の使用場面: テストリクエストを実行し、実際の結果と期待される結果を比較するために使用します。

---

推奨する高度なツール（拡張ツール）

これらのツールは必須ではありませんが、自動テスト、レポート作成、環境設定などを大幅に改善できます。

1. レスポンスの検証／解析ツール

1. スキーマ検証

   • validateResponseWithSchema(responseBody, schemaInfo) -> (isValid, errorList)
   • 返された JSON 本文をドキュメントのスキーマと照合し、フィールドの整合性、データ型、必須フィールドを確認します。

2. JSON 解析

   • parseJSON(responseBody) -> (parsedObject)
   • LLM がレスポンス内の特定のフィールドを簡単に読み取り、確認できるようにします（例：特定のフィールドが空でないことの確認）。

2. テスト実行のコンテキスト／ログ記録ツール

1. テスト結果の記録／保存

   • storeTestResult(testCase, response, passOrFail, errorMessage)
   • LLM が各テストケースの実行詳細、エラー、結果を記録できるようにし、レポートをまとめやすくします。

2. 過去のテスト結果

   • getTestHistory(apiName or endpoint) -> (historyData)
   • LLM（または他のシステム）が同じエンドポイントの過去のテスト結果を照会し、時間の経過に伴うリグレッションや変更を把握できるようにします。

3. 環境セットアップ／管理ツール

1. 認証／資格情報のセットアップ

   • getAuthToken(username, password) -> token
   • 一部の API では、認証にトークンまたは Cookie が必要です。適切な資格情報を取得するため、LLM は最初にこのツールを呼び出す必要がある場合があります。

2. テストデータのリセット／初期化

   • resetTestData() または seedTestData()
   • テスト開始前に、データベースまたはシステムの状態が既知のデフォルト状態になるようにします。

4. ファジング／エッジケーステストツール

• generateFuzzyInput(fieldType, constraints)
• ストレステストやセキュリティチェック用に、極端または通常とは異なる入力（例：負の値、非常に大きな値、ランダムな文字、特殊記号）を返します。

---

推奨される開発フロー

1. 最小限の実用ツールを統合する

   1. システムに listAllAPIFromDocument、getSingleAPIDetail、callNetHTTP を実装し、LLM が次のことをできるようにします。
      • 利用可能なエンドポイントの一覧を取得する
      • 指定した API の詳細な仕様を取得する
      • 実際の HTTP リクエストを送信する

2. LLM を接続する

   • LLM が上記の 3 つのツールを使用できるようにします。エンドポイントの候補を一覧表示し、それぞれの詳細を取得して、テストシナリオを生成し、最後に callNetHTTP で実行できます。

3. 検証ツールを追加する（レスポンス／スキーマ）

   • 返されたデータが、ドキュメントに記載されたスキーマや期待値に一致するかどうかを LLM が検証できるユーティリティを提供します。

4. テストログと環境管理を拡張する

   • テスト結果の保存、過去のテストの照会、環境のリセット、認証トークンの取得を行うインターフェースを提供します。
   • LLM はこれらのツールを呼び出して、一貫した状態とテストプロセスの記録を維持できます。

5. ファジング／エッジケーステスト

   • 悪意のある値や極端な値を生成するツールを統合するか、LLM がそれらを自動生成できるようにして、詳細なストレステストやセキュリティテストを実施します。

---

重要な注意事項

• セキュリティと権限

  • LLM が API を呼び出す際は、これらのテストを安全な環境（開発環境またはサンドボックス）で実行し、機密データを危険にさらさないようにしてください。

• LLM が生成するコンテンツの正確性

  • LLM は無効または誤ったパラメーターを生成する可能性があります。インターフェースに追加の検証やエラー処理が必要になる場合があります。

• 従来のテストを完全に置き換えることはできません

  • LLM は境界値や異常系のテストケースをすばやく生成できますが、十分な網羅性を確保するには、従来のユニットテストが引き続き不可欠です。

テスト

ReadOpenAPIDocument

curl -X POST --data '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
  "name": "ReadOpenAPIDocument",
  "arguments": {
    "openAPIPath": "/absolute/path/to/your/openAPI/file"
  }
}
}' http://localhost:8000/message?sessionId=9fa4fc8c-1799-4955-a0bb-4881258f13f9

ListAllAPIFromDocument

curl -X POST --data '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
  "name": "ListAllAPIFromDocument"
}
}' http://localhost:8000/message?sessionId=9fa4fc8c-1799-4955-a0bb-4881258f13f9