azureai-optimizer/README.md

AI-Powered Azure Infrastructure Optimization via Model Context Protocol

# AzureAI Optimizer MCP Server

🚀 **AI-Powered Azure Infrastructure Optimization via Model Context Protocol**

[![npm version](https://badge.fury.io/js/azureai-optimizer.svg)](https://badge.fury.io/js/azureai-optimizer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Azure Marketplace](https://img.shields.io/badge/Azure-Marketplace-blue.svg)](https://azuremarketplace.microsoft.com)

## Overview

AzureAI Optimizer is a specialized MCP (Model Context Protocol) server that provides AI-powered Azure infrastructure optimization, cost management, and security compliance through any MCP-compatible AI assistant (Claude, ChatGPT, GitHub Copilot).

**Key Value Proposition:** Reduce Azure costs by 20-40% while improving security posture and performance through AI-driven analysis and recommendations.

## 🎯 Target Market

- Mid-market companies spending $10K-500K/month on Azure services
- Organizations seeking professional-grade optimization without expensive consultants
- DevOps teams wanting AI-assisted Azure management

## ⚡ Quick Start with NPX

The easiest way to get started is using NPX - no installation required!

### 🚀 **30-Second Setup for Claude Desktop**

1. **Set your Azure credentials:**
   ```bash
   export AZURE_SUBSCRIPTION_ID="your-subscription-id"
   export AZURE_TENANT_ID="your-tenant-id"  # optional
   ```

2. **Add to Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
   ```json
   {
     "mcpServers": {
       "azureai-optimizer": {
         "command": "npx",
         "args": ["-y", "azureai-optimizer@latest", "server", "start"],
         "env": {
           "AZURE_SUBSCRIPTION_ID": "your-subscription-id",
           "AZURE_TENANT_ID": "your-tenant-id"
         }
       }
     }
   }
   ```

3. **Restart Claude Desktop** and start optimizing:
   ```
   "Analyze my Azure costs for the last 30 days"
   ```

### 📋 **Prerequisites**

### For VS Code with GitHub Copilot

1. **Install Prerequisites:**
   ```bash
   # Ensure you have Node.js 18+ installed
   node --version
   ```

2. **Add to VS Code MCP Configuration:**
   
   Create or update `.vscode/mcp.json`:
   ```json
   {
     "servers": {
       "AzureAI Optimizer": {
         "command": "npx",
         "args": [
           "-y",
           "azureai-optimizer@latest",
           "server",
           "start"
         ],
         "env": {
           "AZURE_SUBSCRIPTION_ID": "your-subscription-id",
           "AZURE_TENANT_ID": "your-tenant-id"
         }
       }
     }
   }
   ```

3. **Restart VS Code and activate GitHub Copilot Agent Mode**

4. **Start optimizing:**
   ```
   @azureai analyze my Azure costs for the last 30 days
   @azureai recommend VM right-sizing for my production environment
   @azureai assess security compliance for SOC2
   ```

### For Claude Desktop

**Step 1:** Locate your Claude Desktop configuration file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

**Step 2:** Add the AzureAI Optimizer configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "azureai-optimizer": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-subscription-id",
        "AZURE_TENANT_ID": "your-tenant-id"
      }
    }
  }
}
```

**Step 3:** Replace the placeholder values:
- `your-subscription-id` - Your Azure subscription ID (GUID format)
- `your-tenant-id` - Your Azure tenant ID (optional, auto-detected if not provided)

**Step 4:** Restart Claude Desktop

### For Other MCP Clients

#### **Cline (VS Code Extension)**
Add to your Cline MCP configuration:

```json
{
  "mcpServers": {
    "azureai-optimizer": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-subscription-id",
        "AZURE_TENANT_ID": "your-tenant-id"
      }
    }
  }
}
```

#### **Continue (VS Code Extension)**
Add to your Continue configuration:

```json
{
  "mcpServers": [
    {
      "name": "azureai-optimizer",
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-subscription-id",
        "AZURE_TENANT_ID": "your-tenant-id"
      }
    }
  ]
}
```

#### **Custom MCP Clients**

```bash
# Run the server directly
npx -y azureai-optimizer@latest server start

