Awx MCP Server

🚀 AWX MCP - 基於人工智能的AWX/AAP/Ansible自動化

AWX MCP 服務器是適用於 AWX、Ansible 自動化平臺（AAP）和 Ansible Tower 的行業標準多客戶端協議（MCP）服務器，它將這些自動化工具與人工智能工具相連接，使 AI 代理和助手能夠通過自然語言交互來管理作業模板、啟動和監控作業、管理清單和項目，以及自動化基礎設施工作流。

本項目專為希望將其 AI 工具與 AWX/AAP/Tower 自動化功能集成的開發者而設計。

✨ 支持 AWX（開源）、AAP（紅帽）和 Ansible Tower（舊版），採用相同的 API 和功能！

🚀 快速開始

安裝方法

你有 三種方式 來安裝和運行 AWX MCP 服務器：

→ 若要進行定製並從自己的倉庫運行，請參閱 INSTALL_FROM_SOURCE.md

選項 1：PyPI 安裝（快速啟動推薦）

從 PyPI 安裝

# 安裝 MCP 服務器
pip install awx-mcp-server

# 驗證安裝
python -m awx_mcp_server --version

為 VS Code 配置

編輯 VS Code 的 settings.json (Ctrl+, → 搜索 "chat.mcp")：

{
  "mcpServers": {
    "awx": {
      "command": "python",
      "args": ["-m", "awx_mcp_server"],
      "env": {
        "AWX_BASE_URL": "https://your-awx.com"
      },
      "secrets": {
        "AWX_TOKEN": "your-awx-token"
      }
    }
  }
}

重啟 VS Code，MCP 服務器將在 Copilot Chat 中可用。

選項 2：從源代碼安裝（用於定製）

適用場景：分叉、定製、企業部署、貢獻代碼

快速安裝：

# 克隆倉庫（或你的分叉）
git clone https://github.com/SurgeX-Labs/awx-mcp-server.git
cd awx-mcp-server/awx-mcp-python/server

# 創建虛擬環境
python -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\Activate.ps1

# 以可編輯模式安裝
pip install -e .

# 驗證
python -m awx_mcp_server --version

VS Code 配置（使用虛擬環境中的 Python）：

{
  "mcpServers": {
    "awx": {
      "command": "/path/to/awx-mcp-server/awx-mcp-python/server/venv/bin/python",
      "args": ["-m", "awx_mcp_server"],
      "env": {
        "AWX_BASE_URL": "https://your-awx.com"
      },
      "secrets": {
        "AWX_TOKEN": "your-token"
      }
    }
  }
}

📖 完整指南：請參閱 INSTALL_FROM_SOURCE.md，瞭解以下內容：

• 分叉倉庫
• 對代碼進行定製
• 從自己的分叉/倉庫運行
• 從源代碼構建自定義 Docker 鏡像
• 企業部署和 CI/CD

選項 3：遠程服務器模式（團隊/企業）

前提條件

• Python 3.10+
• AWX/Ansible Tower 實例
• （可選）Docker 或 Kubernetes

使用 Docker 快速啟動

cd awx-mcp-python/server

# 啟動帶有監控棧的服務器
docker-compose up -d

# 服務器訪問地址：
# - API: http://localhost:8000
# - 文檔: http://localhost:8000/docs
# - 指標: http://localhost:8000/prometheus-metrics
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3000

使用 Python 快速啟動

cd awx-mcp-python/server

# 安裝
pip install -e .

# 配置 AWX 環境（交互式）
awx-mcp-server env list

# 啟動服務器
awx-mcp-server start --host 0.0.0.0 --port 8000

CLI 使用方法

# 列出作業模板
awx-mcp-server templates list

# 啟動作業
awx-mcp-server jobs launch "Deploy App" --extra-vars '{"env":"prod"}'

# 監控作業
awx-mcp-server jobs get 123
awx-mcp-server jobs stdout 123

# 管理項目
awx-mcp-server projects list
awx-mcp-server projects update "My Project"

# 列出清單
awx-mcp-server inventories list

REST API 使用方法

# 創建 API 密鑰（首次使用）
curl -X POST http://localhost:8000/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "chatbot", "tenant_id": "team1", "expires_days": 90}'

# 列出作業模板
curl http://localhost:8000/api/v1/job-templates \
  -H "X-API-Key: awx_mcp_xxxxx"

# 啟動作業
curl -X POST http://localhost:8000/api/v1/jobs/launch \
  -H "X-API-Key: awx_mcp_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"template_name": "Deploy App", "extra_vars": {"env": "prod"}}'

