MCP 服務

MCP（Model Context Protocol）讓支援該協議的客戶端（編輯器、Agent 工具）直接查詢和控制 AzurPilot。它是另一條入口，不是 WebSocket API 的替代品。

兩種運行方式

方式	端點	説明
隨 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=<密码>`（僅限無法自定義 Header 的客戶端）

不帶憑據返回 401。修改密碼後需要重新啟動 WebUI，MCP 才會使用新密碼。

查詢參數就是憑據

?key= 會出現在日誌、歷史記錄與截圖中。有條件就改用 Header。

客戶端配置

本地：

json

{
  "mcpServers": {
    "azurpilot": {
      "url": "http://127.0.0.1:25548/mcp/sse",
      "headers": { "Authorization": "Bearer <WebUI 密码>" }
    }
  }
}

遠程或內網：

json

{
  "mcpServers": {
    "azurpilot": {
      "url": "http://<IP_ADDRESS>:25548/mcp/sse",
      "headers": { "Authorization": "Bearer <WebUI 密码>" }
    }
  }
}

連接埠被改過時同步替換。

工具清單

共 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。這裏只説明用途，不復制容易過期的參數定義。

典型用法

讓 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 是「給 Agent 的窄介面」，WebSocket 是「給前端的完整介面」。

安全建議

只在需要時開啟，不要長期暴露到公網。
密碼要強，且與遊戲帳號不同。
遠程訪問優先走 WSS / Tunnel，不要把 25548 直接映射到公網。
查看 Agent 的工具調用記錄，尤其是寫操作。
不用時重新啟動 WebUI 並更換密碼。

疑難排解

現象	原因
401	未帶憑據、密碼錯誤、改密碼後未重新啟動
連接被拒	連接埠不對，或 MCP 未隨 WebUI 啟動
工具調用超時	實例正在執行長任務，後端繁忙
返回舊配置	配置快取，重新 `get_config`
獨立服務起不來	22268 被 OCR 佔用

MCP 服務

兩種運行方式 ​

鑑權 ​

客戶端配置 ​

工具清單 ​

典型用法 ​

讓 Agent 巡檢 ​

手動干預 ​

危險操作 ​

與 WebSocket 的分工 ​

安全建議 ​

疑難排解 ​