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 集成精心打造 ❤️