{"id":31366359,"url":"https://github.com/azurecosmosdb/mcptoolkit","last_synced_at":"2025-09-27T10:29:47.779Z","repository":{"id":316449922,"uuid":"1054272417","full_name":"AzureCosmosDB/MCPToolKit","owner":"AzureCosmosDB","description":"An MCP ToolKit enabling agents and agentic apps to work with Azure Cosmos DB. ","archived":false,"fork":false,"pushed_at":"2025-09-24T18:00:53.000Z","size":475,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-24T18:10:20.943Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AzureCosmosDB.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-10T15:50:13.000Z","updated_at":"2025-09-24T18:00:57.000Z","dependencies_parsed_at":"2025-09-24T18:10:42.819Z","dependency_job_id":"a8bad5db-3a9c-40c8-b12b-7f1e7a280c51","html_url":"https://github.com/AzureCosmosDB/MCPToolKit","commit_stats":null,"previous_names":["azurecosmosdb/mcptoolkit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AzureCosmosDB/MCPToolKit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FMCPToolKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FMCPToolKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FMCPToolKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FMCPToolKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AzureCosmosDB","download_url":"https://codeload.github.com/AzureCosmosDB/MCPToolKit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FMCPToolKit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277218545,"owners_count":25781444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-27T02:00:08.978Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-27T10:29:44.353Z","updated_at":"2025-09-27T10:29:47.773Z","avatar_url":"https://github.com/AzureCosmosDB.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Azure Cosmos DB MCP Toolkit\n\nA Model Context Protocol (MCP) toolkit that provides seamless integration with Azure Cosmos DB and Azure OpenAI for document querying, vector search, and schema inspection through AI agents. **Now with full containerization support for Azure Container Apps!**\n\n## Overview\n\nThis Azure Cosmos DB MCP Toolkit is a production-ready MCP Server that enables AI agents to interact with Azure Cosmos DB. It supports traditional document queries, full-text search, vector similarity search using Azure OpenAI embeddings, and schema discovery. All operations use Entra ID (Azure AD) authentication for secure, enterprise-grade access to Azure services.\n\n**Key Features:**\n- 🔍 Document querying and full-text search\n- 🧠 AI-powered vector similarity search with Azure OpenAI embeddings\n- 📊 Container schema discovery and analysis\n- 🔐 Secure Entra ID authentication with Managed Identity support\n- 🏷️ Model Context Protocol integration for AI agents\n- ⚡ Real-time query execution with comprehensive error handling\n- 🐳 **Full containerization support for Azure Container Apps**\n- 🚀 **One-click deployment to Azure with automated CI/CD**\n- � **Local development with Docker Compose and Cosmos DB emulator**\n\n## 🚀 Quick Deploy to Azure\n\nGet started instantly with a complete Azure infrastructure deployment that includes all necessary resources and RBAC configuration:\n\n[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzureCosmosDB%2FMCPToolKit%2Fmain%2Finfrastructure%2Fdeploy-all-resources.json)\n\n[![Deploy with GitHub Actions](https://github.com/AzureCosmosDB/MCPToolKit/actions/workflows/deploy-complete.yml/badge.svg)](https://github.com/AzureCosmosDB/MCPToolKit/actions/workflows/deploy-complete.yml)\n\n\u003e **⚠️ Important**: If your Azure subscription has policies requiring an \"owner\" tag, you'll need to provide an **Owner Tag** value during deployment. This is typically your email address or username.\n\n**What gets deployed:**\n- ✅ **Azure Cosmos DB** (serverless) with sample database and container\n- ✅ **Azure OpenAI** service with text-embedding-ada-002 deployment\n- ✅ **Azure Container Registry** for your container images\n- ✅ **Azure Container Apps** environment with managed identity\n- ✅ **Complete RBAC setup** with all necessary permissions\n- ✅ **Log Analytics workspace** for monitoring and diagnostics\n\n### Alternative Deployment Methods\n\n#### PowerShell Quick Deploy (Recommended for Advanced Users)\n```powershell\n# Download and run the complete deployment script\nInvoke-WebRequest -Uri \"https://raw.githubusercontent.com/AzureCosmosDB/MCPToolKit/main/scripts/Deploy-Complete.ps1\" -OutFile \"Deploy-Complete.ps1\"\n\n# Run with your configuration\n.\\Deploy-Complete.ps1 `\n    -ResourceGroupName \"rg-mcp-toolkit\" `\n    -Location \"East US\" `\n    -PrincipalId \"your-user-object-id\" `\n    -PrincipalType \"User\"\n```\n\n#### Linux/Mac Quick Deploy\n```bash\n# Download and run the complete deployment script\ncurl -O https://raw.githubusercontent.com/AzureCosmosDB/MCPToolKit/main/scripts/deploy-complete.sh\nchmod +x deploy-complete.sh\n\n# Set environment variables and run\nexport RESOURCE_GROUP_NAME=\"rg-mcp-toolkit\"\nexport LOCATION=\"East US\"\nexport PRINCIPAL_ID=\"your-user-object-id\"\nexport PRINCIPAL_TYPE=\"User\"\n./deploy-complete.sh\n```\n\n#### GitHub Actions Workflow Deploy\nFor automated deployment with full CI/CD integration:\n\n1. **Fork this repository** to your GitHub account\n2. **Set up repository secrets:**\n   - `AZURE_CREDENTIALS` - Service principal JSON for Azure access\n   - `AZURE_SUBSCRIPTION_ID` - Your Azure subscription ID\n\n3. **Run the workflow:**\n   - Go to Actions → \"Deploy Complete Infrastructure to Azure\"\n   - Click \"Run workflow\"\n   - Enter your deployment parameters\n   - Monitor progress and get deployment summary\n\n\u003e **💡 Tip**: Get your user object ID by running: `az ad signed-in-user show --query id -o tsv`\n\n## Deployment Options\n\n### 🚀 Option 1: Azure Container Apps (Recommended for Production)\n\nDeploy to Azure Container Apps with automated scaling, managed identity, and enterprise security.\n\n#### Prerequisites\n- Azure CLI installed\n- Docker installed\n- Azure subscription with appropriate permissions\n\n#### Quick Deployment\n```powershell\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd MCPToolKit\n\n# Run the deployment script\n.\\scripts\\deploy.ps1 `\n    -ResourceGroupName \"rg-mcp-toolkit\" `\n    -Location \"East US\" `\n    -CosmosEndpoint \"https://your-cosmosdb-account.documents.azure.com:443/\" `\n    -OpenAIEndpoint \"https://your-openai-service.openai.azure.com/\" `\n    -OpenAIEmbeddingDeployment \"text-embedding-ada-002\"\n```\n\nThis will:\n- ✅ Create Azure Container Registry\n- ✅ Build and push Docker image\n- ✅ Deploy to Azure Container Apps with managed identity\n- ✅ Configure health checks and auto-scaling\n- ✅ Set up monitoring with Log Analytics\n\n#### Manual Azure Deployment Steps\n\n1. **Build and push the container image:**\n```bash\n# Login to Azure and create ACR\naz login\naz group create --name rg-mcp-toolkit --location eastus\naz acr create --resource-group rg-mcp-toolkit --name mcptoolkitacr --sku Basic --admin-enabled true\n\n# Build and push image\naz acr login --name mcptoolkitacr\ndocker build -t mcptoolkitacr.azurecr.io/mcp-toolkit:latest .\ndocker push mcptoolkitacr.azurecr.io/mcp-toolkit:latest\n```\n\n2. **Deploy the infrastructure:**\n```bash\naz deployment group create \\\n    --resource-group rg-mcp-toolkit \\\n    --template-file infrastructure/main.bicep \\\n    --parameters \\\n        containerImage=mcptoolkitacr.azurecr.io/mcp-toolkit:latest \\\n        cosmosEndpoint=\"https://your-cosmosdb-account.documents.azure.com:443/\" \\\n        openaiEndpoint=\"https://your-openai-service.openai.azure.com/\" \\\n        openaiEmbeddingDeployment=\"text-embedding-ada-002\"\n```\n\n3. **Configure RBAC permissions:** (see Security Setup section below)\n\n### 🐳 Option 2: Local Development with Docker Compose\n\nPerfect for development, testing, and local AI agent integration.\n\n#### Prerequisites\n- Docker and Docker Compose installed\n- Azure OpenAI service (for vector search features)\n\n#### Quick Start\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd MCPToolKit\n\n# Set up environment variables\ncopy .env.example .env\n# Edit .env with your Azure OpenAI credentials\n\n# Start the local environment\ndocker-compose up -d\n\n# The MCP server will be available at http://localhost:8080\n# Cosmos DB emulator will be available at https://localhost:8081\n```\n\nThis includes:\n- ✅ Azure Cosmos DB Linux emulator\n- ✅ MCP Toolkit container\n- ✅ Automatic container networking\n- ✅ Persistent data storage\n- ✅ Health checks and restart policies\n\n### Development Configuration\n\nCreate a `.env` file in the project root:\n```env\n# Azure OpenAI Configuration (required for vector search)\nOPENAI_ENDPOINT=https://your-openai-service.openai.azure.com/\nOPENAI_EMBEDDING_DEPLOYMENT=text-embedding-ada-002\n\n# For local development with emulator, Cosmos endpoint is automatically configured\n# COSMOS_ENDPOINT=https://cosmos-emulator:8081/\n```\n\n#### Cosmos DB Emulator Certificate Setup (For SSL)\n\nThe Cosmos DB emulator uses a self-signed certificate. For production-like testing:\n\n**Windows (PowerShell)**:\n```powershell\n.\\scripts\\Setup-CosmosCert.ps1\n```\n\n**Linux/macOS (Bash)**:\n```bash\n./scripts/setup-cosmos-cert.sh\n```\n\nThis downloads and installs the emulator's certificate for SSL connections.\n\n### 📱 Option 3: Traditional Local Development\n\nFor developers who prefer running .NET directly.\n\n```bash\n# Set environment variables\nexport COSMOS_ENDPOINT=\"https://your-cosmosdb-account.documents.azure.com:443/\"\nexport OPENAI_ENDPOINT=\"https://your-openai-service.openai.azure.com/\"\nexport OPENAI_EMBEDDING_DEPLOYMENT=\"text-embedding-ada-002\"\n\n# Build and run\ndotnet restore\ndotnet build\ndotnet run\n```\n\n## CI/CD Pipeline Setup\n\n### GitHub Actions (Included)\n\nThe repository includes a complete GitHub Actions workflow for automated deployment:\n\n1. **Set up repository secrets:**\n   - `AZURE_CREDENTIALS` - Service principal for Azure access\n   - `AZURE_SUBSCRIPTION_ID` - Your Azure subscription ID\n   - `COSMOS_ENDPOINT` - Your Cosmos DB endpoint\n   - `OPENAI_ENDPOINT` - Your Azure OpenAI endpoint  \n   - `OPENAI_EMBEDDING_DEPLOYMENT` - Your embedding deployment name\n\n2. **Trigger deployment:**\n   - Push to `main` branch for automatic deployment\n   - Use `workflow_dispatch` for manual deployment with environment selection\n\n3. **Monitor deployment:**\n   - View progress in GitHub Actions\n   - Check deployment summary with direct links to Azure resources\n\n## Container Configuration\n\n### Environment Variables\n| Variable | Description | Required | Default | Example |\n|----------|-------------|----------|---------|---------|\n| `COSMOS_ENDPOINT` | Azure Cosmos DB endpoint URL | Yes | - | `https://myaccount.documents.azure.com:443/` |\n| `OPENAI_ENDPOINT` | Azure OpenAI service endpoint | Yes* | - | `https://myopenai.openai.azure.com/` |\n| `OPENAI_EMBEDDING_DEPLOYMENT` | Azure OpenAI embedding deployment name | Yes* | - | `text-embedding-ada-002` |\n| `ASPNETCORE_ENVIRONMENT` | ASP.NET Core environment | No | `Production` | `Development` |\n| `ASPNETCORE_URLS` | Application listening URLs | No | `http://+:8080` | `http://+:8080` |\n\n*Required only for vector search functionality\n\n### Docker Compose Environment\nThe Docker Compose setup automatically configures:\n- `COSMOS_ENDPOINT=https://cosmos-emulator:8081/`\n- `COSMOS_EMULATOR_SSL_VERIFY=false` (for development)\n- Network connectivity between containers\n- Volume persistence for Cosmos emulator data\n\n### Health Checks\nThe container includes health check endpoints:\n- **Readiness**: `/health` - Container is ready to receive traffic\n- **Liveness**: `/health` - Container is alive and responsive\n\n### Resource Requirements\n- **CPU**: 0.5 cores (minimum)\n- **Memory**: 1 GB (minimum)\n- **Storage**: Minimal (stateless application)\n\n### Scaling Configuration\n- **Min Replicas**: 1 (can scale to zero when idle)\n- **Max Replicas**: 3 (configurable based on load)\n- **Scale Trigger**: HTTP concurrent requests (10 per replica)\n\n## Supported MCP Tools\n\nThe toolkit provides the following Model Context Protocol (MCP) tools for AI agents:\n\n### Database \u0026 Container Management\n- **`ListDatabases`** - Lists all databases available in the Cosmos DB account\n- **`ListCollections`** - Lists containers (collections) for a specified database\n\n### Document Querying\n- **`GetRecentDocuments`** - Gets the most recent N documents ordered by timestamp (_ts DESC). N must be between 1-20\n- **`FindDocumentByID`** - Finds a specific document by its ID in the specified database/container\n- **`TextSearch`** - Performs full-text search on a specified property using FullTextContains. N must be between 1-20\n\n### Schema Discovery\n- **`GetApproximateSchema`** - Analyzes up to 10 sample documents to infer the container's schema, including property names, data types, and frequency of occurrence\n\n### AI-Powered Vector Search\n- **`VectorSearch`** - Performs semantic vector search using Azure OpenAI embeddings. Finds documents that are semantically similar to the input text. N must be between 1-50\n  - Automatically generates embeddings for search text using Azure OpenAI\n  - Returns results with similarity scores (_score field)\n  - Supports custom property projection (explicit properties only)\n  - No wildcard (`*`) selection allowed - must specify explicit properties\n  - Uses `VectorDistance` function for similarity calculations\n\n## Technical Specifications\n\n### Platform Requirements\n- **.NET 9.0** - Latest .NET runtime for optimal performance\n- **Azure Cosmos DB** - NoSQL database with vector search capabilities\n- **Azure OpenAI** - For embedding generation (text-embedding-ada-002 recommended)\n- **Docker** - For containerization and local development\n\n### Container Configuration\n- **Base Image**: `mcr.microsoft.com/dotnet/aspnet:9.0`\n- **Port**: 8080 (configured for Azure Container Apps compatibility)\n- **Health Endpoint**: `/health` - Returns HTTP 200 when service is ready\n- **Non-root User**: Runs as `appuser` (UID 1000) for security\n\n### Authentication \u0026 Security\n- **DefaultAzureCredential**: Automatic authentication across environments\n  - **Local Development**: Uses `az login` credentials\n  - **Azure Container Apps**: Uses managed identity\n  - **CI/CD**: Supports service principal authentication\n- **RBAC Permissions**: Least privilege access with specific role assignments\n- **HTTPS Enforcement**: TLS 1.2+ for all Azure service connections\n\n## Security Setup\n\n### Azure Container Apps (Managed Identity)\n\nWhen deployed to Azure Container Apps, the application uses a managed identity for secure authentication:\n\n#### 1. Cosmos DB RBAC Configuration\n```bash\n# Get the managed identity principal ID from deployment output\nPRINCIPAL_ID=\"\u003cmanaged-identity-principal-id-from-deployment\u003e\"\n\n# Assign Cosmos DB Data Contributor role\naz cosmosdb sql role assignment create \\\n  --account-name your-cosmosdb-account \\\n  --resource-group your-cosmosdb-resource-group \\\n  --scope \"/\" \\\n  --principal-id $PRINCIPAL_ID \\\n  --role-definition-id 00000000-0000-0000-0000-000000000002\n```\n\n#### 2. Azure OpenAI RBAC Configuration\n```bash\n# Assign Cognitive Services OpenAI User role\naz role assignment create \\\n  --assignee $PRINCIPAL_ID \\\n  --role \"Cognitive Services OpenAI User\" \\\n  --scope /subscriptions/your-subscription-id/resourceGroups/your-openai-rg/providers/Microsoft.CognitiveServices/accounts/your-openai-service\n```\n\n### Local Development Setup\n\nFor local development (including Docker Compose), you'll need to authenticate using your user account:\n\n#### 1. Azure CLI Login\n```bash\naz login\n```\n\n#### 2. Configure Cosmos DB RBAC for Your User\n```bash\n# Get your user object ID\nUSER_ID=$(az ad signed-in-user show --query id -o tsv)\n\n# Assign Cosmos DB Built-in Data Contributor role\naz cosmosdb sql role assignment create \\\n  --account-name your-cosmosdb-account \\\n  --resource-group your-resource-group \\\n  --scope \"/\" \\\n  --principal-id $USER_ID \\\n  --role-definition-id 00000000-0000-0000-0000-000000000002\n```\n\n#### 3. Configure Azure OpenAI RBAC for Your User\n```bash\n# Assign Cognitive Services OpenAI User role\naz role assignment create \\\n  --assignee $USER_ID \\\n  --role \"Cognitive Services OpenAI User\" \\\n  --scope /subscriptions/your-subscription-id/resourceGroups/your-resource-group/providers/Microsoft.CognitiveServices/accounts/your-openai-service\n```\n\n## Security Considerations\n\n⚠️ **IMPORTANT SECURITY NOTICE**\n\nThis MCP Toolkit uses Entra ID (Azure AD) and Managed Identities to connect securely to Azure Cosmos DB and Azure OpenAI resources. However, it's critical to understand the security implications:\n\n### Data Access and Exposure\n- **Any data accessible to this MCP server can potentially be exposed to connected AI agents or applications**\n- The MCP server can execute tools that may read/edit/add any document in the databases and containers it has access to\n- Connected agents may request and receive data through the available tools\n\n### Container Security Features\n- ✅ **Non-root user**: Containers run as non-privileged user (uid 1000)\n- ✅ **Managed Identity**: No credentials stored in container images or environment variables\n- ✅ **HTTPS-only ingress**: All external traffic uses TLS encryption\n- ✅ **Health checks**: Automatic restart of unhealthy containers\n- ✅ **Resource limits**: CPU and memory constraints prevent resource exhaustion\n\n### Access Control Requirements\n- **Grant RBAC permissions ONLY to specific databases and containers** that you want AI agents to access\n- Use the principle of least privilege - don't grant broad access to your entire Cosmos DB account\n- Regularly review and audit the permissions granted to the MCP server's identity\n- Consider creating dedicated databases/containers for AI agent access rather than sharing production data\n\n### Network Security\n- Container Apps ingress is HTTPS-only with automatic TLS termination\n- Internal container communication uses encrypted channels\n- Log Analytics workspace captures security events and access patterns\n\n**Recommendation**: Start with a dedicated, isolated Cosmos DB account containing only non-sensitive test data when first deploying this toolkit.\n\n## VS Code Integration\n\n### Container-based Development\nWhen using Docker Compose for local development:\n\n1. **Start the containerized environment:**\n```bash\ndocker-compose up -d\n```\n\n2. **Configure VS Code MCP integration:**\nCreate or update `.vscode/mcp.json`:\n```json\n{\n  \"servers\": {\n    \"azure-cosmos-db-mcp\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8080\"\n    }\n  }\n}\n```\n\n3. **Restart VS Code** and test with GitHub Copilot Chat\n\n### Azure Container Apps Integration\nFor testing against your deployed Azure Container Apps instance:\n\n```json\n{\n  \"servers\": {\n    \"azure-cosmos-db-mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-container-app-url.azurecontainerapps.io\"\n    }\n  }\n}\n```\n\n### Traditional Local Development\nFor running .NET directly (port 8080 is now default):\n\n```json\n{\n  \"servers\": {\n    \"azure-cosmos-db-mcp\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8080\"\n    }\n  }\n}\n```\n\n### Basic Document Queries\n```\n@copilot List databases in my Cosmos DB account\n\n@copilot Show containers in the 'ecommerce' database\n\n@copilot Get the last 10 documents from the 'orders' container in 'ecommerce' database\n\n@copilot Find document with ID '12345' in the 'products' container\n```\n\n### Schema Discovery\n```\n@copilot What's the schema of the 'customers' container in 'ecommerce' database?\n\n@copilot Analyze the structure of documents in the 'inventory' container\n```\n\n### Text Search\n```\n@copilot Search for documents containing 'electronics' in the 'description' property of 'products' container\n\n@copilot Find orders where the 'status' contains 'shipped' in the last 15 results\n```\n\n### Vector Search (Semantic Search)\n```\n@copilot Find products similar to 'wireless headphones' and return id, name, price from the 'products' container using the 'contentVector' property\n\n@copilot Search for documents semantically similar to 'customer service complaint' in the 'feedback' container, return id, subject, content using vector property 'embeddings'\n```\n\n## Testing \u0026 Development\n\n### 📋 Comprehensive Testing Resources\n\nThis repository includes detailed testing guides:\n\n- **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - Complete testing scenarios for local and Azure environments\n- **[docs/deploy-to-azure-guide.md](docs/deploy-to-azure-guide.md)** - Detailed deployment documentation\n\n### 🧪 Unit Tests\n\nRun the included unit tests:\n```bash\n# Run all tests\ndotnet test\n\n# Run tests with verbose output\ndotnet test --verbosity normal\n\n# Run specific test class\ndotnet test --filter CosmosDbToolsTests\n```\n\n### 🔍 Health Monitoring\n\nThe application includes a health check endpoint for monitoring:\n\n```bash\n# Local development\ncurl http://localhost:8080/health\n\n# Azure deployment\ncurl https://your-container-app.azurecontainerapps.io/health\n```\n\nReturns HTTP 200 with \"Healthy\" when the service is ready to accept requests.\n\n## Key Dependencies\n\n### .NET Packages\n- **ModelContextProtocol.AspNetCore** (v0.3.0-preview.4) - MCP server framework\n- **Microsoft.Azure.Cosmos** (v3.53.0) - Cosmos DB .NET SDK\n- **Azure.Identity** (v1.12.0) - Authentication library with DefaultAzureCredential\n- **Azure.AI.OpenAI** (v2.0.0) - Azure OpenAI client for embeddings\n- **ASP.NET Core 9.0** - Web framework and hosting\n\n### Development Dependencies\n- **xUnit** (v2.6.1) - Unit testing framework\n- **FluentAssertions** (v6.12.0) - Assertion library for tests\n- **Moq** (v4.20.69) - Mocking framework\n- **Microsoft.AspNetCore.Mvc.Testing** - Integration testing\n\n## Vector Search Setup\n\nFor vector search functionality, your Cosmos DB documents need to contain vector embeddings. Here's an example document structure:\n\n```json\n{\n  \"id\": \"product-123\",\n  \"name\": \"Wireless Bluetooth Headphones\",\n  \"description\": \"High-quality wireless headphones with noise cancellation\",\n  \"category\": \"Electronics\",\n  \"price\": 199.99,\n  \"contentVector\": [0.1, 0.2, 0.3, ...], // 1536-dimensional embedding array\n  \"_ts\": 1234567890\n}\n```\n\nThe `contentVector` field contains the embedding generated by an Azure OpenAI's embedding model for the product's text content.\n\n## Troubleshooting\n\n## Troubleshooting\n\n### Container Deployment Issues\n\n#### Health Check Failures\n```bash\n# Test health endpoint directly\ncurl http://localhost:8080/health  # Local\ncurl https://your-app.azurecontainerapps.io/health  # Azure\n\n# Expected response: HTTP 200 \"Healthy\"\n```\n\n#### Authentication Errors\nThe application uses **DefaultAzureCredential** which attempts authentication in this order:\n1. **Environment variables** (service principal)\n2. **Managed identity** (in Azure)\n3. **Azure CLI** (`az login`)\n4. **Visual Studio/VS Code** credentials\n\n**Solutions**:\n- For local development: Run `az login`\n- For Azure: Ensure managed identity has proper RBAC assignments\n- For CI/CD: Set `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`\n\n#### Azure Container Apps Deployment Failures\n```bash\n# Check deployment status\naz deployment group list --resource-group rg-mcp-toolkit --output table\n\n# View deployment details\naz deployment group show --resource-group rg-mcp-toolkit --name \u003cdeployment-name\u003e\n\n# Check container app logs\naz containerapp logs show --name mcp-toolkit --resource-group rg-mcp-toolkit\n```\n\n#### Docker Compose Issues\n```bash\n# Check container status\ndocker-compose ps\n\n# View logs\ndocker-compose logs mcp-toolkit\ndocker-compose logs cosmos-emulator\n\n# Restart services\ndocker-compose restart\n\n# Rebuild and restart\ndocker-compose up --build\n```\n\n#### Container Health Check Failures\n```bash\n# Test health endpoint directly\ncurl http://localhost:8080/health\n\n# For Azure Container Apps\ncurl https://your-app.azurecontainerapps.io/health\n```\n\n### Common Issues\n\n#### Authentication Errors\n- **Error**: `Unauthorized` or `Forbidden`\n- **Container Solution**: Check managed identity configuration and RBAC assignments\n- **Local Solution**: Verify `az login` and user permissions\n\n#### Environment Variables\n- **Error**: `Missing required environment variable`\n- **Container Solution**: Verify Bicep template parameters and deployment configuration\n- **Local Solution**: Check `.env` file and docker-compose environment variables\n\n#### Port Conflicts\n- **Error**: Port 8080 already in use\n- **Solution**: Stop conflicting services or change port mapping in docker-compose.yml\n\n#### Cosmos DB Emulator Issues (Local Development)\n```bash\n# Reset emulator data\ndocker-compose down\ndocker volume rm mcp-toolkit-cosmos-data\ndocker-compose up -d\n\n# Import emulator SSL certificate (Windows)\ncurl -k https://localhost:8081/_explorer/emulator.pem \u003e cosmos-emulator.crt\ncertlm.msc # Import the certificate to Trusted Root Certification Authorities\n```\n\n#### Vector Search Issues\n- **Error**: Vector search returning no results\n- **Solution**: Ensure documents have vector embeddings and the vectorProperty parameter matches your schema\n\n#### Network Connectivity (Containers)\n```bash\n# Test container-to-container communication\ndocker-compose exec mcp-toolkit ping cosmos-emulator\n\n# Check network configuration\ndocker network ls\ndocker network inspect mcp-toolkit-network\n```\n\n### Debug Mode\n\n#### Container Debugging\n```bash\n# Run with debug logging\ndocker-compose -f docker-compose.yml -f docker-compose.override.yml up\n\n# Access container shell\ndocker-compose exec mcp-toolkit /bin/bash\n\n# Check environment variables inside container\ndocker-compose exec mcp-toolkit env | grep -E \"(COSMOS|OPENAI)\"\n```\n\n#### Azure Container Apps Debugging\n```bash\n# Enable debug logging\naz containerapp update \\\n  --name mcp-toolkit \\\n  --resource-group rg-mcp-toolkit \\\n  --set-env-vars ASPNETCORE_LOGGING__LOGLEVEL__DEFAULT=Debug\n\n# Stream logs\naz containerapp logs tail --name mcp-toolkit --resource-group rg-mcp-toolkit\n```\n\n### Verify Configuration\n\n#### Container Environment\n```bash\n# Check all environment variables\ndocker-compose config\n\n# Test container image locally\ndocker run --rm -it mcptoolkitacr.azurecr.io/mcp-toolkit:latest /bin/bash\n```\n\n#### Azure Resources\n```bash\n# Verify Cosmos DB access\naz cosmosdb show --name your-cosmos-account --resource-group your-rg\n\n# Verify OpenAI access  \naz cognitiveservices account show --name your-openai --resource-group your-rg\n\n# Check RBAC assignments\naz role assignment list --assignee \u003cprincipal-id\u003e --scope \u003cresource-scope\u003e\n```\n\n## Monitoring and Observability\n\n### Azure Container Apps Monitoring\n- **Application Insights**: Automatic telemetry collection\n- **Log Analytics**: Centralized logging and querying\n- **Health Checks**: Built-in readiness and liveness probes\n- **Metrics**: CPU, memory, and request metrics\n\n### Monitoring Queries (Log Analytics)\n```kusto\n// Application logs\nContainerAppConsoleLogs_CL\n| where ContainerAppName_s == \"mcp-toolkit\"\n| order by TimeGenerated desc\n\n// Health check failures\nContainerAppConsoleLogs_CL\n| where ContainerAppName_s == \"mcp-toolkit\"\n| where Log_s contains \"health\"\n| where Log_s contains \"fail\"\n```\n\n## Performance and Scaling\n\n### Azure Container Apps Scaling\n- **Horizontal scaling**: 1-3 replicas based on HTTP requests\n- **Scale trigger**: 10 concurrent requests per replica\n- **Scale-to-zero**: Automatically scales down during idle periods\n- **Custom scaling**: Modify `infrastructure/main.bicep` for different scaling rules\n\n### Resource Optimization\n```bash\n# Update container resources\naz containerapp update \\\n  --name mcp-toolkit \\\n  --resource-group rg-mcp-toolkit \\\n  --cpu 1.0 \\\n  --memory 2.0Gi\n```\n\n## Contributing\n\n### Development Workflow\n1. **Fork and clone** the repository\n2. **Create feature branch** from `dev/sajee/updates`\n3. **Test locally** using Docker Compose\n4. **Deploy to test environment** using GitHub Actions\n5. **Submit pull request** with comprehensive testing\n\n### Container Development\n```bash\n# Build and test locally\ndocker build -t mcp-toolkit-dev .\ndocker run -p 8080:8080 --env-file .env mcp-toolkit-dev\n\n# Run tests\ndocker-compose -f docker-compose.yml -f docker-compose.test.yml up --abort-on-container-exit\n```\n\n## Support and Documentation\n\n### Quick Links\n- **Health Check**: `GET /health` - Container health status\n- **Azure Portal**: Monitor your deployed resources\n- **GitHub Actions**: View deployment history and logs\n- **Log Analytics**: Query application logs and metrics\n\n### Getting Help\n1. **Container Issues**: Check the troubleshooting section above\n2. **Azure Resources**: Review Azure Cosmos DB and Container Apps documentation  \n3. **GitHub Issues**: Open an issue with deployment logs and configuration details\n4. **Security Questions**: Follow the security considerations and RBAC setup guides\n\n### Documentation Resources\n- [Azure Container Apps Documentation](https://docs.microsoft.com/en-us/azure/container-apps/)\n- [Azure Cosmos DB Documentation](https://docs.microsoft.com/en-us/azure/cosmos-db/)\n- [Azure OpenAI Documentation](https://docs.microsoft.com/en-us/azure/cognitive-services/openai/)\n- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)\n\n## 🎯 Project Structure\n\n```\nMCPToolKit/\n├── src/AzureCosmosDB.MCP.Toolkit/     # Main MCP server application (.NET 9.0)\n│   ├── Program.cs                      # 7 MCP tools and web server setup\n│   ├── *.csproj                       # Project configuration with latest packages\n│   └── appsettings*.json              # Application configuration\n├── tests/                             # Unit and integration tests (xUnit)\n│   └── AzureCosmosDB.MCP.Toolkit.Tests/\n├── infrastructure/                    # Bicep templates for Azure deployment\n│   ├── deploy-all-resources.bicep     # Complete infrastructure template\n│   └── *.json                        # ARM template versions for portal deployment\n├── scripts/                          # Deployment and utility scripts (5 essential)\n│   ├── Deploy-Complete.ps1           # Windows complete deployment\n│   ├── deploy-complete.sh            # Linux/macOS complete deployment\n│   ├── validate-setup.ps1            # Environment validation\n│   └── Setup-CosmosCert.ps1          # Certificate setup for emulator\n├── .github/workflows/                # GitHub Actions CI/CD pipelines\n├── docs/                             # Additional documentation and guides\n├── Dockerfile                        # Multi-stage container build (.NET 9.0)\n├── docker-compose.yml               # Local dev environment + Cosmos emulator\n├── TESTING_GUIDE.md                 # Comprehensive testing instructions\n└── README.md                        # This comprehensive documentation\n```\n\n## 🚀 Quick Start Summary\n\n1. **One-Click Azure Deployment**: [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzureCosmosDB%2FMCPToolKit%2Fmain%2Finfrastructure%2Fdeploy-all-resources.json)\n2. **Local Development**: `docker-compose up -d`\n3. **VS Code Integration**: Configure `.vscode/mcp.json` with server URL\n4. **Test with AI Agent**: \"@copilot List databases in my Cosmos DB account\"\n\n---\n\n## 📦 Container Architecture Summary\n\n```mermaid\ngraph TB\n    subgraph \"Azure Container Apps\"\n        MCP[MCP Toolkit Container]\n        MI[Managed Identity]\n        Health[Health Checks]\n    end\n    \n    subgraph \"Azure Services\"\n        Cosmos[Cosmos DB]\n        OpenAI[Azure OpenAI]\n        ACR[Container Registry]\n        LA[Log Analytics]\n    end\n    \n    subgraph \"Local Development\"\n        DC[Docker Compose]\n        CE[Cosmos Emulator]\n        Local[Local Container]\n    end\n    \n    MCP --\u003e Cosmos\n    MCP --\u003e OpenAI\n    MI --\u003e Cosmos\n    MI --\u003e OpenAI\n    Health --\u003e MCP\n    LA --\u003e MCP\n    \n    DC --\u003e CE\n    DC --\u003e Local\n    Local --\u003e OpenAI\n```\n\nThis containerized MCP Toolkit provides enterprise-ready deployment options with comprehensive monitoring, security, and scaling capabilities. Choose the deployment method that best fits your development workflow and production requirements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazurecosmosdb%2Fmcptoolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazurecosmosdb%2Fmcptoolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazurecosmosdb%2Fmcptoolkit/lists"}