内容
# Azure Cosmos DB MCP 客户端与服务器
该仓库包含一个项目，展示如何为 Azure Cosmos DB 创建 MCP 服务器和客户端。该项目分为两个部分：
- 前端应用：NextJS 15 应用，展示产品目录，并具有一个 AI 助手，帮助用户在目录中查找产品和获取过去的订单
- MCP 服务器组件，连接到 Azure Cosmos DB NoSQL 数据库，负责从数据库中读取产品和订单。
## Azure 架构
- 一个存储产品目录的 Azure Cosmos DB NoSQL 数据库
- 一个作为 MCP 服务器组件的 node.js 服务器
## 参考资料
- [为 NoSQL 创建 Azure Cosmos DB 账户](https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/quickstart-portal)
- [创建 Azure 存储账户](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal)
- [创建 Windows 虚拟机](https://learn.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-portal)
- [Windows 执行策略](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.5)
## 步骤指南
### 安装
**Azure Cosmos DB**
在 Azure 门户中，创建一个 Azure Cosmos DB NoSQL 账户。
- 为您的 Azure Cosmos DB 账户提供一个唯一的名称。我们将在本指南的其余部分使用 cosmos-eastus2-nosql-2。
- 点击“下一步：全球分布”
- 接受默认值并点击“下一步：网络”
- 接受默认值并点击“下一步：备份策略”
- 选择“定期”备份策略
- 选择“本地冗余备份存储”
- 点击“下一步：加密”
- 点击“审核并创建”以开始验证
- 点击“创建”以开始创建 Azure Cosmos DB 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 源：
```sh
dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
```
7. 如果需要，修改 Windows 计算机的 PowerShell 执行策略。以 **管理员模式** 打开 PowerShell 窗口并运行以下命令：
```sh
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
8. 如果需要，安装 nuget、powershell、az cli 和 az 模块：
```sh
# 安装 az cli
winget install -e --id Microsoft.AzureCLI
# 安装 nuget 并引用 nuget 源
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
# 更新到最新的 Powershell 版本（截至撰写时为 7.5）
winget install --id Microsoft.PowerShell --source winget
# 安装 az 模块
Install-Module -Name Az -Repository PSGallery -Force -AllowClobber
```
9. 打开终端窗口并克隆仓库：
```sh
git clone https://github.com/patrice-truong/cosmosdb-mcp.git
cd cosmosdb-mcp
```
10. 导航到 nextjs 文件夹并安装依赖：
```sh
cd cosmosdb-mcp/nextjs
npm install --legacy-peer-deps
```
11. 在 nextjs 文件夹中，创建并配置一个 .env 文件，内容如下：
```sh
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：
```sh
az login
az account show --query tenantId -o tsv
```
13. 在 webapi 文件夹中，配置 appsettings.json 文件，并将 tenant_id 替换为上一步中获得的值：
```sh
{
"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 门户中创建一个应用注册
15. 在 Azure 门户中创建一个应用密钥
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 |
```sh
$SubscriptionId = "<subscription-id>" # Azure 订阅 ID
$AccountName = "<cosmosdb-account-name>" # Cosmos DB 账户名称
$ResourceGroupName = "<resource-group-name>" # Cosmos DB 账户的资源组名称
$PrincipalId = "<principal-id>" # 在 Entra ID 中注册的应用的对象 ID
```
17. 打开 PowerShell 提示符，运行 Connect-AzAccount 并执行 ./set_rbac.ps1
18. 允许您的应用（或虚拟机）访问存储账户
- 在 Azure 门户中，转到您的存储账户
- 在菜单中选择访问控制 (IAM)
- 点击“添加角色分配”
- 在过滤文本框中，输入“Storage Blob Data Contributor”
- 点击“成员”
- 选择您的应用名称
- 点击“选择”按钮
- 点击“审核并分配”
19. 创建一个容器并将“azure-storage”文件夹的内容复制到您的存储账户
20. 使用 dotnet build 构建 webapi 后端项目
```sh
cd webapi
dotnet build
```
18. 在您的次要区域虚拟机（澳大利亚东部）中，使用主区域（东美国 2）中套接字服务器的 IP 地址修改 .env 文件
19. 此项目中没有内置身份验证。用户电子邮件在 /nextjs/models/constants.ts 中硬编码。请根据您的演示需求进行更改
19. 在 mcp-server 和 nextjs 文件夹中，将 .env.template 复制到 .env，并根据您的演示需求修改值
```json
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 前端项目
```sh
cd nextjs
npm run build
```
## 填充产品目录
在本节中，我们将从 populate/catalog.json 文件读取产品目录，并填充 Azure Cosmos DB NoSQL 数据库。
1. 修改 appsettings.json，使用您的 cosmosdb 账户名称和
```json
{
"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 服务器
```sh
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。
2. 点击右上角的 AI 助手图标
3. 输入“我对背包感兴趣”（产品列表会刷新并显示背包列表）
4. 输入“获取我的订单”（订单列表会刷新并显示订单列表）
连接信息
猜你喜欢
暂无推荐服务器