Awx MCP Server

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服务器：

→ 有关自定义和从自己的存储库运行，请参阅 安装\_ ROM \_来源.md

______________________________________________________________________

选项1:PyPI安装（建议快速启动）

从PyPI安装

# Install the MCP server
pip install awx-mcp-server

# Verify installation
python -m awx_mcp_server --version

配置VS代码

编辑VS代码设置.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代码 MCP服务器将在Copilot聊天中可用。

______________________________________________________________________

选项2：从源代码安装（用于自定义）

非常适合：分叉、定制、企业部署、贡献

快速安装:

# 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）：

{
  "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快速入门

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快速入门

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使用情况

# 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使用

# 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部署

cd server/deployment/helm

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

看: 服务器/README.md 详细指南

______________________________________________________________________

🎨 集成示例

与自定义聊天机器人集成

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集成

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聊天
2. 扩展通过stdio向本地服务器发送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代码扩展

• 存储在VS Code安全存储中的凭据
• 仅限本地服务器（无网络暴露）
• 基于环境的隔离

Web服务器

• API密钥认证（SHA-256哈希）
• 多租户隔离
• 可配置密钥过期
• HTTPS建议用于生产
• 机密的环境变量

______________________________________________________________________

🚢 部署选项

用于VS代码扩展

• 从.vsix文件安装扩展名
• VS Code启动时MCP服务器自动运行
• 无需额外的基础设施

对于Web服务器

发展

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

生产-Docker

cd server
docker-compose up -d

包括：服务器、普罗米修斯、Grafana

生产-Kubernetes

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集群（可选）

设置开发环境

# 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

运行测试

# Server tests
cd server
pytest tests/ -v --cov

# Integration tests
cd tests
pytest test_mcp_integration.py -v

建筑VS代码扩展

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查询参考 -自然语言查询示例

______________________________________________________________________

🤝 贡献

我们欢迎捐款！拜托：

1. 分叉存储库
2. 创建要素分支
3. 通过测试进行更改
4. 提交拉取请求

代码的风格

• 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 Environment
• Ctrl+Shift+P → AWX: Test Connection
• Ctrl+Shift+P → AWX: Switch Environment
• 在Copilot聊天中： @awx

Web服务器CLI命令

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集成