RAG MCP Server (Lambda + OpenSearch Serverless)

RAG MCP Server（Lambda + OpenSearch Serverless）

このプロジェクトは、AWS のサーバーレスアーキテクチャを使用してデプロイされる、MCP（Model Context Protocol）ツールとして設計された RAG（検索拡張生成）サーバーを実装します。

コンピューティングには AWS Lambda、リクエストインターフェイスには API Gateway（HTTP API）、ベクトルストレージ／検索には OpenSearch Serverless、埋め込みと生成には OpenAI、永続的な生ドキュメントストレージには AWS S3 を使用します。

インフラストラクチャは、Python を使用した AWS Cloud Development Kit（CDK）で管理します。

前提条件

開始する前に、以下がインストールされていることを確認してください。

• Node.js と npm： AWS CDK に必要です。（ダウンロード）
• AWS CDK Toolkit： npm を使用してグローバルにインストールします：npm install -g aws-cdk
• AWS CLI： インストールして設定してください。CDK と Makefile が AWS アカウントとやり取りするために使用します。
  • 設定： 通常は以下の方法で認証情報を設定します。
    • IAM Identity Center（SSO）：aws configure sso または aws sso login を実行します。こちらが推奨される最新の方法です。
    • IAM User：aws configure を実行し、Access Key ID と Secret Access Key を入力します（セキュリティ上、推奨度は低くなります）。
  • AWS CLI 設定ガイドを参照してください。
  • 重要： 設定した AWS プロファイル（またはデフォルトプロファイル）に、十分な権限があることを確認してください（「セットアップ」セクションを参照）。
• Python： バージョン 3.9 以降（Lambda ランタイムに適合するもの）。
• Pip： 通常は Python に含まれています。Python の依存関係の管理に使用します。
• Make： Makefile の自動化ターゲットの使用に必要です。（Linux/macOS には通常プリインストールされています。Windows ではインストールが必要な場合があります）。

プロジェクト構成

/
├── Makefile             # Automation commands (build, deploy, test, etc.)
├── pyproject.toml       # Application dependencies & project metadata
├── pytest.ini           # Pytest configuration (ensures tests find modules)
├── .env.example         # Example environment variables for local testing/config
├── README.md            # This file
├── src/                 # Application source code (Lambda handler, services, utils)
├── stack/               # CDK Stack definition (Python)
├── infrastructure/      # AWS CDK app definition and config
│   ├── app.py           # CDK App entrypoint
│   ├── cdk.json         # CDK configuration
└── tests/               # Application and infrastructure tests
    ├── test_lambda_handler.py
    └── test_infrastructure.py
└── example_payloads/    # Example JSON payloads for API requests
    ├── payload_add.json
    ├── payload_query.json
    └── payload_list.json

セットアップと設定

1. 依存関係のインストール： プロジェクトのルートディレクトリで、Python の依存関係をインストールします。

   make deps
   

2. AWS 認証情報と権限：（デプロイには AdministratorAccess または同等の権限があることを確認してください）。

3. AWS Secrets Manager にシークレットを作成（対象リージョン）：

   • OpenAI API キーのシークレット：
     • 名前： AI/MCP_SERVERS/RAG_SERVER（または stack/rag_mpc_stack.py を更新します）
     • タイプ： その他のタイプのシークレット
     • シークレットのキー／値： キー OPENAI_API_KEY を 1 つ追加し、値として sk-... のキーを設定します。
   • アプリケーション API キーのシークレット：
     • 理由： デプロイした API へのクライアントリクエストを認証するためです。
     • 名前： App/RagMcp/ApiKey（または stack/rag_mpc_stack.py を更新します）
     • タイプ： その他のタイプのシークレット
     • シークレット値： プレーンテキストを選択し、クライアントアプリケーション（Agentic AI フレームワーク）が使用する、強力でランダムな API キー値を入力します。（例：UUID を生成するか、パスワード生成ツールを使用します）。キーと値のペアとして保存せず、キー文字列そのものだけを保存してください。

4. 環境変数（ローカルでの使用）：（テスト／デプロイには不要です）。

Makefile によるデプロイと管理

Makefile には、アプリケーションのライフサイクルを管理する便利なターゲットが用意されています。必要に応じて、環境変数を使ってデフォルトの AWS リージョンとプロファイルを上書きできます（例：AWS_REGION=us-east-1 make deploy）。

一般的なワークフロー：

1. make deps
2. make bootstrap
3. AWS Secrets Manager で両方のシークレット（OpenAI キー、アプリ API キー）を作成します。
4. make deploy
5. make invoke / make logs / API エンドポイント（API キーを含む）を使ってアプリケーションを利用します。
6. make destroy

Makefile のターゲット：

• make build：Lambda デプロイパッケージをビルドし（pyproject.toml から依存関係をインストールして src/ をコピー）、build/lambda_package/ ディレクトリに格納します。これは make deploy と make test の一環として自動的に実行されます。

• make bootstrap：（AWS アカウント／リージョンごとに 1 回実行）CDK デプロイ用に AWS 環境をブートストラップします。

  • **理由：**CDK は、デプロイアセットを保存してデプロイを管理するために、S3 バケットなどの特定の AWS リソースを必要とします。ブートストラップにより、これらの共有リソースが作成されます。

  # Example using the default region from Makefile/AWS config
  make bootstrap
  # Example overriding region
  make bootstrap AWS_REGION=us-east-1
  

