Cliente y servidor de MCP de Azure Cosmos DB

Este repositorio contiene un proyecto que muestra cómo crear un servidor y un cliente MCP para Azure Cosmos DB. El proyecto se divide en dos partes:

• Aplicación frontend: Aplicación NextJS 15 que muestra un catálogo de productos y cuenta con un asistente de IA que ayuda a los usuarios a encontrar productos en el catálogo y obtener pedidos anteriores.

• un componente de servidor MCP, conectado a la base de datos NoSQL de Azure Cosmos DB y responsable de leer productos y pedidos de la base de datos.

Arquitectura de Azure

• una base de datos NoSQL de Azure Cosmos DB que almacena el catálogo de productos

• un servidor node.js que sirve como componente de servidor MCP

Related MCP server: Azure Cosmos DB MCP Server

Referencias

• Crear una cuenta de Azure Cosmos DB para NoSQL

• Crear una cuenta de Azure Storage

• Crear una máquina virtual de Windows

• Políticas de ejecución de Windows

Tutorial paso a paso

Instalación

Azure Cosmos DB

En el portal de Azure, cree una cuenta de Azure Cosmos DB para NoSQL.

• Asigne un nombre único a su cuenta de Azure Cosmos DB. Usaremos cosmos-eastus2-nosql-2 en el resto de este tutorial.

• Haga clic en "Siguiente: Distribución global"

• Acepte los valores predeterminados y haga clic en "Siguiente: Redes".

• Acepte los valores predeterminados y haga clic en "Siguiente: Política de respaldo"

• Seleccione la política de copias de seguridad "Periódico"

• Seleccione "Almacenamiento de respaldo con redundancia local"

• Haga clic en "Siguiente: Cifrado"

• Haga clic en "Revisar y crear" para iniciar la validación.

• Haga clic en "Crear" para iniciar la creación de la cuenta de Azure Cosmos DB para NoSQL

Para este proyecto, deberá habilitar la compatibilidad con vectores en la cuenta de Azure Cosmos DB.

• En la sección de configuración, seleccione Características y luego "Búsqueda vectorial para API NoSQL".

• En el panel que se abre, haga clic en el botón Habilitar

• Cree la base de datos de Azure Cosmos DB eShop y el contenedor Productos

• Haga clic en "..." junto a eShop para mostrar el menú contextual y seleccione "Nuevo contenedor" para crear el contenedor "carritos" en la base de datos de eShop.

Asegúrese de que la clave de partición sea "/id" (la clave de partición distingue entre mayúsculas y minúsculas)

Expanda "Política de vectores de contenedores" y haga clic en el botón "Agregar incrustación de vectores".

• Crear el contenedor de carritos

Cuenta de almacenamiento

1. Crea una cuenta de almacenamiento para guardar las imágenes del producto

Para obtener más detalles, consulte la documentación: https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal

**Requisitos previos para la instalación del software**

1. Cree una máquina virtual en Azure o use su computadora local

2. Instale node.js v22.13.1 (LTS) desde https://nodejs.org/en/download

3. Instale Visual Studio Code x64 1.97.0 desde https://code.visualstudio.com/download

4. Instale Git 2.47.12 x64 desde https://git-scm.com/downloads

5. Instale .NET SDK x64 v9.0.102 desde https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/sdk-9.0.102-windows-x64-installer

6. Abra una ventana de terminal y agregue la fuente NuGet con

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

7. Si es necesario, modifique las políticas de ejecución de PowerShell para equipos Windows. Abra una ventana de PowerShell en modo administrador y ejecute este comando.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

8. Si es necesario, instale los módulos Nuget, PowerShell, Az CLI y 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

9. Abra una ventana de terminal y clone el repositorio:

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

10. Navegue a la carpeta nextjs e instale las dependencias

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

11. En la carpeta nextjs, cree y configure un archivo .env con los siguientes valores:

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. Obtén tu ID de inquilino. Puedes obtenerlo con este comando:

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

13. En la carpeta webapi, configure el archivo appsettings.json y reemplace el tenant_id con el valor obtenido en el paso anterior:

{
  "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. Crear un registro de aplicación en el Portal de Azure

15. Crear un secreto de aplicación en el Portal de Azure

16. Necesitará permitir que su aplicación acceda a Azure Cosmos DB. Recupere los cuatro identificadores mencionados a continuación y modifique el archivo "populate/set_rbac.ps1".

$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. Abra un símbolo del sistema de PowerShell, ejecute Connect-AzAccount y ejecute ./set_rbac.ps1

18. Permitir que su aplicación (o máquina virtual) acceda a la cuenta de almacenamiento

• En el portal de Azure, vaya a su cuenta de almacenamiento

• Seleccione Control de acceso (IAM) en el menú

• Haga clic en "Agregar asignación de rol"

• En el cuadro de texto del filtro, escriba "Contribuidor de datos de blobs de almacenamiento".

• Haga clic en "Miembros"

• Seleccione el nombre de su aplicación

• Haga clic en el botón "Seleccionar"

• Haga clic en "Revisar y asignar"

19. Cree un contenedor y copie el contenido de la carpeta "azure-storage" a su cuenta de almacenamiento

20. Cree un proyecto backend de webapi con dotnet build

cd webapi
dotnet build

18. En la máquina virtual de su región secundaria (Australia Este), modifique el archivo .env con la dirección IP del servidor de sockets de su región principal (East US 2).

19. Este proyecto no incluye autenticación. El correo electrónico del usuario está predefinido en /nextjs/models/constants.ts. Modifíquelo para adaptarlo a las necesidades de su demostración.

19. En las carpetas mcp-server y nextjs, copie .env.template a .env y modifique los valores para adaptarlos a sus necesidades de demostración

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. Construir un proyecto frontend de nextjs

cd nextjs
npm run build

Completar el catálogo de productos

En esta sección, leeremos el catálogo de productos del archivo populate/catalog.json y completaremos la base de datos de Azure Cosmos DB para NoSQL.

1. Modifique appsettings.json con el nombre de su cuenta cosmosdb y

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

2. Abra una ventana de terminal, navegue hasta la carpeta de población, ejecute az login y luego dotnet run

3. Verifique que el contenedor de Azure Cosmos DB se haya rellenado correctamente

Guión de demostración

Inicialización de demostración:

3. En su computadora de desarrollo, inicie el servidor mcp

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

3. Iniciar el proyecto frontend

• Front-end de NextJS (tienda virtual)

  • cd nextjs

  • inicio de npm

4. Opcionalmente, abra un símbolo del sistema e inicie el inspector MCP con este comando: npx -y @modelcontextprotocol/inspector

Pasos de demostración:

1. Vaya a http://localhost:3002 .

2. Haga clic en el ícono del Asistente de IA en la esquina superior derecha

3. Ingresa "Me interesan las mochilas" (la lista de productos se actualiza con una lista de mochilas)

4. Ingresa a "Obtener mis pedidos" (la lista de pedidos se actualiza con una lista de pedidos)