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、同じ機能！

🚀 クイックスタート

インストール方法

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

→ カスタマイズや独自のリポジトリからの実行については、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操作（テンプレート、ジョブ、プロジェクト、インベントリ）

最適なシチュエーション: AI駆動型オートメーション、自然言語による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):
        """ユーザーメッセージを処理し、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()

# 使用例
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:
        # メッセージからテンプレート名を抽出
        template = extract_template(text)
        
        # 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"✅ ジョブが起動しました！ID: {job['id']}, ステータス: {job['status']}")

📚 ドキュメント

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

• 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クエリリファレンス - 自然言語クエリの例

🔧 技術詳細

利用可能なAWX操作

VS Code拡張機能とウェブサーバーの両方が、すべての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/                    # スタンドアロンのウェブサーバー
│   ├── 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. 拡張機能がstdioを介してローカルサーバーにMCPリクエストを送信
3. MCPサーバーがAWX REST APIを呼び出す
4. 結果がCopilot Chatに返される
5. AIが応答を自然に整形する

ウェブサーバーのアーキテクチャ

┌──────────────┐      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の安全なストレージに保存されます。
• ローカルサーバーのみ（ネットワークに公開されません）
• 環境ベースの分離

ウェブサーバー

• APIキー認証（SHA-256ハッシュ化）
• マルチテナント分離
• キーの有効期限を設定可能
• 本番環境ではHTTPSを推奨
• シークレットには環境変数を使用

デプロイメントオプション

VS Code拡張機能

• .vsixファイルから拡張機能をインストール
• VS Codeが起動するとMCPサーバーが自動的に実行されます。
• 追加のインフラストラクチャは必要ありません。

ウェブサーバー

開発環境

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

特徴:

• 水平ポッドオートスケーリング（HPA）
• タスクポッド（操作ごとに一時的なジョブ）
• Prometheusモニタリング
• イングレスサポート

開発

前提条件

• 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ファイルが生成されます。

モニタリング（ウェブサーバー）

モニタリングダッシュボードにアクセスできます。

• 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 <your command>

ウェブサーバーの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         # インベントリを一覧表示

ウェブサーバーの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統合のために❤️ で作られました。