• make deploy：Lambda パッケージをビルドし、cdk deploy を使ってスタック全体（RagMcpStack）をデプロイします。

  • **前提条件：**有効な AWS 認証情報、Secrets Manager で正しく設定された OpenAI シークレット、および対象リージョンでの CDK ブートストラップの完了。
  • **処理：**CDK はスタック定義を CloudFormation テンプレートに合成してデプロイします。これにより、必要な AWS リソースがすべて作成または更新されます。特に初回、または OpenSearch リソースの作成／更新時には、数分かかることがあります。
  • **出力：**正常に完了すると、API Gateway のエンドポイント URL がスタックの出力に表示されます。

  make deploy
  # Example overriding region and profile
  make deploy AWS_REGION=us-east-1 AWS_PROFILE=my-dev-profile
  

• make test：必要に応じてパッケージをビルドし、pytest を使ってユニットテストとインフラストラクチャテストを実行します。

• make logs：デプロイ済み Lambda 関数の CloudWatch ログをリアルタイムで追跡します。スタックのデプロイが正常に完了している必要があります。停止するには Ctrl+C を押します。

• make destroy：CloudFormation を介して、CDK スタックが作成したすべての AWS リソースを破棄します。この操作は取り消せないため、注意して実行してください。

• make clean：ローカルのビルド成果物（build/、cdk.out など）を削除します。デプロイ済みの AWS リソースには影響しません。

• make invoke：デプロイ済み API とやり取りするための curl コマンドの例を表示します。

  • まず、コマンドの出力に示されるように、API_KEY と API_URL の環境変数を設定します。
  • 次に、curl コマンドの例を実行します。
  • POST リクエストでは、example_payloads/ ディレクトリにある JSON ファイルを使用します。
  • デプロイ済み URL の例（直近のデプロイ成功時）： https://9h8ob953ge.execute-api.eu-west-3.amazonaws.com/（注：現在のデプロイには、必ず make invoke の出力または CloudFormation の出力にある URL を使用してください）。

アーキテクチャの概要

1. API Gateway（HTTP API）： /mcp への受信 HTTP リクエストを処理します（検出には GET、実行には POST を使用）。
2. **Lambda 関数：**API Gateway からのリクエストを処理します。MCP 呼び出しを解析し、シークレットを取得して、埋め込みを生成し（OpenAI を使用）、OpenSearch Serverless および S3 と連携し、必要に応じて生成のために OpenAI を呼び出します。
3. **OpenSearch Serverless：**ドキュメントの埋め込みとメタデータを保存します。RAG の検索ステップで k-NN ベクトル検索機能を提供します。
4. **S3 バケット：**追加されたドキュメントの元のテキストコンテンツを保存します。
5. **Secrets Manager：**OpenAI API キーを安全に保存します。
6. **IAM：**Lambda 関数が他の AWS サービス（S3、Secrets Manager、OpenSearch、CloudWatch Logs）にアクセスするための権限を定義します。
7. **CloudWatch：**Lambda 関数のログを収集します。

開発に関する注意事項

• テスト： make test を使用すると、AWS／OpenAI／OpenSearch の依存関係をモックしたユニットテストを実行できます。実際のエンドツーエンドテストでは、通常、開発用 AWS 環境へのデプロイが必要です。
• 依存関係： Python の依存関係を pyproject.toml に追加し、make deps を実行します。
• インフラストラクチャ： stack/rag_mpc_stack.py を編集して AWS リソースを変更します。
• アプリケーションロジック： src/ ディレクトリ内のファイルを編集して Lambda の動作を変更します。

サンプルスクリプトの実行

サンプルの Python スクリプト（example.py）では、デプロイ済み API とのやり取り方法を示しています。

1. スタックをデプロイします： スタックがデプロイ済みであることを確認します（make deploy）。

2. 環境変数を設定します： デプロイ済み API の URL と App API Key を環境変数として指定する必要があります。これらは make invoke を実行するか、CloudFormation スタックの出力から取得できます。

   # URL を取得します（例）
   export API_URL=$(aws cloudformation describe-stacks --stack-name RagMcpStack --query "Stacks[0].Outputs[?OutputKey=='ApiGatewayEndpoint'].OutputValue" --output text --profile <YOUR_PROFILE> --region <YOUR_REGION>)
   
   # キーを設定します（Secrets Manager にある実際のキーに置き換えます）
   export API_KEY="<YOUR_APP_API_KEY>"
   

3. スクリプトを実行します：

   python example.py
   

   スクリプトはディスカバリーエンドポイントを呼び出し、2 つのドキュメントを追加し、ドキュメントを一覧表示してクエリを実行し、リクエストとレスポンスを出力します。 注： スクリプトには requests ライブラリが必要です（インストールされていない場合は pip install requests を実行してください。ただし、make deps によってインストールされるはずです）。

よくあるトラブルシューティングのヒント

• ExpiredToken／InvalidClientTokenId エラー： AWS 認証情報を更新します（aws sso login）。
• Secrets Manager に関するメッセージが表示されてデプロイに失敗する場合： 次の点を確認してください。
  • CDK 内のシークレット名が AWS 上の名前と完全に一致している。
  • シークレットがデプロイ先と 同じリージョン に存在する。
  • シークレットの値が正しい形式である（OpenAI キーには OPENAI_API_KEY フィールドが必要です。App API Key はプレーンテキストである必要があります）。
  • デプロイ担当者の認証情報に secretsmanager:GetSecretValue 権限がある。
• IAM エラーが発生してデプロイに失敗する場合： デプロイ担当者の権限を確認します。
• API Gateway が 401 Unauthorized を返す場合： クライアントが X-API-Key ヘッダーで正しい API キーの値を送信していることを確認します。
• API Gateway が 5xx エラーを返す場合： Lambda のログを確認します（make logs）。