Azure Cosmos DB MCP CLient & Server

Azure Cosmos DB MCP クライアント＆サーバー

このリポジトリには、Azure Cosmos DB 用の MCP サーバーとクライアントの作成方法を示すプロジェクトが含まれています。プロジェクトは 2 つの部分に分かれています。

• フロントエンドアプリケーション：商品のカタログを表示する NextJS 15 アプリケーションです。ユーザーがカタログから商品を見つけたり、過去の注文を確認したりするのを支援する AI アシスタントを備えています。
• Azure Cosmos DB NoSQL データベースに接続され、データベースから商品と注文を読み取る MCP サーバーコンポーネント

Azure アーキテクチャ

• 商品カタログを格納する Azure Cosmos DB NoSQL データベース
• MCP サーバーコンポーネントとして機能する node.js サーバー

参考資料

• Azure Cosmos DB for NoSQL アカウントを作成する
• Azure Storage アカウントを作成する
• Windows 仮想マシンを作成する
• Windows の実行ポリシー

手順ごとの説明

インストール

Azure Cosmos DB

Azure portal で、Azure Cosmos DB for NoSQL アカウントを作成します。

• Azure Cosmos DB アカウントに一意の名前を付けます。この手順では、以降 cosmos-eastus2-nosql-2 を使用します。

• 「次へ：グローバル分散」をクリックします。

• 既定値をそのまま使用し、「次へ：ネットワーク」をクリックします。

• 既定値をそのまま使用し、「次へ：バックアップ ポリシー」をクリックします。
• 「定期的」バックアップ ポリシーを選択します。
• 「ローカル冗長」バックアップ ストレージを選択します。

• 「次へ：暗号化」をクリックします。

• 「確認および作成」をクリックして、検証を開始します。

• 「作成」をクリックして、Azure Cosmos DB for NoSQL アカウントの作成を開始します。

このプロジェクトでは、Azure Cosmos DB アカウントでベクター検索を有効にする必要があります。

• 設定セクションで「機能」を選択し、「NoSQL API のベクター検索」を選択します。

• 開いたパネルで、「有効にする」ボタンをクリックします。

• Azure Cosmos DB の eShop データベースと Products コンテナーを作成します。

• eShop の横にある「...」をクリックしてコンテキスト メニューを表示し、「新しいコンテナー」を選択して、eShop データベースに「carts」コンテナーを作成します。

パーティション キーが "/id" であることを確認してください（パーティション キーでは大文字と小文字が区別されます）。

「コンテナー ベクター ポリシー」を展開し、「ベクター埋め込みの追加」ボタンをクリックします。

• carts コンテナーを作成します。

ストレージ アカウント

1. 商品画像を保存するためのストレージ アカウントを作成します。

詳細については、ドキュメントを参照してください：https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal

**ソフトウェアの前提条件をインストールする **

1. Azure で仮想マシンを作成するか、ローカルコンピューターを使用します
2. https://nodejs.org/en/download から node.js v22.13.1 (LTS) をインストールします
3. https://code.visualstudio.com/download から Visual Studio Code x64 1.97.0 をインストールします
4. https://git-scm.com/downloads から Git 2.47.12 x64 をインストールします
5. https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-9.0.102-windows-x64-installer から .NET SDK x64 v9.0.102 をインストールします
6. ターミナルウィンドウを開き、次のコマンドで nuget ソースを追加します

dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

7. 必要に応じて、Windows コンピューターの PowerShell 実行ポリシーを変更します。管理者モードで Powershell ウィンドウを開き、次のコマンドを実行します

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

8. 必要に応じて、nuget、powershell、az cli、az modules をインストールします

# install az cli
winget install -e --id Microsoft.AzureCLI

# install nuget and reference nuget source
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force

# update to latest Powershell release (7.5 as of writing)
winget install --id Microsoft.PowerShell --source winget

# install az modules
Install-Module -Name Az -Repository PSGallery -Force -AllowClobber

9. ターミナルウィンドウを開き、リポジトリをクローンします：

git clone https://github.com/patrice-truong/cosmosdb-mcp.git
cd cosmosdb-mcp

10. nextjs フォルダーに移動し、依存関係をインストールします

cd cosmosdb-mcp/nextjs
npm install  --legacy-peer-deps

11. nextjs フォルダーに .env ファイルを作成し、次の値を設定します：

AZURE_COSMOSDB_NOSQL_ENDPOINT=https://<cosmosdb_account_name>.documents.azure.com:443/
AZURE_COSMOSDB_NOSQL_DATABASE=eshop
AZURE_COSMOSDB_NOSQL_PRODUCTS_CONTAINER=products
AZURE_COSMOSDB_NOSQL_CARTS_CONTAINER=carts
AZURE_COSMOSDB_NOSQL_ORDERS_CONTAINER=orders
AZURE_STORAGE_ACCOUNT_NAME=<storage_account_name>
AZURE_STORAGE_CONTAINER_NAME=<container_name>

12. テナント ID を取得します。テナント ID は次のコマンドで取得できます：

az login
az account show --query tenantId -o tsv

13. webapi フォルダーで appsettings.json ファイルを設定し、tenant_id を前の手順で取得した値に置き換えます：