# 獲取作業狀態
curl http://localhost:8000/api/v1/jobs/123 \
  -H "X-API-Key: awx_mcp_xxxxx"

# 獲取作業輸出
curl http://localhost:8000/api/v1/jobs/123/stdout \
  -H "X-API-Key: awx_mcp_xxxxx"

Kubernetes 部署

cd server/deployment/helm

helm install awx-mcp-server . \
  --set replicaCount=3 \
  --set autoscaling.enabled=true \
  --set taskPods.enabled=true

詳情請見：server/README.md 中的詳細指南

✨ 主要特性

主要模式：MCP 服務器（行業標準） ⭐ 推薦

使用標準輸入輸出（STDIO）傳輸的標準 MCP 實現（如 Postman MCP、Claude MCP）

用例：AI 助手（GitHub Copilot、Claude、Cursor）+ AWX 自動化

特性：

• ✅ 可與任何 MCP 客戶端（Copilot、Claude、Cursor、Windsurf 等）配合使用
• ✅ 行業標準模式（STDIO 傳輸）
• ✅ 安裝簡單：pip install git+https://github.com/USERNAME/awx-mcp-server.git
• ✅ 可在所有支持 MCP 的工具中移植
• ✅ 支持 18 種以上 AWX 操作（模板、作業、項目、清單）

適用場景：基於人工智能的自動化、通過自然語言控制 AWX、任何 MCP 客戶端

可選模式：VS Code 擴展（UI 增強）

為 VS Code 用戶提供的可選 UI 功能

用例：希望獲得額外 UI（側邊欄視圖、樹狀提供程序）的 VS Code 用戶

特性：

• ✅ 帶有 AWX 實例、作業、指標的側邊欄
• ✅ AWX 資源的樹狀視圖
• ✅ 配置網頁視圖
• ✅ 自動配置 MCP（或支持手動設置）

適用場景：希望在 MCP 功能基礎上獲得豐富 UI 的 VS Code 用戶

💻 使用示例

基礎用法

# 與自定義聊天機器人集成
import httpx

class AWXChatbot:
    def __init__(self, api_key: str, base_url: str = "http://localhost:8000"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {"X-API-Key": api_key}
    
    async def handle_message(self, user_message: str):
        """Process user message and call AWX API"""
        if "list templates" in user_message.lower():
            return await self.list_templates()
        elif "launch" in user_message.lower():
            template_name = self.extract_template_name(user_message)
            return await self.launch_job(template_name)
        elif "job status" in user_message.lower():
            job_id = self.extract_job_id(user_message)
            return await self.get_job(job_id)
    
    async def list_templates(self):
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}/api/v1/job-templates",
                headers=self.headers
            )
            return response.json()
    
    async def launch_job(self, template_name: str, extra_vars: dict = None):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/api/v1/jobs/launch",
                headers=self.headers,
                json={"template_name": template_name, "extra_vars": extra_vars}
            )
            return response.json()
    
    async def get_job(self, job_id: int):
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}/api/v1/jobs/{job_id}",
                headers=self.headers
            )
            return response.json()

# Usage
chatbot = AWXChatbot(api_key="awx_mcp_xxxxx")
response = await chatbot.handle_message("list all job templates")

高級用法

# 與 Slack 機器人集成
from slack_bolt.async_app import AsyncApp
import httpx

app = AsyncApp(token="xoxb-your-token")
awx_api_key = "awx_mcp_xxxxx"
awx_base_url = "http://localhost:8000"

@app.message("awx")
async def handle_awx_command(message, say):
    text = message['text']
    
    if "launch" in text:
        # Extract template name from message
        template = extract_template(text)
        
        # Call AWX API
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{awx_base_url}/api/v1/jobs/launch",
                headers={"X-API-Key": awx_api_key},
                json={"template_name": template}
            )
            job = response.json()
        
        await say(f"✅ Job launched! ID: {job['id']}, Status: {job['status']}")

📚 詳細文檔

安裝與設置

• 從 PyPI 安裝 - 使用 pip install awx-mcp-server 快速安裝
• 從源代碼安裝 - 分叉、定製並從自己的倉庫運行
• 操作系統兼容性 - Windows、macOS 和 Linux 的安裝與配置

平臺支持

• AAP 支持指南 - Ansible 自動化平臺、AWX 和 Ansible Tower 的完整指南

部署架構

• 部署架構 - 單用戶與團隊/企業部署選項
• 遠程部署指南 - Docker、Kubernetes 和雲部署
• 雙模式快速啟動 - 選擇部署模式的快速參考

高級特性（計劃中）