# Or with custom configuration
npx -y azureai-optimizer@latest server start --port 8080 --transport sse
```

## 🛠️ Available Tools

### Cost Optimization
- **`analyze_cost_optimization`** - Comprehensive cost analysis with AI recommendations
- **`right_size_resources`** - VM and database right-sizing suggestions
- **`reserved_instance_analysis`** - RI and Savings Plan recommendations
- **`unused_resource_detection`** - Identify and eliminate waste

### Security Assessment
- **`security_compliance_check`** - Multi-framework compliance assessment
- **`vulnerability_scan`** - Security posture analysis
- **`access_review`** - IAM and RBAC optimization
- **`encryption_audit`** - Data protection compliance

### Performance Optimization
- **`performance_analysis`** - Resource performance insights
- **`scaling_recommendations`** - Auto-scaling optimization
- **`network_optimization`** - Traffic and latency analysis
- **`storage_optimization`** - Storage tier and access pattern analysis

### Resource Management
- **`resource_inventory`** - Complete Azure resource discovery
- **`tag_management`** - Resource tagging and governance
- **`policy_compliance`** - Azure Policy assessment
- **`backup_analysis`** - Backup and disaster recovery review

## 🔧 MCP Client Configuration

### Complete Configuration Examples

#### **Claude Desktop Configuration (OpenRouter - Recommended)**
Create or update `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "azureai-optimizer": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "12345678-1234-1234-1234-123456789012",
        "AZURE_TENANT_ID": "87654321-4321-4321-4321-210987654321",
        "OPENROUTER_API_KEY": "sk-or-v1-your-openrouter-key",
        "OPENROUTER_COST_MODEL": "openai/gpt-4.1-preview",
        "OPENROUTER_SECURITY_MODEL": "anthropic/claude-3.5-sonnet:beta",
        "AZUREAI_LOG_LEVEL": "info"
      }
    }
  }
}
```

#### **Claude Desktop Configuration (Direct Providers)**
Alternative configuration using direct OpenAI/Anthropic APIs:

```json
{
  "mcpServers": {
    "azureai-optimizer": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "12345678-1234-1234-1234-123456789012",
        "AZURE_TENANT_ID": "87654321-4321-4321-4321-210987654321",
        "OPENAI_API_KEY": "sk-your-openai-key",
        "ANTHROPIC_API_KEY": "sk-ant-your-anthropic-key",
        "AZUREAI_LOG_LEVEL": "info"
      }
    }
  }
}
```

#### **Cline (VS Code) Configuration**
Add to your Cline settings:

```json
{
  "mcpServers": {
    "azureai-optimizer": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "12345678-1234-1234-1234-123456789012",
        "AZURE_TENANT_ID": "87654321-4321-4321-4321-210987654321"
      }
    }
  }
}
```

#### **Multi-Subscription Enterprise Configuration**
For organizations with multiple Azure subscriptions:

```json
{
  "mcpServers": {
    "azureai-production": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "prod-subscription-id",
        "AZURE_CLIENT_ID": "prod-service-principal-id",
        "AZURE_CLIENT_SECRET": "prod-service-principal-secret",
        "AZUREAI_LOG_LEVEL": "warn"
      }
    },
    "azureai-development": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "dev-subscription-id",
        "AZURE_CLIENT_ID": "dev-service-principal-id",
        "AZURE_CLIENT_SECRET": "dev-service-principal-secret",
        "AZUREAI_LOG_LEVEL": "debug"
      }
    }
  }
}
```

### Environment Variables

```bash
# Required
AZURE_SUBSCRIPTION_ID=your-subscription-id
AZURE_TENANT_ID=your-tenant-id

# Optional - Authentication (uses DefaultAzureCredential if not provided)
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

