FreshMCP

Fornece uma interface MCP para operações do FreshMCP usando Azure Cosmos DB e AI Search.

Documentação

FreshMCP

Um serviço baseado em Python que fornece uma interface de Message Control Protocol (MCP) para operações do FreshMCP usando Azure Cosmos DB e AI Search.

Visão Geral

O FreshMCP é um serviço abrangente que fornece interfaces padronizadas para interagir com os serviços do Azure:

Operações do Cosmos DB

Gerenciamento de contêineres (criar, listar, excluir)
Operações de itens (criar, ler, atualizar, excluir, consultar)

Operações do AI Search

Criar índice
Listar índices
Excluir índice

Arquitetura e Fluxo

Arquitetura do 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

Fluxo de Solicitações

Solicitação do Cliente: VSCode/Cursor ou aplicação web envia a solicitação para o APIM
Processamento do APIM:
- Autenticação e autorização
- Limitação de taxa e throttling
- Roteamento de solicitações com base no tipo de serviço
Processamento do Agente MCP:
- Execução de ferramentas com base no tipo de solicitação
- Operações específicas do serviço
- Formatação de respostas
Interação com os Serviços do Azure:
- Chamadas diretas de API para os serviços do Azure
- Recuperação e manipulação de dados
- Coleta de telemetria

Configuração do APIM

O Azure API Management (APIM) atua como o gateway central para todas as comunicações dos agentes MCP:

Autenticação: Autenticação baseada em chave de assinatura
Limitação de Taxa: Limites configuráveis por assinatura
Roteamento: Roteamento inteligente para os agentes MCP apropriados
Monitoramento: Análises e monitoramento integrados
Cache: Cache de respostas para melhor desempenho

Comunicação dos Agentes MCP

Cada agente MCP se comunica por meio do protocolo Server-Sent Events (SSE):

Agente do Cosmos DB: Gerencia todas as operações de banco de dados
Agente de Busca: Gerencia as operações de índice do AI Search

Pré-requisitos

Python 3.11 ou superior
Azure CLI
Azure Developer CLI (azd)
Docker
Assinatura do Azure com as permissões apropriadas

Configuração de Desenvolvimento Local

Clone o repositório:
Instale o uv (se ainda não estiver instalado):

pip install uv

Crie e ative um ambiente virtual usando o uv:

uv venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

Instale as dependências usando o uv:

uv sync

Configure as variáveis de ambiente:

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

Endpoints do Servidor

Inicie o servidor MCP do Cosmos DB:

python -m src.cosmos.mcp.server

O servidor será iniciado em http://localhost:8001/cosmos/sse

Inicie o servidor MCP do AI Search:

python -m src.search.mcp.server

O servidor será iniciado em http://localhost:8002/search/sse

Configurando o MCP no cliente

Adicione as ferramentas de qualquer servidor MCP ao VSCode ou Cursor fornecendo um arquivo de configuração JSON abaixo:

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

Implantação com Azure Developer CLI (azd)

Inicialize o azd (se ainda não tiver feito):

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

Implante a aplicação:

azd up

Isso irá:

Empacotar os projetos/serviços
Provisionar todos os serviços do Azure necessários
Compilar e enviar as imagens Docker para o Azure Container Registry
Implantar as imagens no Azure Container Apps

Configurando RBAC para Serviços do Azure

RBAC do Cosmos DB

Conceda a função RBAC necessária à identidade gerenciada atribuída ao 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 "/"

Observação: A identidade gerenciada atribuída ao sistema é atribuída ao seu Container App do cosmosdb por padrão.

RBAC do AI Search

Conceda a função RBAC necessária à identidade gerenciada atribuída ao 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>

Observação: A identidade gerenciada atribuída ao sistema é atribuída ao seu Container App de busca por padrão.

Variáveis de Ambiente

Variáveis de ambiente necessárias (use uma tabela para listá-las):

Variável	Descrição	Obrigatória
`AZURE_TENANT_ID`	ID do locatário (tenant) do Azure	Sim (se usar Service Principal)
`AZURE_CLIENT_ID`	ID do cliente para autenticação	Sim (se usar Service Principal)
`AZURE_CLIENT_SECRET`	Segredo do cliente para autenticação	Sim (se usar Service Principal)
`APPLICATIONINSIGHTS_CONNECTION_STRING`	String de conexão do Application Insights	Não

Monitoramento

Para monitorar sua aplicação:

azd monitor -e dev

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça commit das suas alterações
Envie para o branch
Crie um Pull Request

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.