Azure Cosmos DB MCP 客户端和服务器

Name: Azure Cosmos DB MCP Server
Author: patrice-truong

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

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

Azure 体系结构Azure Architecture

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

Related MCP server: Azure Cosmos DB MCP Server

参考

分步演练

安装

Azure Cosmos DB

在 Azure 门户中，创建一个 Azure Cosmos DB for NoSQL 帐户。

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

Cosmos DB 基础知识

点击“下一步：全球分发”

Cosmos DB - 全球分布

接受默认值并点击“下一步：网络”

Cosmos DB - 网络

接受默认值并点击“下一步：备份策略”
选择“定期”备份策略
选择“本地冗余备份存储”

Cosmos DB - 备份策略

点击“下一步：加密”

Cosmos DB - 加密

点击“审核并创建”开始验证

Cosmos DB - 验证

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

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

在设置部分中，选择“功能”，然后选择“NoSQL API 的矢量搜索”
在打开的面板中，单击启用按钮

创建 Azure Cosmos DB eShop 数据库和 Products 容器
单击 eShop 旁边的“...”以显示上下文菜单，然后选择“新建容器”以在 eShop 数据库中创建“carts”容器。

确保分区键是***“/id”*** （分区键区分大小写）

展开“容器向量策略”，点击“添加向量嵌入”按钮

Cosmos DB - 创建数据库

创建购物车容器

Cosmos DB - 创建数据库

存储帐户

创建存储帐户来存储产品图像

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

存储 - 基础知识

存储 - 高级

存储 - 网络

存储 - 数据保护

存储 - 加密

存储-验证

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

在 Azure 中创建虚拟机或使用本地计算机
从https://nodejs.org/en/download安装 node.js v22.13.1 (LTS)
从https://code.visualstudio.com/download安装 Visual Studio Code x64 1.97.0
从https://git-scm.com/downloads安装 Git 2.47.12 x64
从https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-9.0.102-windows-x64-installer安装 .NET SDK x64 v9.0.102
打开终端窗口并添加 nuget 源

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

如有必要，请更改 Windows 计算机的 PowerShell 执行策略。以管理员模式打开 Powershell 窗口并运行以下命令

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

如果需要，安装 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

打开终端窗口并克隆存储库：

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

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

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

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

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

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

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

在 Azure 门户中创建应用程序注册
在 Azure 门户中创建应用程序机密
您需要允许您的应用访问 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

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

Cosmos DB - RBAC

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

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

存储 - 访问控制

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

存储 - Blob 数据贡献者

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

存储 - 角色分配

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

存储 - 角色分配

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

存储 - 创建容器

存储 - 上传文件

存储 - 已上传的文件

使用 dotnet build 构建 webapi 后端项目

cd webapi dotnet build

Dotnet 构建 18. 在您的次要区域虚拟机（澳大利亚东部）上，使用您的主要区域（美国东部 2）中的套接字服务器的 IP 地址修改 .env 文件

socket_server_ip

该项目未内置身份验证。用户邮箱地址已硬编码在 /nextjs/models/constants.ts 中。请根据你的演示需求进行修改。

npm 运行构建

在 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

构建 nextjs 前端项目

cd nextjs npm run build

npm 运行构建

填充产品目录

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

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

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

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

Cosmos - 填充产品

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

Cosmos - 产品

演示脚本

演示初始化：

在你的开发计算机上，启动 mcp 服务器

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

启动前端项目

NextJS 前端（商店前端）
- cd nextjs
- npm 启动

或者，打开命令提示符并使用以下命令启动 MCP 检查器：npx -y @modelcontextprotocol/inspector

演示步骤：

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

Azure Cosmos DB MCP Server

Azure Cosmos DB MCP 客户端和服务器

Azure 体系结构Azure Architecture

参考

分步演练

安装

填充产品目录

演示脚本

Resources

New MCP Servers

Latest Blog Posts

MCP directory API