Azure Cosmos DB MCP Server

Azure Cosmos DB MCP客户端和服务器

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

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

Demo

Azure架构

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

参考文献

• 为NoSQL帐户创建Azure Cosmos数据库
• 创建Azure存储帐户
• 创建Windows虚拟机
• Windows执行策略

逐步演练

安装

Azure Cosmos数据库

在Azure门户中，为NoSQL帐户创建Azure Cosmos DB。

• 为您的Azure Cosmos DB帐户提供一个唯一的名称。在本演练的其余部分中，我们将使用cosmos-eastus2-nosql-2。

Cosmos DB - Basics

• 点击“下一步：全球分销”

Cosmos DB - Global distribution

• 接受默认值，然后单击“下一步：网络”

Cosmos DB - Networking

• 接受默认值，然后单击“下一步：备份策略”
• 选择“定期”备份策略
• 选择“本地冗余备份存储”

Cosmos DB - Backup Policy

• 点击“下一步：加密”

Cosmos DB - Encryption

• 点击“查看和创建”开始验证

Cosmos DB - Validation

• 点击“创建”开始创建Azure Cosmos DB for NoSQL帐户

对于此项目，您需要在Azure Cosmos DB帐户上启用矢量支持。

• 在设置部分中，选择功能，然后选择“矢量搜索NoSQL API”

• 在打开的面板中，单击启用按钮

Cosmos DB - Validation

• 创建Azure Cosmos DB eShop数据库和产品容器

• 点击eShop旁边的“…”显示上下文菜单，选择“新建容器”在eShop数据库中创建“购物车”容器。

确保分区密钥为 _“/id”_ （分区键区分大小写）

展开“容器矢量策略”，然后单击“添加矢量嵌入”按钮

Cosmos DB - Create database

• 创建购物车容器

Cosmos DB - Create database

存储帐户

1. 创建存储帐户以存储产品映像

有关更多详细信息，请参阅文档：https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-门户网站

Storage - Basics

Storage - Advanced

Storage - Networking

Storage - Data protection

Storage - Encryption

Storage - Validation

\*\*安装软件的先决条件\*\*

1. 在Azure中创建虚拟机或使用本地计算机
2. 从以下位置安装node.js v22.13.1（LTS）https://nodejs.org/en/download
3. 从以下位置安装Visual Studio代码x64 1.97.0https://code.visualstudio.com/download
4. 从x64安装Git 2.47.12https://git-scm.com/downloads
5. 安装。NET SDK x64 v9.0.102从https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-9.0.102-windows-x64-installer
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://.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=
AZURE_STORAGE_CONTAINER_NAME=

1. 获取租户ID。可以使用以下命令检索租户ID：

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

1. 在webapi文件夹中，配置apps_文件，并将tenant_id替换为上一步中获得的值：

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

1. 在Azure门户中创建应用程序注册
2. 在Azure门户中创建应用程序密钥
3. 您需要允许您的应用程序访问Azure Cosmos DB。检索下面提到的4个id，并修改文件“populate/set_rbac.ps1”。

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

1. 打开Powershell提示符，运行Connect AzAccount并执行。/set_rbac.py

Cosmos DB - RBAC

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

• 在Azure门户中，转到您的存储帐户
• 在菜单中选择访问控制（IAM）

Storage - Access Control

• 点击“添加角色分配”
• 在筛选器文本框中，键入“存储Blob数据贡献者”

Storage - Blob Data contributor

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

Storage - Role assignment

• 点击“选择”按钮
• 点击“审核和分配”

Storage - Role assignment

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

Storage - Create container

Storage - Upload files

Storage - Files uploaded

1. 使用.NET Build构建webapi后端项目

cd webapi
dotnet build

Dotnet build 18.在辅助区域VM（澳大利亚东部）上，使用主区域（美国东部2）中套接字服务器的IP地址修改.env文件

socket_server_ip

1. 此项目中没有内置身份验证。用户电子邮件已硬编码在/nextjs/models/constants.ts中。请更改它以满足您的演示需求

1. 在mcp-server和nextjs文件夹中，将.env.template复制到.env，并修改值以满足您的演示需求

AZURE_COSMOSDB_NOSQL_ENDPOINT=https://.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=
NEXT_PUBLIC_AZURE_CLIENT_ID=
NEXT_PUBLIC_AZURE_CLIENT_SECRET=

NEXT_PUBLIC_AZURE_STORAGE_ACCOUNT_NAME=
NEXT_PUBLIC_AZURE_STORAGE_CONTAINER_NAME=img

AZURE_OPENAI_ENDPOINT=https://.openai.azure.com/
AZURE_OPENAI_API_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帐户名和

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

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

Cosmos - Populate products

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

Cosmos - Products

演示脚本

演示初始化：

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

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

1. 启动前端项目

• NextJS前端（店面）

- cd-nextjs - npm启动

1. （可选）打开命令提示符，并使用以下命令启动MCP检查器：

npx-y@model上下文协议/检查器

演示步骤：

1. 引导到http://localhost:3002.

1.

1. 点击右上角的AI助手图标
2. 输入“我对背包感兴趣”（产品列表会更新背包列表）
3. 输入“获取我的订单”（订单列表将刷新订单列表）

Demo