FreshMCP

Proporciona una interfaz MCP para operaciones de FreshMCP usando Azure Cosmos DB y AI Search.

Documentación

FreshMCP

Un servicio basado en Python que proporciona una interfaz de Protocolo de Control de Mensajes (MCP) para operaciones de FreshMCP utilizando Azure Cosmos DB y AI Search.

Descripción general

FreshMCP es un servicio integral que proporciona interfaces estandarizadas para interactuar con los servicios de Azure:

Operaciones de Cosmos DB

Gestión de contenedores (crear, listar, eliminar)
Operaciones de elementos (crear, leer, actualizar, eliminar, consultar)

Operaciones de AI Search

Crear índice
Listar índices
Eliminar índice

Arquitectura y flujo

Arquitectura del sistema

graph TB
    subgraph "Client Layer"
        A[VSCode/Cursor Client]
        B[Web Application]
    end

    subgraph "APIM Gateway"
        C[Azure API Management]
        D[Rate Limiting]
        E[Authentication]
        F[Request Routing]
    end

    subgraph "MCP Agent Layer"
        G[Cosmos DB MCP Agent]
        H[Search MCP Agent]
    end

    subgraph "Azure Services"
        J[Cosmos DB]
        K[AI Search]
    end

    A --> C
    B --> C
    C --> D
    C --> E
    C --> F
    F --> G
    F --> H
    G --> J
    H --> K

Flujo de solicitudes

Solicitud del cliente: VSCode/Cursor o la aplicación web envía la solicitud a APIM
Procesamiento de APIM:
- Autenticación y autorización
- Limitación y control de velocidad
- Enrutamiento de solicitudes según el tipo de servicio
Procesamiento del agente MCP:
- Ejecución de herramientas según el tipo de solicitud
- Operaciones específicas del servicio
- Formato de respuesta
Interacción con los servicios de Azure:
- Llamadas directas a la API de los servicios de Azure
- Recuperación y manipulación de datos
- Recopilación de telemetría

Configuración de APIM

Azure API Management (APIM) actúa como la puerta de enlace central para todas las comunicaciones de los agentes MCP:

Autenticación: Autenticación basada en clave de suscripción
Limitación de velocidad: Límites configurables por suscripción
Enrutamiento: Enrutamiento inteligente a los agentes MCP apropiados
Monitoreo: Análisis y monitoreo integrados
Almacenamiento en caché: Almacenamiento en caché de respuestas para mejorar el rendimiento

Comunicación del agente MCP

Cada agente MCP se comunica mediante el protocolo Server-Sent Events (SSE):

Agente de Cosmos DB: Maneja todas las operaciones de la base de datos
Agente de búsqueda: Gestiona las operaciones de índice de AI Search

Requisitos previos

Python 3.11 o superior
Azure CLI
Azure Developer CLI (azd)
Docker
Suscripción de Azure con los permisos adecuados

Configuración de desarrollo local

Clonar el repositorio:
Instalar uv (si aún no está instalado):

pip install uv

Crear y activar un entorno virtual usando uv:

uv venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

Instalar las dependencias usando uv:

uv sync

Configurar las variables de entorno:

cp .env.example .env
# Edit .env with your Azure credentials and service settings

Puntos finales del servidor

Iniciar el servidor MCP de Cosmos DB:

python -m src.cosmos.mcp.server

El servidor se iniciará en http://localhost:8001/cosmos/sse

Iniciar el servidor MCP de AI Search:

python -m src.search.mcp.server

El servidor se iniciará en http://localhost:8002/search/sse

Configuración del MCP en el cliente

Agregue las herramientas de cualquier servidor MCP a VSCode o Cursor proporcionando un archivo de configuración JSON a continuación:

VSCode:

{
  "servers": {
    "cosmos_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8001/cosmos/sse"
    },
    "search_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8002/search/sse"
    }
  }
}

Cursor:

{
  "mcpServers": {
    "cosmos_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8001/cosmos/sse"
    },
    "search_mcp_local": {
      "type": "sse",
      "url": "http://localhost:8002/search/sse"
    }
  }
}

Implementación con Azure Developer CLI (azd)

Inicializar azd (si aún no se ha hecho):

azd init -e dev -l eastus

# -e dev is optional, it will create a new dev environment

# -l eastus is optional, it will create the resources in the eastus region

Implementar la aplicación:

azd up

Esto:

Empaquetará los proyectos/servicios
Aprovisionará todos los servicios de Azure necesarios
Creará y enviará las imágenes de Docker al Azure Container Registry
Implementará las imágenes en Azure Container Apps

Configuración de RBAC para los servicios de Azure

RBAC de Cosmos DB

Otorgar el rol RBAC necesario a la identidad administrada asignada por el sistema:

az cosmosdb sql role assignment create \
    --account-name <your-cosmos-account> \
    --resource-group <your-resource-group> \
    --role-definition-id "00000000-0000-0000-0000-000000000002" \
    --principal-id <managed-identity-principal-id> \
    --scope "/"

Nota: La identidad administrada asignada por el sistema se asigna a su Container App de cosmosdb de forma predeterminada.

RBAC de AI Search

Otorgar el rol RBAC necesario a la identidad administrada asignada por el sistema:

az role assignment create \
    --assignee <managed-identity-principal-id> \
    --role "Search Service Contributor" \
    --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service-name>

Nota: La identidad administrada asignada por el sistema se asigna a su Container App de búsqueda de forma predeterminada.

Variables de entorno

Variables de entorno requeridas (use una tabla para listarlas):

Variable	Descripción	Requerida
`AZURE_TENANT_ID`	ID de inquilino de Azure	Sí (si se usa una entidad de servicio)
`AZURE_CLIENT_ID`	ID de cliente para autenticación	Sí (si se usa una entidad de servicio)
`AZURE_CLIENT_SECRET`	Secreto de cliente para autenticación	Sí (si se usa una entidad de servicio)
`APPLICATIONINSIGHTS_CONNECTION_STRING`	Cadena de conexión de Application Insights	No

Monitoreo

Para monitorear su aplicación:

azd monitor -e dev

Contribuciones

Haga un fork del repositorio
Cree una rama de características
Confirme sus cambios
Envíe los cambios a la rama
Cree una solicitud de extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.