AWS Labs amazon-qindex MCP Server

AWS Labs amazon-qindex MCP Server は、Amazon Q Business の SearchRelevantContent API との統合を容易にするために設計された Model Context Protocol (MCP) サーバーです。このサーバーは Amazon Q index を使用した認証と検索機能のための必須ツールと機能を提供しますが、現時点では AWS 登録データアクセサーである独立系ソフトウェアベンダー (ISV) を対象としています。このサーバーはクロスアカウント検索機能を実現し、データアクセサーである ISV が、特定の認証・認可フローを使用して、エンタープライズ顧客の Q index を検索し、そのデータソース全体から関連コンテンツにアクセスできるようにします。

Amazon Q Business アプリケーションの所有者向けの直接統合サポートはまだ提供されていません。この MCP サーバーは、ISV への提供を目的とした包括的なソリューションです。

機能

• Q Business とのやり取りのための Boto3 クライアント実装
• さまざまな認証方式(IAM 認証情報、プロファイルベース)のサポート
• Q index リクエストを処理する MCP サーバー実装
• トークンベースの認可サポート
• Q Business API レスポンスのエラー処理とマッピング

ツール

AuthorizeQIndex

• Q index 認証用の OIDC 認可 URL を生成します
• 必須パラメータ:
  • idc_region (str): IAM Identity Center の AWS リージョン(例: us-west-2)
  • isv_redirect_url (str): ISV 登録時に登録したリダイレクト URL
  • oauth_state (str): CSRF 保護用のランダム文字列
  • idc_application_arn (str): Amazon Q Business アプリケーション ID
• 戻り値: ユーザー認証用の認可 URL

CreateTokenWithIAM

• IAM を通じて認可コードを使用し、認証トークンを作成します
• 必須パラメータ:
  • idc_application_arn (str): Amazon Q Business アプリケーション ID
  • redirect_uri (str): 登録済みのリダイレクト URL
  • code (str): OIDC エンドポイントからの認可コード
  • idc_region (str): IAM Identity Center の AWS リージョン
  • role_arn (str): 引き受ける IAM ロールの ARN
• 戻り値: アクセストークン、リフレッシュトークン、有効期限を含むトークン情報

AssumeRoleWithIdentityContext

• トークンから取得したアイデンティティコンテキストを使用して IAM ロールを引き受けます
• 必須パラメータ:
  • role_arn (str): 引き受ける IAM ロールの ARN
  • identity_context (str): デコードされたトークンから取得したアイデンティティコンテキスト
  • role_session_name (str): セッション識別子(デフォルト: "qbusiness-session")
  • idc_region (str): IAM Identity Center の AWS リージョン
• 戻り値: 一時的な AWS 認証情報

SearchRelevantContent

• Amazon Q Business アプリケーション内のコンテンツを検索します
• 必須パラメータ:
  • application_id (str): Q Business アプリケーションの識別子
  • query_text (str): 検索クエリのテキスト
• オプションパラメータ:
  • attribute_filter (AttributeFilter): ドキュメント属性フィルター
  • content_source (ContentSource): コンテンツソースの設定
  • max_results (int): 返される結果の最大数 (1-100)
  • next_token (str): ページネーショントークン
  • qbuiness_region (str): AWS リージョン(デフォルト: us-east-1)
  • aws_credentials: 一時的な AWS 認証情報
• 戻り値: 関連コンテンツにマッチした検索結果

セットアップ

前提条件

• Astral または GitHub README から uv をインストールします

• uv python install 3.10 を使用して Python をインストールします

• 2 つの AWS アカウント(このテスターアプリケーションを実行する ISV としてのアカウントと、Amazon Q Business を実行するエンタープライズ顧客としてのアカウント)

• ISV 用に登録されたデータアクセサー

• エンタープライズ顧客の AWS アカウントに、ユーザーを追加した IAM Identity Center (IDC) インスタンスのセットアップ

• エンタープライズ顧客の AWS アカウントに、IAM IDC をアクセス管理として設定した Amazon Q Business アプリケーションのセットアップ

インストール

Kiro	Cursor	VS Code

MCP クライアントの設定で MCP サーバーを設定します(例: Kiro の場合は ~/.kiro/settings/mcp.json を編集します)。

{
  "mcpServers": {
    "awslabs.amazon_qindex_mcp_server": {
      "command": "uvx",
      "args": ["awslabs.amazon_qindex_mcp_server"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Windows でのインストール

Windows ユーザーの場合、MCP サーバーの設定形式が若干異なります。

{
  "mcpServers": {
    "awslabs.amazon-qindex-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.amazon-qindex-mcp-server@latest",
        "awslabs.amazon-qindex-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

# Clone the repository
git clone [repository-url]

# Go to root directory of this server
cd <your repo path>/mcp/src/amazon-qindex-mcp-server/

# Install dependencies
pip install -e .

使用方法

1. エンタープライズデータから何をクエリしたいかを説明するテキストプロンプトを入力します

search <your query> on enterprise data

2. SearchRelevantContent API を処理するための認証フローを進めるには、以下の詳細情報も提供する必要があります

application id - (enterprise account's Amazon Q Business application ID)
retriever id - (enterprise account's Amazon Q Business retriever ID)
iam idc arn - (enterprise account's IdC application ARN)
idc region - (Region for the IAM Identity Center instance)
qbuiness region - (enterprise account's Amazon Q Business application region)
redirect url - (ISV's redirect url - this could be anything within allowlisted for the data accessor - ie https://localhost:8081)
iam role arn - (ISV's IAM Role ARN registered with the data accessor)

3. 上記 2 つのステップで情報を提供すると、ブラウザで認可 URL にアクセスするよう求められます。認証に成功して URL パラメータに認可コードを含むリダイレクト URL に移動したら(?code=ABC123...&state=xxx のような形式になります)、コード部分をコピーしてクライアントに貼り付け、処理を再開します。

code is <your authorization code>

4. その後、この MCP サーバーは CreateTokenWithIAM で認証トークンを作成し、AssumeRoleWithIdentityContext でロールを引き受けて一時認証情報を取得し、最後に SearchRelevantContent を呼び出して、ユーザーがクエリしたコンテンツを Amazon Q Business アプリケーション内で検索します。

テスト

pytest を使用してテストを実行します。

pytest --cache-clear -v

セキュリティに関する考慮事項

この MCP サーバーの実装は、ユーザーを認識した認証を用いて MCP サーバー経由で SearchRelevantContent API にアクセスする方法を示すデモンストレーション目的のものです。本番環境で使用する場合は、以下のセキュリティ対策を検討してください。

認証と認可

• 認証情報や機密情報をコードにハードコーディングしない
• 適切なセッション管理とトークン更新の仕組みを実装する
• OAuth フローに強力な CSRF 保護の仕組みを使用する
• すべての認可コードとトークンの適切な検証を実装する
• トークンを安全に保管し、決してログに記録しない
• セッション終了時に適切なトークン失効処理を実装する