MCP サービス

MCP（Model Context Protocol）は、同プロトコルをサポートするクライアント（エディタ、AI Agent ツール）から AzurPilot を直接操作・問い合わせするためのインターフェースです。これは外部連携用の別系統のエントリポイントであり、WebSocket API を代替するものではありません。

2つの稼働形態

形態	エンドポイント	説明
WebUI 同梱マウント	`http://<host>:25548/mcp/sse`	デフォルト構成。WebUI プロセスと同一ポートを共有
独立サービス	`python mcp_server_sse.py`（ポート `22268`）	デバッグ時やプロセス分離環境向け

22268 ポートの OCR との競合

MCP 独立サーバーと OCR サービスはデフォルトでどちらも 22268 ポートを使用します。同一マシン上で両者を動作させる場合は、事前にいずれかのポート番号を変更してください。

認証方式

MCP は WebUI の認証パスワード（--key または deploy.yaml の Password）を流用します：

方式	記法
リクエストヘッダー（推奨）	`Authorization: Bearer <パスワード>`
互換ヘッダー	`X-API-Key: <パスワード>`
クエリパラメータ	`?key=<パスワード>`（カスタムヘッダー非対応のクライアント限定）

認証情報が欠落している場合は 401 が返却されます。パスワード変更を反映するには WebUI の再起動が必要です。

クエリパラメータは認証情報そのものです

?key= はサーバーアクセスログやブラウザ履歴、スクリーンショット等に記録される危険があります。環境が許す限りヘッダー方式を利用してください。

クライアント設定例

ローカル環境：

json

{
  "mcpServers": {
    "azurpilot": {
      "url": "http://127.0.0.1:25548/mcp/sse",
      "headers": { "Authorization": "Bearer <WebUI パスワード>" }
    }
  }
}

リモートまたは LAN 経由：

json

{
  "mcpServers": {
    "azurpilot": {
      "url": "http://<IP_ADDRESS>:25548/mcp/sse",
      "headers": { "Authorization": "Bearer <WebUI パスワード>" }
    }
  }
}

ポート番号を変更している場合は適宜 URL を置き換えてください。

提供ツール一覧

合計 18 種類のツールが提供されています。

カテゴリ	ツール名	機能概要
インスタンス	`list_instances`	全インスタンスの一覧を取得
インスタンス	`get_status`	インスタンスの実行状態を取得
インスタンス	`start_instance`	インスタンスを起動
インスタンス	`stop_instance`	インスタンスを停止
タスク	`list_tasks`	全タスクの一覧を取得
タスク	`get_task_help`	タスクのヘルプ情報を取得
タスク	`trigger_task`	タスクを即座にトリガー実行
タスク	`get_scheduler_queue`	スケジューラーのキュー一覧を取得
タスク	`clear_scheduler_queue`	スケジューラーのキューをクリア
監視	`get_current_running_task`	現在実行中のタスク情報を取得
監視	`get_resources`	保有リソース（燃料・資金等）の状態を取得
監視	`get_config`	インスタンスの設定を取得
監視	`get_recent_logs`	直近のログを取得
監視	`get_screenshot`	現在の画面スクリーンショットを取得
設定	`update_config`	インスタンスの設定を更新
メンテナンス	`restart_emulator`	エミュレーターを再起動
メンテナンス	`restart_adb`	ADB サーバーを再起動
メンテナンス	`update_alas`	AzurPilot 本体のコードを更新

パラメータの仕様はサーバー側の宣言に準拠します

MCP クライアントは tools/list を介して各ツールの完全な JSON Schema を取得します。ここでは目的と機能概要のみを記載し、頻繁に更新される詳細パラメータ定義は省略しています。

代表的な利用シナリオ

AI Agent による定期パトロール

text

1. list_instances           → 登録インスタンスの確認
2. get_status(instance)     → 稼働状態・現在タスクの確認
3. get_recent_logs(...)     → エラーログの有無の検知
4. get_resources(...)       → 燃料や資金が枯渇していないか判定

手動トラブルシューティング介入

text

trigger_task(instance, task)   → 特定タスクの即時テスト
clear_scheduler_queue(...)     → キューに溜まったタスクの一括リセット
restart_adb(...)               → ADB 接続切断時の自動復帰

注意を要する操作

update_alas、restart_emulator、clear_scheduler_queue は実行中のタスクを強制中断します。Agent に自律実行させる前に、その影響範囲を確認してください。

Agent による無制限な設定変更の回避

update_config は設定を直接ディスクに永続化し、今後のスケジューリングに影響を及ぼします。楽観的ロック（revision）が存在しない外部からの変更は、ユーザーの手動編集を上書きするリスクがあります。

WebSocket との役割分担

機能	MCP	WebSocket
インスタンスの一覧・起動・停止	✅	✅
詳細な設定スキーマの読み書き	一部限定（`update_config`）	✅ 完全対応
リアルタイムストリーミング購読	❌	✅
スケジュールキューの詳細編集	❌	✅
AI クライアント向けプロトコル	✅	独自開発が必要

MCP は「AI Agent のためのコンパクトなインターフェース」、WebSocket は「GUI フロントエンドのための完全なインターフェース」として設計されています。

セキュリティ上の推奨事項

必要時のみ有効化し、公網へ恒常的にポートを開放しないでください。
WebUI には強力なパスワードを設定し、ゲームアカウントのパスワードと共通化しないでください。
リモート運用時は WSS や Cloudflare Tunnel 等を経由し、ポート 25548 を生でインターネットに公開しないでください。
Agent が実行したツール呼び出し履歴（特に書き込み・更新操作）を定期的に監査してください。
長期間利用しない場合は WebUI を再起動し、認証パスワードを変更してください。

トラブルシューティング

現象	主な原因と対策
401 Unauthorized	認証ヘッダーの欠落、パスワード間違い、パスワード変更後の WebUI 未再起動
接続が拒否される	ポート番号の不一致、または WebUI 起動時に MCP が無効化されている
ツール呼び出しがタイムアウト	インスタンスが重い処理を実行中でバックエンドの応答が遅延
古い設定値が返却される	設定キャッシュの影響。再度 `get_config` を呼び出してください
独立サービスが起動しない	ポート 22268 が OCR サービスに占有されています

MCP サービス

2つの稼働形態 ​

認証方式 ​

クライアント設定例 ​

提供ツール一覧 ​

代表的な利用シナリオ ​

AI Agent による定期パトロール ​

手動トラブルシューティング介入 ​

注意を要する操作 ​

WebSocket との役割分担 ​

セキュリティ上の推奨事項 ​

トラブルシューティング ​