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

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

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

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

npm install

2. Configure Environment

cp .env.example .env
# Edit .env with your settings

3. Build & Run

npm run build
npm start

MCP Client Configuration

{
  "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