# AI Providers (OpenRouter recommended for latest models)
OPENROUTER_API_KEY=sk-or-v1-your-openrouter-key
OPENROUTER_COST_MODEL=openai/gpt-4.1-preview
OPENROUTER_SECURITY_MODEL=anthropic/claude-3.5-sonnet:beta

# Alternative - Direct AI Providers
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Optional - Configuration
AZUREAI_LOG_LEVEL=info
AZUREAI_CACHE_TTL=300
AZUREAI_MAX_CONCURRENT_REQUESTS=10
```

### 🚀 Quick Configuration Generator

Generate MCP configuration for your client:

```bash
# Generate configuration for Claude Desktop
npx azureai-optimizer config --output claude_desktop_config.json

# Generate configuration with custom settings
npx azureai-optimizer config --transport sse --port 8080

# Display configuration in terminal
npx azureai-optimizer config
```

### Authentication Methods

The server uses Azure's `DefaultAzureCredential` which tries authentication in this order:

1. **Environment Variables** - Service Principal credentials
2. **Managed Identity** - For Azure-hosted applications
3. **Azure CLI** - `az login` credentials
4. **Visual Studio** - VS credentials
5. **Interactive Browser** - Fallback authentication

### 🔍 Health Check

Verify your configuration before using:

```bash
# Check Azure connectivity and permissions
npx azureai-optimizer health

# Expected output:
# 🏥 Running health checks...
# ✅ Environment variables configured
# ✅ Azure authentication successful
# ✅ Subscription access confirmed: Production Subscription
# 🎉 All health checks passed!
```

## 💬 Usage Examples

### Natural Language Queries (Recommended)

Once configured, you can use natural language with your AI assistant:

#### **Cost Optimization**
```
"Analyze my Azure costs for the last 30 days and show me the top optimization opportunities"

"What are my most expensive Azure services this month?"

"Compare this month's Azure spending to last month and identify any anomalies"

"Show me potential cost savings from right-sizing my virtual machines"
```

#### **Security Assessment**
```
"Check my Azure security compliance for SOC2 requirements"

"What security vulnerabilities exist in my Azure environment?"

"Assess my Azure resources against ISO27001 compliance framework"

"Show me the top security risks and how to fix them"
```

#### **Performance Analysis**
```
"Analyze the performance of my Azure VMs and identify bottlenecks"

"What resources are underperforming and need optimization?"

"Check for performance issues in my production environment"

"Recommend performance improvements for my Azure infrastructure"
```

#### **Resource Management**
```
"List all my unused Azure resources that are costing money"

"What VMs can be right-sized to save costs?"

"Show me resources without proper tags"

"Analyze my reserved instance coverage and recommendations"
```

### Direct Tool Calls (Advanced)

For programmatic access or custom integrations:

#### **Cost Analysis**
```json
{
  "tool": "analyze_cost_optimization",
  "arguments": {
    "subscription_id": "12345678-1234-1234-1234-123456789012",
    "resource_group": "production-rg",
    "days_back": 30,
    "include_recommendations": true,
    "granularity": "daily"
  }
}
```

#### **Security Assessment**
```json
{
  "tool": "security_compliance_check",
  "arguments": {
    "subscription_id": "12345678-1234-1234-1234-123456789012",
    "compliance_framework": "SOC2",
    "include_remediation": true,
    "severity_filter": "medium"
  }
}
```

#### **Resource Right-sizing**
```json
{
  "tool": "right_size_resources",
  "arguments": {
    "subscription_id": "12345678-1234-1234-1234-123456789012",
    "resource_types": ["VirtualMachines", "SqlDatabases"],
    "utilization_threshold": 70,
    "analysis_days": 30
  }
}
```

#### **Performance Analysis**
```json
{
  "tool": "performance_analysis",
  "arguments": {
    "subscription_id": "12345678-1234-1234-1234-123456789012",
    "resource_group": "production-rg",
    "analysis_days": 7,
    "performance_threshold": 80
  }
}
```

## 🏗️ Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  AzureAI Server  │    │  Azure APIs     │
│  (Claude/GPT)   │◄──►│   (NPX Package)  │◄──►│  (Cost/Security)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   AI Analysis    │
                       │ (Multi-LLM Stack)│
                       └──────────────────┘
```

