# Azure Omni-Tool MCP Server

A **Model Context Protocol (MCP) server** in TypeScript that acts as an intelligent bridge between natural language requests and Azure CLI execution.

## Features

✅ **Plan/Execute Flow** - Review commands before execution  
✅ **Safety Guardrails** - Shell injection detection, destructive command warnings  
✅ **Audit Trail** - Operator email tagging for traceability  
✅ **Retry Logic** - Exponential backoff for transient failures  
✅ **Caching** - LRU cache with configurable TTL  
✅ **Tenant Scoping** - Configure tenant/subscription via environment  
✅ **Azure Service Adapters** - Type-safe access to 8 Azure services

---

## Architecture Overview

```mermaid
flowchart TB
    subgraph Client["🖥️ Client Layer"]
        LLM[LLM / AI Agent]
    end

    subgraph MCP["⚙️ MCP Server"]
        direction TB
        Entry[index.ts]
        
        subgraph Tools["Tools"]
            T1[manage_azure_resources]
            T2[get_azure_context]
            T3[azure_service]
        end
        
        subgraph Lib["Core Libraries"]
            Auth[auth.ts]
            Cache[cache.ts]
            CLI[cli-executor.ts]
            Retry[retry.ts]
            Safety[safety.ts]
            Audit[audit.ts]
        end
        
        subgraph Services["Service Adapters"]
            S1[StorageService]
            S2[CosmosService]
            S3[SearchService]
            S4[KustoService]
            S5[MonitorService]
            S6[AppConfigService]
            S7[KeyVaultService]
            S8[PostgresService]
        end
    end

    subgraph Azure["☁️ Azure"]
        AzCLI[Azure CLI]
        AzAPI[Azure APIs]
    end

    LLM -->|MCP Protocol| Entry
    Entry --> Tools
    Tools --> Lib
    Tools --> Services
    Services --> Lib
    Lib --> AzCLI
    Auth --> AzAPI
```

---

## Request Flow

```mermaid
sequenceDiagram
    participant C as Client
    participant M as MCP Server
    participant S as Safety
    participant E as CLI Executor
    participant A as Azure

    C->>M: Tool Request
    M->>S: Validate Input
    alt Unsafe Command
        S-->>M: Block + Warning
        M-->>C: Error Response
    else Safe
        S-->>M: Approved
        M->>E: Execute Command
        E->>A: az CLI call
        A-->>E: Response
        E-->>M: Result + Parse
        M-->>C: Structured Output
    end
```

---

## Plan/Execute Flow

```mermaid
flowchart LR
    A[LLM Client] -->|Natural Language| B[MCP Server]
    B --> C{execute_now?}
    C -->|false| D[Return Plan]
    C -->|true| E[Execute CLI]
    E --> F{Success?}
    F -->|Yes| G[Return Output]
    F -->|No| H[Return Error + Analysis]
    H -->|Feedback Loop| A
```

---

## Quick Start

### 1. Install Dependencies
```bash
npm install
```

### 2. Configure Environment
```bash
cp .env.example .env
# Edit .env with your settings
```

### 3. Build & Run
```bash
npm run build
npm start
```

### MCP Client Configuration
```json
{
  "mcpServers": {
    "azure-omni-tool": {
      "command": "node",
      "args": ["path/to/Azure-mcp/dist/index.js"]
    }
  }
}
```

---

## Tools

### `manage_azure_resources`
Plan and execute Azure CLI commands with safety checks.

| Argument | Type | Description |
|----------|------|-------------|
| `command` | string | Azure CLI command |
| `explanation` | string | Why this command was chosen |
| `execute_now` | boolean | `false` = plan, `true` = execute |

### `get_azure_context`
Query Azure environment with caching.

| Query Type | Description |
|------------|-------------|
| `subscriptions` | List accessible subscriptions |
| `resource_groups` | List resource groups |
| `resources` | List resources |
| `custom` | Custom KQL via Resource Graph |

### `azure_service`
Interact with specific Azure services.

| Service | Actions |
|---------|---------|
| `storage` | list, listContainers, listBlobs, getContainer, listTables, queryTable |
| `cosmos` | list, listDatabases, listContainers, query, getContainer |
| `search` | list, listIndexes, getIndex, query, getService |
| `kusto` | list, listDatabases, listTables, getSchema, sample, query |
| `monitor` | list, getWorkspace, listTables, query, listMetrics, getMetrics |
| `appconfig` | list, getStore, listKeyValues, getKeyValue, setKeyValue, lock, unlock |
| `keyvault` | list, getVault, listKeys, getKey, createKey, listSecrets, getSecret, listCertificates |
| `postgres` | list, getServer, listDatabases, listParameters, getParameter, listTables, getTableSchema, query |

---

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AZURE_TENANT_ID` | Azure tenant for scoping | - |
| `AZURE_SUBSCRIPTION_ID` | Default subscription | - |
| `OPERATOR_EMAIL` | Email for audit trail | - |
| `OPERATOR_NAME` | Operator name | - |
| `LOG_LEVEL` | Logging level | `info` |
| `ENABLE_CACHE` | Enable query caching | `true` |
| `CACHE_TTL_SECONDS` | Cache duration | `300` |
| `CACHE_CLEANUP_INTERVAL_MS` | Cache cleanup interval | `60000` |
| `MAX_RETRIES` | Retry attempts | `3` |
| `RETRY_DELAY_MS` | Base retry delay | `1000` |
| `COMMAND_TIMEOUT_MS` | CLI timeout | `120000` |
| `AZURE_MCP_INCLUDE_PRODUCTION_CREDENTIALS` | Enable Managed Identity | `false` |

---

## Project Structure

```
Azure-mcp/
├── src/
│   ├── index.ts                 # MCP server entry
│   ├── lib/
│   │   ├── auth.ts              # Azure credential management
│   │   ├── audit.ts             # Audit trail with correlation IDs
│   │   ├── cache.ts             # LRU cache with TTL
│   │   ├── cli-executor.ts      # Azure CLI wrapper
│   │   ├── config.ts            # Environment config
│   │   ├── logger.ts            # Structured JSON logging
│   │   ├── retry.ts             # Exponential backoff
│   │   ├── safety.ts            # Input sanitization
│   │   └── types.ts             # Shared types
│   ├── services/
│   │   ├── base-service.ts      # Abstract service base
│   │   ├── storage.ts           # Azure Storage
│   │   ├── cosmos.ts            # Cosmos DB
│   │   ├── search.ts            # AI Search
│   │   ├── kusto.ts             # Data Explorer
│   │   ├── monitor.ts           # Monitor / Log Analytics
│   │   ├── appconfig.ts         # App Configuration
│   │   ├── keyvault.ts          # Key Vault
│   │   ├── postgres.ts          # PostgreSQL Flexible Server
│   │   └── index.ts             # Service factory
│   └── tools/
│       ├── azure-manager.ts     # Plan/Execute tool
│       ├── context-retriever.ts # Context queries
│       └── service-tool.ts      # Service adapter tool
├── .env.example
├── package.json
└── tsconfig.json
```

---

## Prerequisites

- Node.js >= 18.0.0
- Azure CLI installed and authenticated (`az login`)

---

## License

MIT