awx-mcp-server

AWX MCP - AI を活用した AWX/AAP/Ansible 自動化

AWX/AAP/Ansible Tower 自動化の業界標準 MCP サーバー

AWX MCP サーバーは、AWX、Ansible Automation Platform (AAP)、Ansible Tower を AI ツールに接続し、AI エージェントやアシスタントがジョブテンプレートの管理、ジョブの起動と監視、インベントリーやプロジェクトの管理、自然言語でのやり取りによるインフラストラクチャのワークフロー自動化を行えるようにします。

AI ツールを AWX/AAP/Tower 自動化機能と統合したい開発者向けに設計されています。

✨ AWX（オープンソース）、AAP（Red Hat）、Ansible Tower（レガシー）をサポート。同じ API、同じ機能です！

---

🎯 使用パターン

主な用途：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 操作（テンプレート、ジョブ、プロジェクト、インベントリー）

最適な用途：AI を活用した自動化、自然言語による AWX 操作、あらゆる MCP クライアント

---

オプション：VS Code 拡張機能（UI の強化）

VS Code ユーザー向けのオプションの UI 機能

ユースケース：追加の UI（サイドバービュー、ツリープロバイダー）を求める VS Code ユーザー

機能：

• ✅ AWX インスタンス、ジョブ、メトリクスを表示するサイドバー
• ✅ AWX リソースのツリービュー
• ✅ 構成用 Webview
• ✅ MCP を自動構成（または手動設定を尊重）

最適な用途：MCP 機能とともに充実した UI を利用したい VS Code ユーザー

---

🚀 クイックスタート

インストール方法

AWX MCP サーバーをインストールして実行する方法は3 つあります。

方法	最適な用途	インストール
📦 PyPI（pip）	すばやいインストール、本番環境での使用	pip install awx-mcp-server
🔧 ソースから	カスタマイズ、開発、企業向けフォーク	GitHub からクローンし、コードを編集
🐳 Docker	コンテナー化されたデプロイ、チーム	docker run surgexlabs/awx-mcp-server

→ カスタマイズして独自のリポジトリから実行する方法については、INSTALL_FROM_SOURCE.md を参照してください。

---

オプション 1：PyPI からインストール（クイックスタートに推奨）

PyPI からインストール

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

# Verify installation
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 を再起動すると、Copilot Chat で MCP サーバーを利用できるようになります。

---

オプション 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 Code の構成（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"
      }
    }
  }
}

📖 詳細なガイド：INSTALL_FROM_SOURCE.md を参照してください。内容：

• リポジトリのフォーク
• コードのカスタマイズ
• 独自のフォーク／リポジトリからの実行
• ソースからのカスタム 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

参照先：server/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 ボットとの統合

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 - ジョブのイベントを取得します（Playbook のタスク）

プロジェクト

• 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 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. 拡張機能が 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 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）
• タスク Pod（操作ごとに一時的な Job を作成）
• Prometheus による監視
• Ingress に対応

---

🛠️ 開発

前提条件

• Python 3.10+
• Node.js 18+（VS Code 拡張機能用）
• 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 Code 拡張機能のビルド

cd vscode-extension
npm run package
# Generates awx-mcp-*.vsix file

---

📊 監視（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 - 種類ごとのエラー数

---

📚 ドキュメント

インストールとセットアップ

• PyPI からインストール - pip install awx-mcp-server で簡単にインストールできます
• ソースからインストール - フォークしてカスタマイズし、ご自身のリポジトリから実行します
• OS の互換性 - Windows、macOS、Linux でのインストールと設定

プラットフォームのサポート

• AAP サポートガイド - Ansible Automation Platform、AWX、Ansible Tower の完全ガイド

デプロイアーキテクチャ

• デプロイアーキテクチャ - 単一ユーザー向けとチーム／エンタープライズ向けのデプロイオプション
• リモートデプロイガイド - Docker、Kubernetes、クラウドへのデプロイ
• デュアルモードクイックスタート - デプロイモードを選択するためのクイックリファレンス

高度な機能（予定）

• Vault 連携 - HashiCorp Vault、AWS Secrets Manager、Azure Key Vault に対応（v2.0.0）
• 実装状況 - 現在の機能とロードマップ

その他のリソース

• MCP Copilot のセットアップ - VS Code の MCP 設定
• クイックリファレンス - よく使うコマンドと使用例
• AWX MCP クエリリファレンス - 自然言語でのクエリ例

---

🤝 コントリビューション

コントリビューションを歓迎します！次の手順でお願いします。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. テストを含めて変更を行います
4. プルリクエストを送信します

コードスタイル

• Python：PEP 8 に従い、型ヒントを使用します
• TypeScript：ESLint のルールに従います
• 新機能のテストを作成します
• ドキュメントを更新します

---

📄 ライセンス

MIT License - 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 <your command>

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 連携のために ❤️ を込めて作成