Azure Cosmos DB MCP CLient & Server

Azure Cosmos DB MCP 客户端与服务端

此存储库包含一个项目，演示如何为 Azure Cosmos DB 创建 MCP 服务和客户端。该项目分为 2 个部分：

• 前端应用：一个 NextJS 15 应用，用于展示产品目录，并提供 AI 助手，帮助用户查找目录中的产品和查看过往订单
• MCP 服务组件：连接到 Azure Cosmos DB NoSQL 数据库，负责从数据库中读取产品和订单。

Azure 架构

• 一个用于存储产品目录的 Azure Cosmos DB NoSQL 数据库
• 一个充当 MCP 服务组件的 node.js 服务

参考资料

• 创建 Azure Cosmos DB for NoSQL 帐户
• 创建 Azure Storage 帐户
• 创建 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 容器

Storage 帐户

1. 创建一个 Storage 帐户来存储产品图片

如需了解详情，请参阅文档：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 > Overview > Subscription Id
Azure Cosmos DB 帐户名称	cosmos-eastus2-nosql-2
资源组名称	Cosmos DB > Overview > Resource group name
主体 ID	App registration Object 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. 在次要区域的虚拟机（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 检查器： npx -y @modelcontextprotocol/inspector

演示步骤：

1. 导航到 http://localhost:3002。
3. 点击右上角的 AI 助手图标
4. 输入“我对背包感兴趣”（产品列表会刷新并显示背包列表）
5. 输入“获取我的订单”（订单列表会刷新并显示订单列表）