Azure Cosmos DB MCP 客户端与服务器

此仓库包含一个项目，展示了如何为 Azure Cosmos DB 创建 MCP 服务器和客户端。该项目分为两部分：

• 前端应用程序：NextJS 15 应用程序，用于显示产品目录，并具有 AI 助手功能，帮助用户在目录中查找产品并获取过去的订单
• MCP 服务器组件，连接到 Azure Cosmos DB NoSQL 数据库，负责从数据库读取产品和订单。

Azure 架构

• 一个存储产品目录的 Azure Cosmos DB NoSQL 数据库
• 一个作为 MCP 服务器组件的 node.js 服务器

参考资料

• 创建 Azure Cosmos DB for NoSQL 账户
• 创建 Azure 存储账户
• 创建 Windows 虚拟机
• Windows 执行策略

逐步操作指南

安装

Azure Cosmos DB

在 Azure 门户中，创建一个 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

1. 如果需要，更改 Windows 计算机的 PowerShell 执行策略。以管理员模式打开 PowerShell 窗口并运行此命令

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

1. 如有需要，安装 nuget、powershell、az cli 和 az 模块

# 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

1. 打开终端窗口并克隆仓库：

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

1. 导航到 nextjs 文件夹并安装依赖项

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

1. 在 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>

1. 获取您的租户 ID。可以通过以下命令检索租户 ID：

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

1. 在 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>"
  }
}

1. 在 Azure 门户中创建应用注册
2. 在 Azure 门户中创建应用密钥
3. 您需要允许您的应用访问 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

1. 打开 PowerShell 提示符，运行 Connect-AzAccount 并执行 ./set_rbac.ps1

1. 允许您的应用（或虚拟机）访问存储账户

• 在 Azure 门户中，转到您的存储账户
• 在菜单中选择访问控制 (IAM)

• 点击“添加角色分配”
• 在过滤器文本框中，输入“Storage Blob Data Contributor”

• 点击“成员”
• 选择您的应用程序的名称

• 点击“选择”按钮
• 点击“审查并分配”

1. 创建一个容器并将 "azure-storage" 文件夹的内容复制到您的存储帐户中

1. 使用 dotnet build 构建 webapi 后端项目

cd webapi
dotnet build

18. 在您的次区域 VM（澳大利亚东部）上，修改 .env 文件，使用主区域（美国东部 2）中的 socket 服务器的 IP 地址

1. 该项目没有内置身份验证。用户电子邮件在 /nextjs/models/constants.ts 中硬编码。根据您的演示需求进行更改

1. 在 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

1. 构建 nextjs 前端项目

cd nextjs
npm run build

填充产品目录

在本节中，我们将从 populate/catalog.json 文件读取产品目录，并填充 Azure Cosmos DB for NoSQL 数据库

1. 使用您的 cosmosdb 帐户名修改 appsettings.json

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

1. 打开终端窗口，导航到 populate 文件夹，执行 az login，然后运行 dotnet run

1. 验证 Azure Cosmos DB 容器是否已被正确填充

演示脚本

演示初始化：

1. 在您的开发计算机上启动 MCP 服务器

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

1. 启动前端项目

• NextJS 前端（商店前端）
  • cd nextjs
  • npm start

1. 可选地，打开命令提示符并使用此命令启动 MCP 检查器：
   npx -y @modelcontextprotocol/inspector

演示步骤：

1. 导航到 http://localhost:3002。
3. 点击右上角的 AI 助手图标
4. 输入“I'm interested in backpacks”（产品列表刷新显示背包列表）
5. 输入“Get my orders”（订单列表刷新显示订单列表）