# FreshMCP

A Python-based service that provides a Message Control Protocol (MCP) interface for FreshMCP operations using Azure Cosmos DB and AI Search.

## Overview

FreshMCP is a comprehensive service that provides standardized interfaces for interacting with Azure services:

### Cosmos DB Operations

- Container management (create, list, delete)
- Item operations (create, read, update, delete, query)

### AI Search Operations

- Create index
- List indexes
- Delete index

---

## Architecture & Flow

### System Architecture

```mermaid
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
```

### Request Flow

1. **Client Request**: VSCode/Cursor or web application sends request to APIM
2. **APIM Processing**:
   - Authentication and authorization
   - Rate limiting and throttling
   - Request routing based on service type
3. **MCP Agent Processing**:
   - Tool execution based on request type
   - Service-specific operations
   - Response formatting
4. **Azure Service Interaction**:
   - Direct API calls to Azure services
   - Data retrieval and manipulation
   - Telemetry collection

### APIM Configuration

The Azure API Management (APIM) serves as the central gateway for all MCP agent communications:

- **Authentication**: Subscription key-based authentication
- **Rate Limiting**: Configurable limits per subscription
- **Routing**: Intelligent routing to appropriate MCP agents
- **Monitoring**: Built-in analytics and monitoring
- **Caching**: Response caching for improved performance

### MCP Agent Communication

Each MCP agent communicates via Server-Sent Events (SSE) protocol:

- **Cosmos DB Agent**: Handles all database operations
- **Search Agent**: Manages AI Search index operations

---

## Prerequisites

- Python 3.11 or higher
- Azure CLI
- Azure Developer CLI (azd)
- Docker
- Azure subscription with appropriate permissions

---

## Local Development Setup

1. Clone the repository:

2. Install uv (if not already installed):

```bash
pip install uv
```

3. Create and activate a virtual environment using uv:

```bash
uv venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate
```

4. Install dependencies using uv:

```bash
uv sync
```

5. Set up environment variables:

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

### Server Endpoints

**Start the Cosmos DB MCP server:**

```bash
python -m src.cosmos.mcp.server
```

> The server will start on `http://localhost:8001/cosmos/sse`

**Start the AI Search MCP server:**

```bash
python -m src.search.mcp.server
```

> The server will start on `http://localhost:8002/search/sse`

---

## Setting up the MCP to the client

Add the tools of any MCP server to VSCode or Cursor providing a JSON configuration file below:

**VSCode**:

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

**Cursor**:

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

---

## Deployment with Azure Developer CLI (azd)

1. Initialize azd (if not already done):

```bash
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
```

2. Deploy the application:

```bash
azd up
```

This will:

- Packages the project/services
- Provision all the necessary Azure services
- Build and push the Docker images to the Azure Container Registry
- Deploy the images to the Azure Container Apps

---

## Setting up RBAC for Azure Services

### Cosmos DB RBAC

1. Grant the necessary RBAC role to the system-assigned managed identity:

```bash
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 "/"
```

> **Note**: The system-assigned managed identity is assigned to your cosmosdb Container App by default.

### AI Search RBAC

1. Grant the necessary RBAC role to the system-assigned managed identity:

```bash
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>
```

> **Note**: The system-assigned managed identity is assigned to your search Container App by default.

---

## Environment Variables

Required environment variables (use a table to list them):

| Variable | Description | Required |
|----------|-------------|----------|
| `AZURE_TENANT_ID` | Azure tenant ID | Yes (If using Service Principal) |
| `AZURE_CLIENT_ID` | Client ID for authentication | Yes (If using Service Principal) |
| `AZURE_CLIENT_SECRET` | Client secret for authentication | Yes (If using Service Principal) |
| `APPLICATIONINSIGHTS_CONNECTION_STRING` | Application Insights connection string | No |

---

## Monitoring

To monitor your application:

```bash
azd monitor -e dev
```

---

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

---

## License

This project is licensed under the MIT License - see the LICENSE file for details.