{
  "CosmosDb": {
    "Endpoint": "https:/<cosmosdb_account_name>.documents.azure.com:443/",
    "TenantId": "<tenant_id>",
    "DatabaseName": "eshop",
    "ProductsContainerName": "products",
    "CartsContainerName": "carts",
    "OrdersContainerName": "orders"
  },
  "AzureBlobStorage": {
    "AccountName": "<storage_account_name>"
  }
}

14. Azure Portal でアプリ登録を作成します
15. Azure Portal でアプリシークレットを作成します
16. アプリが Azure Cosmos DB にアクセスできるようにする必要があります。以下に記載された 4 つの ID を取得し、ファイル "populate/set_rbac.ps1" を変更します。

変数	参照
サブスクリプション ID	Cosmos DB > 概要 > サブスクリプション ID
Azure Cosmos DB アカウント名	cosmos-eastus2-nosql-2
リソースグループ名	Cosmos DB > 概要 > リソースグループ名
プリンシパル ID	アプリ登録のオブジェクト ID

$SubscriptionId = "<subscription-id>"   # Azure subscription id
$AccountName = "<cosmosdb-account-name>"    # cosmos db account name
$ResourceGroupName = "<resource-group-name>" # resource group name of the Cosmos DB account
$PrincipalId = "<principal-id>"   # object id of the app registered in Entra ID

17. Powershell プロンプトを開き、Connect-AzAccount を実行してから ./set_rbac.ps1 を実行します

18. アプリ（または仮想マシン）がストレージアカウントにアクセスできるようにします

• Azure portal でストレージアカウントに移動します
• メニューから Access Control (IAM) を選択します

• 「Add role assignment」をクリックします
• フィルターテキストボックスに「Storage Blob Data Contributor」と入力します

• 「Members」をクリックします
• アプリケーション名を選択します

• 「Select」ボタンをクリックします
• 「Review and assign」をクリックします

19. コンテナーを作成し、「azure-storage」フォルダーの内容をストレージアカウントにコピーします

20. dotnet build で webapi バックエンドプロジェクトをビルドします

cd webapi
dotnet build

18. セカンダリリージョンの VM（Australia East）で、.env ファイルを変更し、プライマリリージョン（East US 2）のソケットサーバーの IP アドレスを設定します

19. このプロジェクトには認証機能が組み込まれていません。ユーザーのメールアドレスは /nextjs/models/constants.ts にハードコードされています。デモの要件に合わせて変更してください

19. mcp-server フォルダーと nextjs フォルダーで、.env.template を .env にコピーし、デモの要件に合わせて値を変更します

AZURE_COSMOSDB_NOSQL_ENDPOINT=https://<cosmosdb_account>.documents.azure.com:443/
AZURE_COSMOSDB_NOSQL_DATABASE=eshop
AZURE_COSMOSDB_NOSQL_PRODUCTS_CONTAINER=products
AZURE_COSMOSDB_NOSQL_CARTS_CONTAINER=carts
AZURE_COSMOSDB_NOSQL_ORDERS_CONTAINER=orders

NEXT_PUBLIC_AZURE_TENANT_ID=<tenant_id>
NEXT_PUBLIC_AZURE_CLIENT_ID=<client_id>
NEXT_PUBLIC_AZURE_CLIENT_SECRET=<client_secret>

NEXT_PUBLIC_AZURE_STORAGE_ACCOUNT_NAME=<storage_account_name>
NEXT_PUBLIC_AZURE_STORAGE_CONTAINER_NAME=img

AZURE_OPENAI_ENDPOINT=https://<azure_openai_account>.openai.azure.com/
AZURE_OPENAI_API_KEY=<azure_openai_key>
AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
AZURE_OPENAI_API_VERSION=2024-05-01-preview

20. nextjs フロントエンドプロジェクトをビルドします

cd nextjs
npm run build

商品カタログの登録

このセクションでは、populate/catalog.json ファイルから商品カタログを読み込み、Azure Cosmos DB for NoSQL データベースに登録します。

1. appsettings.json を編集して、Cosmos DB アカウント名と

{
  "CosmosDb": {
    "Endpoint": "https://<cosmosdb_account_name>.documents.azure.com:443/",
    "TenantId": "<tenant_id>",
    "DatabaseName": "eshop",
    "ProductsContainerName": "products",
    "OrdersContainerName": "orders",
  }
}

2. ターミナルウィンドウを開き、populate フォルダーに移動して、az login を実行し、その後 dotnet run を実行します。

3. Azure Cosmos DB コンテナーに正しくデータが登録されたことを確認します。

デモスクリプト

デモの初期化：

3. 開発用コンピューターで、MCP サーバーを起動します。

cd mcp-server
npx ts-node src/server.ts

3. フロントエンドプロジェクトを起動します。

• NextJS フロントエンド（ストアフロント）
  • cd nextjs
  • npm start

4. 必要に応じて、コマンドプロンプトを開き、次のコマンドで MCP inspector を起動します。 npx -y @modelcontextprotocol/inspector

デモの手順：

1. http://localhost:3002 に移動します。
3. 右上隅にある AI アシスタントアイコンをクリックします。
4. 「I'm interested in backpacks」と入力します（商品一覧が更新され、バックパックの一覧が表示されます）。
5. 「Get my orders」と入力します（注文一覧が更新され、注文の一覧が表示されます）。