• 保險庫集成 - HashiCorp Vault、AWS 密鑰管理服務、Azure 密鑰保管庫支持（v2.0.0）
• 實現狀態 - 當前功能和路線圖

額外資源

• MCP Copilot 設置 - VS Code MCP 配置
• 快速參考 - 常用命令和示例
• AWX MCP 查詢參考 - 自然語言查詢示例

🔧 技術細節

可用的 AWX 操作

VS Code 擴展和 Web 服務器均支持以下 16 種操作：

環境管理

• env_list - 列出所有已配置的 AWX 環境
• env_test - 測試與 AWX 環境的連接
• env_get_active - 獲取當前活動的環境

作業模板

• list_job_templates - 列出所有作業模板（支持過濾）
• get_job_template - 根據名稱/ID 獲取模板詳細信息

作業

• list_jobs - 列出所有作業（可按狀態、日期過濾）
• get_job - 根據 ID 獲取作業詳細信息
• job_launch - 從模板啟動作業
• job_cancel - 取消正在運行的作業
• job_stdout - 獲取作業輸出/日誌
• job_events - 獲取作業事件（劇本任務）

項目

• list_projects - 列出所有項目
• project_update - 從源代碼管理（SCM）更新項目

清單

• list_inventories - 列出所有清單
• get_inventory - 獲取清單詳細信息

項目結構

awx-mcp-python/
├── vscode-extension/          # 帶有 GitHub Copilot 的 VS Code 擴展
│   ├── src/                   # 擴展的 TypeScript 源代碼
│   ├── package.json           # 擴展清單
│   ├── README.md              # 擴展指南
│   └── CHANGELOG.md
│
│
├── server/                    # 獨立的 Web 服務器
│   ├── src/awx_mcp_server/
│   │   ├── cli.py             # CLI 命令（468 行）
│   │   ├── http_server.py     # FastAPI REST API
│   │   ├── mcp_server.py      # MCP 服務器集成
│   │   ├── monitoring.py      # Prometheus 指標
│   │   ├── task_pods.py       # Kubernetes 任務容器
│   │   ├── clients/           # AWX 客戶端（自包含）
│   │   ├── storage/           # 配置和憑證
│   │   └── domain/            # 模型和異常
│   ├── deployment/
│   │   ├── docker-compose.yml # Docker Compose 棧
│   │   ├── Dockerfile         # 容器鏡像
│   │   └── helm/              # Kubernetes Helm 圖表
│   ├── pyproject.toml
│   └── README.md
│
└── tests/                     # 共享測試套件
    ├── test_*.py
    └── conftest.py

架構

VS Code 擴展架構

┌─────────────────┐
│   VS Code IDE   │
│                 │
│  ┌───────────┐  │     stdio      ┌──────────────┐
│  │  GitHub   │──┼────transport───▶│  MCP Server  │
│  │  Copilot  │  │    (local)     │   (shared)   │
│  │   Chat    │◀─┼────────────────│   16 Tools   │
│  └───────────┘  │                └──────────────┘
│                 │                        │
│  ┌───────────┐  │                        │
│  │ @awx Chat │  │                        │
│  │Participant│  │                        ▼
│  └───────────┘  │                 ┌──────────────┐
└─────────────────┘                 │     AWX      │
                                    │   Instance   │
                                    └──────────────┘

流程：

1. 用戶在 Copilot Chat 中輸入 @awx list templates
2. 擴展通過標準輸入輸出將 MCP 請求發送到本地服務器
3. MCP 服務器調用 AWX REST API
4. 結果返回給 Copilot Chat
5. AI 自然地格式化響應

Web 服務器架構

┌──────────────┐      REST API       ┌──────────────┐
│   Chatbot    │────────────────────▶│  FastAPI     │
│  /Custom App │   (HTTP/JSON)       │   Server     │
└──────────────┘                     └──────────────┘
                                            │
┌──────────────┐      REST API       │
│   Slack Bot  │────────────────────▶│
└──────────────┘                     │
                                     │
┌──────────────┐         CLI         │
│   Terminal   │────────────────────▶│
│   Scripts    │   (commands)        │
└──────────────┘                     │
                                     │
                              ┌──────┴───────┐
                              │              │
                              │   Clients    │
                              │  REST + CLI  │
                              │              │
                              └──────┬───────┘
                                     │
                                     ▼
                              ┌──────────────┐
                              │     AWX      │
                              │   Instance   │
                              └──────────────┘

流程：

1. 客戶端（聊天機器人/CLI）發送帶有 API 密鑰的 HTTP 請求
2. FastAPI 服務器對請求進行身份驗證
3. 服務器通過複合客戶端調用 AWX API
4. 結果以 JSON 格式返回
5. 客戶端為最終用戶（Slack、終端等）格式化結果

