Skip to main content
Glama
Sign In
enesjakozh

Azure Cosmos DB MCP Server

by patrice-truong
GitHub
TypeScript
MIT License
1
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Provides a backend implementation for the MCP server using .NET, connecting to Azure Cosmos DB for database operations

  • Serves as the foundation for the MCP server component, connecting to Azure Cosmos DB to read products and orders data

  • Integrates with Azure OpenAI services for text embeddings and the AI Assistant functionality that helps users find products and retrieve order information

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

Referencias

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
  1. 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
  1. 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
  1. Abra una ventana de terminal y clone el repositorio:
git clone https://github.com/patrice-truong/cosmosdb-mcp.git cd cosmosdb-mcp
  1. Navegue a la carpeta nextjs e instale las dependencias
cd cosmosdb-mcp/nextjs npm install --legacy-peer-deps
  1. 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>
  1. Obtén tu ID de inquilino. Puedes obtenerlo con este comando:
az login az account show --query tenantId -o tsv
  1. 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>" } }
  1. Crear un registro de aplicación en el Portal de Azure
  2. Crear un secreto de aplicación en el Portal de Azure
  3. 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".
VariableReferencia
ID de suscripciónCosmos DB > Descripción general > Id. de suscripción
Nombre de la cuenta de Azure Cosmos DBcosmos-eastus2-nosql-2
Nombre del grupo de recursosCosmos DB > Descripción general > Nombre del grupo de recursos
Identificación principalId. de objeto de registro de la aplicación
$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
  1. Abra un símbolo del sistema de PowerShell, ejecute Connect-AzAccount y ejecute ./set_rbac.ps1

  1. 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"

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

  1. 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).

  1. 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.

  1. 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
  1. 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", } }
  1. Abra una ventana de terminal, navegue hasta la carpeta de población, ejecute az login y luego dotnet run

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

Guión de demostración

Inicialización de demostración:

  1. En su computadora de desarrollo, inicie el servidor mcp
cd mcp-server npx ts-node src/server.ts
  1. Iniciar el proyecto frontend
  • Front-end de NextJS (tienda virtual)
    • cd nextjs
    • inicio de npm
  1. 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)

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

Servidor Node.js que se conecta a la base de datos NoSQL de Azure Cosmos DB, lo que permite a los usuarios consultar productos y pedidos a través de un Asistente de IA en una aplicación frontend de NextJS.

  1. Arquitectura de Azure
    1. Referencias
      1. Tutorial paso a paso
        1. Instalación
      2. Completar el catálogo de productos
        1. Guión de demostración

          Related MCP Servers

          • Azure MCP Server

            mashriram
            A
            security
            A
            license
            A
            quality
            This server implements the Model Context Protocol for seamless interaction with Azure Blob Storage and Cosmos DB, enabling automatic logging and audit tracking of operations.
            Last updated -
            16
            4
            Python
            MIT License
            • Apple

          • Azure Cosmos DB MCP Server

            robinong79
            -
            security
            A
            license
            -
            quality
            A server that enables LLMs like Claude to interact with Azure Cosmos DB databases through natural language queries, acting as a translator between AI assistants and database systems.
            Last updated -
            JavaScript
            MIT License

          • MCP Math Server

            aem-edge-delivery
            -
            security
            F
            license
            -
            quality
            A Node.js server that processes mathematical calculations and natural language math queries through RESTful API endpoints.
            Last updated -
            JavaScript

          • PlayFab MCP Server

            akiojin
            A
            security
            A
            license
            A
            quality
            A server that enables LLMs (like Claude and VSCode Copilot) to interact with Azure Cosmos DB data through natural language queries, acting as a translator between AI assistants and your database.
            Last updated -
            3
            11
            1
            JavaScript
            MIT License
            • Apple

          View all related MCP servers

          New MCP Servers

          ID: dtf38p20zp