## 🚀 Deployment Options

### 1. NPX (Recommended for Development)
```bash
npx -y azureai-optimizer@latest server start
```

### 2. Global Installation
```bash
npm install -g @azureai/optimizer
azureai-optimizer server start
```

### 3. Docker Container
```bash
docker run -e AZURE_SUBSCRIPTION_ID=your-id azureai/optimizer:latest
```

### 4. Azure Container Instances (Production)
```bash
az container create \
  --resource-group myResourceGroup \
  --name azureai-optimizer \
  --image azureai/optimizer:latest \
  --environment-variables AZURE_SUBSCRIPTION_ID=your-id
```

## 📈 Pricing & Plans

| Plan | Price/Month | Azure Spend Limit | Features |
|------|-------------|-------------------|----------|
| **Starter** | $199 | $10K | Basic optimization, Security assessment |
| **Professional** | $599 | $100K | Advanced optimization, Real-time monitoring |
| **Enterprise** | $1,499 | Unlimited | Multi-subscription, Custom compliance |

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](./LICENSE) for details.

## 🔧 Troubleshooting

### Common Configuration Issues

#### **"Tool not found" or "Server not responding"**
1. Verify your MCP configuration file syntax is valid JSON
2. Check that the `command` and `args` are correct
3. Ensure Node.js 18+ is installed: `node --version`
4. Test the server manually: `npx azureai-optimizer health`

#### **Azure Authentication Failures**
```bash
# Check Azure CLI login
az account show

# Verify subscription access
az account set --subscription your-subscription-id

# Test authentication
npx azureai-optimizer health
```

#### **Missing Environment Variables**
```bash
# Set required variables
export AZURE_SUBSCRIPTION_ID="12345678-1234-1234-1234-123456789012"
export AZURE_TENANT_ID="87654321-4321-4321-4321-210987654321"

# Verify configuration
npx azureai-optimizer config
```

#### **NPX Cache Issues**
```bash
# Clear NPX cache
npx clear-npx-cache

# Force latest version
npx -y @azureai/optimizer@latest --version
```

### Configuration File Locations

| Client | Configuration File |
|--------|-------------------|
| **Claude Desktop (macOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude Desktop (Windows)** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Claude Desktop (Linux)** | `~/.config/Claude/claude_desktop_config.json` |
| **VS Code (Cline)** | VS Code Settings → Extensions → Cline → MCP Servers |
| **Continue** | `.continue/config.json` in your project |

### Debug Mode

Enable debug logging for troubleshooting:

```json
{
  "mcpServers": {
    "azureai-optimizer": {
      "command": "npx",
      "args": ["-y", "@azureai/optimizer@latest", "server", "start"],
      "env": {
        "AZURE_SUBSCRIPTION_ID": "your-subscription-id",
        "AZUREAI_LOG_LEVEL": "debug"
      }
    }
  }
}
```

## 🆘 Support

- 📧 Email: support@azureai-optimizer.com
- 💬 Discord: [AzureAI Community](https://discord.gg/azureai)
- 📖 Documentation: [docs.azureai-optimizer.com](https://docs.azureai-optimizer.com)
- 🐛 Issues: [GitHub Issues](https://github.com/azureai/optimizer/issues)
- 💡 Feature Requests: [GitHub Discussions](https://github.com/azureai/optimizer/discussions)

## 🔗 Links

- [Azure Marketplace Listing](https://azuremarketplace.microsoft.com/marketplace/apps/azureai.optimizer)
- [NPM Package](https://www.npmjs.com/package/azureai-optimizer)
- [Documentation](https://docs.azureai-optimizer.com)
- [API Reference](https://api.azureai-optimizer.com)

---

**Made with ❤️ for the Azure community**