AWX MCP-人工智能驱动的AWX/AAP/Assible自动化
用于AWX/AAP/Assible Tower自动化的行业标准MCP服务器
AWX MCP服务器连接 AWX, Ansible自动化平台(AAP),以及 Ansible塔 AI工具,使AI代理和助手能够管理作业模板、启动和监控作业、管理库存和项目,并通过自然语言交互自动化基础设施工作流程。
专为希望将AI工具与AWX/AAP/Tower自动化功能集成的开发人员而设计。
✨ 支持AWX(开源)、AAP(Red Hat)和Ansible Tower(传统)-相同的API,相同的功能!
🎯 使用模式
主服务器:MCP服务器(行业标准)⭐ 推荐
使用STDIO传输的标准MCP实现(如Postman MCP、Claude MCP)
用例:人工智能助手(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操作(模板、作业、项目、库存)
最适合:AI驱动的自动化、自然语言AWX控制、任何MCP客户端
可选:VS代码扩展(UI增强)
VS Code用户的可选UI功能
用例:需要额外UI(侧边栏视图、树提供程序)的VS Code用户
特性:
- ✅ 带有AWX实例、作业和指标的侧栏
- ✅ AWX资源的树形视图
- ✅ 配置Web视图
- ✅ 自动配置MCP(或遵守手动设置)
最适合:VS Code用户想要丰富的UI和MCP功能
🚀 快速开始
安装方法
你有 三种方式 安装并运行AWX MCP服务器:
| 方法 | 最适合 | 安装 |
|---|---|---|
| 📦 PyPI(点) | 快速安装,生产使用 | pip install awx-mcp-server |
| 🔧 来源 | 定制、开发、企业分叉 | 从GitHub克隆、编辑代码 |
| 🐳 码头工人 | 集装箱化部署,团队 | docker run surgexlabs/awx-mcp-server |
→ 有关自定义和从自己的存储库运行,请参阅 安装_ ROM _来源.md
选项1:PyPI安装(建议快速启动)
从PyPI安装```bash
Install the MCP server
pip install awx-mcp-server
Verify installation
python -m awx_mcp_server --version
#### 配置VS代码
**编辑VS代码设置.json** (`Ctrl+,` → 搜索“chat.mcp”):```json
{
"mcpServers": {
"awx": {
"command": "python",
"args": ["-m", "awx_mcp_server"],
"env": {
"AWX_BASE_URL": "https://your-awx.com"
},
"secrets": {
"AWX_TOKEN": "your-awx-token"
}
}
}
}
重新启动VS代码 MCP服务器将在Copilot聊天中可用。
选项2:从源代码安装(用于自定义)
非常适合:分叉、定制、企业部署、贡献
快速安装:```bash
Clone the repository (or your fork)
git clone https://github.com/SurgeX-Labs/awx-mcp-server.git
cd awx-mcp-server/awx-mcp-python/server
Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: .\venv\Scripts\Activate.ps1
Install in editable mode
pip install -e .
Verify
python -m awx_mcp_server --version
**VS代码配置** (使用venv Python):```json
{
"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"
}
}
}
}
📖 完整指南:参见 安装_ ROM _来源.md 用于:
- 分叉存储库
- 对代码进行自定义
- 从您自己的fork/repository运行
- 从源代码构建自定义Docker镜像
- 企业部署和CI/CD
选项3:远程服务器模式(团队/企业)
先决条件
- Python 3.10+
- AWX/Ansible Tower实例
- (可选)Docker或Kubernetes
Docker快速入门```bash
cd awx-mcp-python/server
Start server with monitoring stack
docker-compose up -d
Server available at:
- API: http://localhost:8000
- Docs: http://localhost:8000/docs
- Metrics: http://localhost:8000/prometheus-metrics
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3000
#### Python快速入门```bash
cd awx-mcp-python/server
# Install
pip install -e .
# Configure AWX environment (interactive)
awx-mcp-server env list
# Start server
awx-mcp-server start --host 0.0.0.0 --port 8000
CLI使用情况```bash
List job templates
awx-mcp-server templates list
Launch job
awx-mcp-server jobs launch "Deploy App" --extra-vars '{"env":"prod"}'
Monitor job
awx-mcp-server jobs get 123
awx-mcp-server jobs stdout 123
Manage projects
awx-mcp-server projects list
awx-mcp-server projects update "My Project"
List inventories
awx-mcp-server inventories list
#### REST API使用```bash
# Create API key (first time)
curl -X POST http://localhost:8000/api/keys \
-H "Content-Type: application/json" \
-d '{"name": "chatbot", "tenant_id": "team1", "expires_days": 90}'
# List job templates
curl http://localhost:8000/api/v1/job-templates \
-H "X-API-Key: awx_mcp_xxxxx"
# Launch job
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"}}'
# Get job status
curl http://localhost:8000/api/v1/jobs/123 \
-H "X-API-Key: awx_mcp_xxxxx"
# Get job output
curl http://localhost:8000/api/v1/jobs/123/stdout \
-H "X-API-Key: awx_mcp_xxxxx"
Kubernetes部署```bash
cd server/deployment/helm
helm install awx-mcp-server . \
--set replicaCount=3 \
--set autoscaling.enabled=true \
--set taskPods.enabled=true
**看**: 服务器/README.md 详细指南
______________________________________________________________________
## 🎨 集成示例
### 与自定义聊天机器人集成```python
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 Bot集成```python
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']}")
______________________________________________________________________
## 🔧 可用的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/ # VS Code extension with GitHub Copilot
│ ├── src/ # Extension TypeScript source
│ ├── package.json # Extension manifest
│ ├── README.md # Extension guide
│ └── CHANGELOG.md
│
│
├── server/ # Standalone web server
│ ├── src/awx_mcp_server/
│ │ ├── cli.py # CLI commands (468 lines)
│ │ ├── http_server.py # FastAPI REST API
│ │ ├── mcp_server.py # MCP server integration
│ │ ├── monitoring.py # Prometheus metrics
│ │ ├── task_pods.py # Kubernetes task pods
│ │ ├── clients/ # AWX clients (self-contained)
│ │ ├── storage/ # Config & credentials
│ │ └── domain/ # Models & exceptions
│ ├── deployment/
│ │ ├── docker-compose.yml # Docker Compose stack
│ │ ├── Dockerfile # Container image
│ │ └── helm/ # Kubernetes Helm chart
│ ├── pyproject.toml
│ └── README.md
│
└── tests/ # Shared test suite
├── test_*.py
└── conftest.py
🏗️ 建筑
VS代码扩展架构```
┌─────────────────┐
│ VS Code IDE │
│ │
│ ┌───────────┐ │ stdio ┌──────────────┐
│ │ GitHub │──┼────transport───▶│ MCP Server │
│ │ Copilot │ │ (local) │ (shared) │
│ │ Chat │◀─┼────────────────│ 16 Tools │
│ └───────────┘ │ └──────────────┘
│ │ │
│ ┌───────────┐ │ │
│ │ @awx Chat │ │ │
│ │Participant│ │ ▼
│ └───────────┘ │ ┌──────────────┐
└─────────────────┘ │ AWX │
│ Instance │
└──────────────┘
**流动**:
1. 用户类型 `@awx list templates` 在Copilot聊天
1. 扩展通过stdio向本地服务器发送MCP请求
1. MCP服务器调用AWX REST API
1. 结果返回到Copilot Chat
1. AI格式自然响应
### Web服务器体系结构```
┌──────────────┐ REST API ┌──────────────┐
│ Chatbot │────────────────────▶│ FastAPI │
│ /Custom App │ (HTTP/JSON) │ Server │
└──────────────┘ └──────────────┘
│
┌──────────────┐ REST API │
│ Slack Bot │────────────────────▶│
└──────────────┘ │
│
┌──────────────┐ CLI │
│ Terminal │────────────────────▶│
│ Scripts │ (commands) │
└──────────────┘ │
│
┌──────┴───────┐
│ │
│ Clients │
│ REST + CLI │
│ │
└──────┬───────┘
│
▼
┌──────────────┐
│ AWX │
│ Instance │
└──────────────┘
流动:
- 客户端(聊天机器人/CLI)使用API密钥发送HTTP请求
- FastAPI服务器对请求进行身份验证
- 服务器通过复合客户端调用AWX API
- 结果以JSON格式返回
- 终端用户的客户端格式(Slack、终端等)
🔒 安全
VS代码扩展
- 存储在VS Code安全存储中的凭据
- 仅限本地服务器(无网络暴露)
- 基于环境的隔离
Web服务器
- API密钥认证(SHA-256哈希)
- 多租户隔离
- 可配置密钥过期
- HTTPS建议用于生产
- 机密的环境变量
🚢 部署选项
用于VS代码扩展
- 从.vsix文件安装扩展名
- VS Code启动时MCP服务器自动运行
- 无需额外的基础设施
对于Web服务器
发展```bash
cd server
pip install -e .
awx-mcp-server start
#### 生产-Docker```bash
cd server
docker-compose up -d
包括:服务器、普罗米修斯、Grafana
生产-Kubernetes```bash
cd server/deployment/helm
helm install awx-mcp-server . \
--set autoscaling.enabled=true \
--set taskPods.enabled=true \
--set ingress.enabled=true
特征:
- 水平吊舱自动缩放(HPA)
- 任务吊舱(每次操作的临时作业)
- 普罗米修斯监控
- 入口支持
______________________________________________________________________
## 🛠️ 发展
### 先决条件
- Python 3.10+
- Node.js 18+(用于VS代码扩展)
- Docker(可选)
- Kubernetes集群(可选)
### 设置开发环境```bash
# Clone repository
git clone https://github.com/your-org/awx-mcp.git
cd awx-mcp/awx-mcp-python
# Install shared package (for VS Code extension)
cd shared
pip install -e ".[dev]"
# Install server
cd ../server
pip install -e ".[dev]"
# Install extension dependencies
cd ../vscode-extension
npm install
# Run tests
cd ../tests
pytest -v
运行测试```bash
Server tests
cd server
pytest tests/ -v --cov
Integration tests
cd tests
pytest test_mcp_integration.py -v
### 建筑VS代码扩展```bash
cd vscode-extension
npm run package
# Generates awx-mcp-*.vsix file
📊 监控(Web服务器)
访问监控仪表板:
- 普罗米修斯: http://localhost:9090
- 格拉法纳: http://localhost:3000(管理员/管理员)
- 指标端点: http://localhost:8000/prometheus-度量标准
可用指标
awx_mcp_requests_total-按租户/端点列出的请求总数awx_mcp_request_duration_seconds-请求延迟awx_mcp_active_connections-每个租户的活动连接数awx_mcp_tool_calls_total-MCP工具调用awx_mcp_errors_total-按类型列出的错误计数
📚 文档
安装和设置
- 从PyPI安装 -快速安装
pip install awx-mcp-server - 从源代码安装 -从您自己的存储库分叉、自定义和运行
- 操作系统兼容性 -Windows、macOS和Linux的安装和配置
平台支持
- AAP支持指南 -Ansible自动化平台、AWX和Ansible Tower的完整指南
部署架构
- 部署架构 -单用户与团队/企业部署选项
- 远程部署指南 -Docker、Kubernetes和云部署
- 双模式快速启动 -选择部署模式的快速参考
高级功能(计划中)
- 保险库集成 -HashiCorp保险库、AWS密钥管理器、Azure密钥保险库支持(v2.0.0)
- 实施状态 -当前功能和路线图
其他资源
- MCP副驾驶设置 -VS代码MCP配置
- 快速参考 -常见命令和示例
- AWX MCP查询参考 -自然语言查询示例
🤝 贡献
我们欢迎捐款!拜托:
- 分叉存储库
- 创建要素分支
- 通过测试进行更改
- 提交拉取请求
代码的风格
- Python:遵循PEP 8,使用类型提示
- TypeScript:遵循ESLint规则
- 为新功能编写测试
- 更新文档
📄 许可证
MIT许可证-请参阅 许可证 文件
🆘 支持
- 问题: https://github.com/your-org/awx-mcp/issues
- 讨论: https://github.com/your-org/awx-mcp/discussions
- 文档:请参阅子目录中的README文件
🎉 快速参考
VS代码扩展命令
Ctrl+Shift+P→AWX: Configure EnvironmentCtrl+Shift+P→AWX: Test ConnectionCtrl+Shift+P→AWX: Switch Environment- 在Copilot聊天中:
@awx
Web服务器CLI命令```bash
awx-mcp-server start # Start HTTP server
awx-mcp-server env list # List environments
awx-mcp-server templates list # List templates
awx-mcp-server jobs launch "Template" # Launch job
awx-mcp-server jobs get 123 # Get job details
awx-mcp-server projects list # List projects
awx-mcp-server inventories list # List inventories
### Web服务器API终结点```
POST /api/keys # Create API key
GET /api/v1/environments # List environments
GET /api/v1/job-templates # List templates
POST /api/v1/jobs/launch # Launch job
GET /api/v1/jobs/{id} # Get job
GET /api/v1/jobs/{id}/stdout # Get output
GET /api/v1/projects # List projects
GET /api/v1/inventories # List inventories
GET /health # Health check
GET /prometheus-metrics # Metrics
GET /docs # API documentation
由以下材料制成❤️ 用于AWX自动化和AI集成
