金大哥 - azure-_mcp MCP 详情

article

README

🚀 Azure Omni-Tool MCP Server

Azure Omni-Tool MCP Server 是一个用 TypeScript 编写的 Model Context Protocol (MCP) 服务器，它充当自然语言请求与 Azure CLI 执行之间的智能桥梁，能将用户的自然语言请求转化为可执行的 Azure CLI 命令。

✨ 主要特性

✅ 计划/执行流程：在执行命令前进行审核。
✅ 安全防护：检测 shell 注入，对破坏性命令发出警告。
✅ 审计跟踪：通过操作员电子邮件标记实现可追溯性。
✅ 重试逻辑：针对临时故障采用指数退避策略。
✅ 缓存机制：使用可配置 TTL 的 LRU 缓存。
✅ 租户范围：可通过环境配置租户/订阅。
✅ Azure 服务适配器：对 8 种 Azure 服务进行类型安全访问。

📚 详细文档

架构概述

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

请求流程

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

计划/执行流程

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

🚀 快速开始

1. 安装依赖

npm install

2. 配置环境

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

3. 构建并运行

npm run build
npm start

MCP 客户端配置

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

💻 使用示例

工具使用

`manage_azure_resources`

该工具可对 Azure CLI 命令进行计划和执行，同时进行安全检查。 | 参数 | 类型 | 描述 | |------|------|------| | command | 字符串 | Azure CLI 命令 | | explanation | 字符串 | 选择该命令的原因 | | execute_now | 布尔值 | false = 计划，true = 执行 |

`get_azure_context`

该工具可通过缓存查询 Azure 环境。 | 查询类型 | 描述 | |----------|------| | subscriptions | 列出可访问的订阅 | | resource_groups | 列出资源组 | | resources | 列出资源 | | custom | 通过资源图进行自定义 KQL 查询 |

`azure_service`

该工具可与特定的 Azure 服务进行交互。 | 服务 | 操作 | |------|------| | storage | 列出存储、列出容器、列出Blob、获取容器、列出表、查询表 | | cosmos | 列出、列出数据库、列出容器、查询、获取容器 | | search | 列出、列出索引、获取索引、查询、获取服务 | | kusto | 列出、列出数据库、列出表、获取架构、采样、查询 | | monitor | 列出、获取工作区、列出表、查询、列出指标、获取指标 | | appconfig | 列出、获取存储、列出键值对、获取键值对、设置键值对、锁定、解锁 | | keyvault | 列出、获取保管库、列出密钥、获取密钥、创建密钥、列出机密、获取机密、列出证书 | | postgres | 列出、获取服务器、列出数据库、列出参数、获取参数、列出表、获取表架构、查询 |

环境变量

| 变量 | 描述 | 默认值 | |------|------|--------| | AZURE_TENANT_ID | 用于范围限定的 Azure 租户 | - | | AZURE_SUBSCRIPTION_ID | 默认订阅 | - | | OPERATOR_EMAIL | 用于审计跟踪的电子邮件 | - | | OPERATOR_NAME | 操作员姓名 | - | | LOG_LEVEL | 日志记录级别 | info | | ENABLE_CACHE | 启用查询缓存 | true | | CACHE_TTL_SECONDS | 缓存持续时间 | 300 | | CACHE_CLEANUP_INTERVAL_MS | 缓存清理间隔 | 60000 | | MAX_RETRIES | 重试次数 | 3 | | RETRY_DELAY_MS | 基本重试延迟 | 1000 | | COMMAND_TIMEOUT_MS | CLI 超时时间 | 120000 | | AZURE_MCP_INCLUDE_PRODUCTION_CREDENTIALS | 启用托管标识 | false |

项目结构

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

前提条件

Node.js >= 18.0.0
已安装并认证 Azure CLI (az login)

📄 许可证

本项目采用 MIT 许可证。

azure-_mcp