安全

VS Code 擴展

• 憑證存儲在 VS Code 的安全存儲中
• 僅本地服務器（無網絡暴露）
• 基於環境的隔離

Web 服務器

• API 密鑰身份驗證（SHA-256 哈希）
• 多租戶隔離
• 可配置的密鑰過期時間
• 生產環境建議使用 HTTPS
• 使用環境變量存儲機密信息

部署選項

VS Code 擴展

• 從 .vsix 文件安裝擴展
• VS Code 啟動時 MCP 服務器自動運行
• 無需額外的基礎設施

Web 服務器

開發環境

cd server
pip install -e .
awx-mcp-server start

生產環境 - Docker

cd server
docker-compose up -d

包含：服務器、Prometheus、Grafana

生產環境 - Kubernetes

cd server/deployment/helm
helm install awx-mcp-server . \
  --set autoscaling.enabled=true \
  --set taskPods.enabled=true \
  --set ingress.enabled=true

特性：

• 水平 Pod 自動伸縮（HPA）
• 任務容器（每個操作一個臨時作業）
• Prometheus 監控
• 支持 Ingress

開發

前提條件

• Python 3.10+
• Node.js 18+（用於 VS Code 擴展）
• Docker（可選）
• Kubernetes 集群（可選）

設置開發環境

# 克隆倉庫
git clone https://github.com/your-org/awx-mcp.git
cd awx-mcp/awx-mcp-python

# 安裝共享包（用於 VS Code 擴展）
cd shared
pip install -e ".[dev]"

# 安裝服務器
cd ../server
pip install -e ".[dev]"

# 安裝擴展依賴
cd ../vscode-extension
npm install

# 運行測試
cd ../tests
pytest -v

運行測試

# 服務器測試
cd server
pytest tests/ -v --cov

# 集成測試
cd tests
pytest test_mcp_integration.py -v

構建 VS Code 擴展

cd vscode-extension
npm run package
# 生成 awx-mcp-*.vsix 文件

監控（Web 服務器）

訪問監控儀表板：

• Prometheus：http://localhost:9090
• Grafana：http://localhost:3000（用戶名/密碼：admin/admin）
• 指標端點：http://localhost:8000/prometheus-metrics

可用指標

• awx_mcp_requests_total - 按租戶/端點統計的總請求數
• awx_mcp_request_duration_seconds - 請求延遲
• awx_mcp_active_connections - 每個租戶的活動連接數
• awx_mcp_tool_calls_total - MCP 工具調用次數
• awx_mcp_errors_total - 按類型統計的錯誤數

🤝 貢獻代碼

我們歡迎貢獻！請按以下步驟操作：

1. 分叉倉庫
2. 創建功能分支
3. 編寫測試並進行更改
4. 提交拉取請求

代碼風格

• Python：遵循 PEP 8，使用類型提示
• TypeScript：遵循 ESLint 規則
• 為新功能編寫測試
• 更新文檔

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 文件。

🆘 支持

• 問題反饋：https://github.com/your-org/awx-mcp/issues
• 討論：https://github.com/your-org/awx-mcp/discussions
• 文檔：請參閱子目錄中的 README 文件

🎉 快速參考

VS Code 擴展命令

• Ctrl+Shift+P → AWX: Configure Environment
• Ctrl+Shift+P → AWX: Test Connection
• Ctrl+Shift+P → AWX: Switch Environment
• 在 Copilot Chat 中：@awx <你的命令>

Web 服務器 CLI 命令

awx-mcp-server start                    # 啟動 HTTP 服務器
awx-mcp-server env list                 # 列出環境
awx-mcp-server templates list           # 列出模板
awx-mcp-server jobs launch "Template"   # 啟動作業
awx-mcp-server jobs get 123             # 獲取作業詳細信息
awx-mcp-server projects list            # 列出項目
awx-mcp-server inventories list         # 列出清單

Web 服務器 API 端點

POST   /api/keys                         # 創建 API 密鑰
GET    /api/v1/environments              # 列出環境
GET    /api/v1/job-templates             # 列出模板
POST   /api/v1/jobs/launch               # 啟動作業
GET    /api/v1/jobs/{id}                 # 獲取作業
GET    /api/v1/jobs/{id}/stdout          # 獲取輸出
GET    /api/v1/projects                  # 列出項目
GET    /api/v1/inventories               # 列出清單
GET    /health                           # 健康檢查
GET    /prometheus-metrics               # 指標
GET    /docs                             # API 文檔

本項目為 AWX 自動化和 AI 集成精心打造 ❤️