Azure Omni-Tool MCP Server

# 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