MCP 快速開始

用程式設計代理開發自動化，儲存 Python 任務後重復執行。你需要 Windows、Python 3.11 或更高版本、目標應用或 ADB 裝置，以及支援 MCP 和本地檔案、程序訪問的程式設計代理。

1. 開啟應用專案

使用已有的 ok-script 應用，或從 ok-script-app 模板建立專案。在程式設計代理中開啟應用目錄。業務任務儲存在這個專案裡，與 ok-script 框架倉庫分開。

可以這樣告訴代理：

準備這個自動化專案的虛擬環境和依賴，保留現有依賴約束和 ok-script 版本。配置我的目標應用，分別提供 MCP 開發入口和使用者 GUI 入口。有可用技能時讀取 setup-env 和 setup-project。不要使用 Computer Use 工具。

新建環境的基本命令：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install "ok-script[default]"

已有應用先安裝自己的依賴。MCP 自 2.0.17 起為必需依賴，隨 ok-script 自動安裝。按需新增 qt、adb 或 ocr。OpenCV 需要單獨安裝，且只能選擇一個相容變體，例如 opencv-python 或 opencv-python-headless；讓代理沿用專案現有選擇。

專案還需要配置真實目標。讓代理檢查已安裝版本的配置實現及已有示例，設定應用執行檔、視窗或 ADB 包名，並驗證截圖和輸入。安裝包本身不會自動建立已配置的應用。

2. 啟動 MCP 執行時

優先使用專案已有的開發入口。否則，在應用目錄執行：

.\.venv\Scripts\python.exe -m ok mcp --config src.config:config

將 src.config:config 替換為實際配置模組和物件。開發期間保持程序執行。該模式不需要 Qt，普通任務排程器保持暫停。

已有桌面應用也可在設定 > 基礎選項 > 啟用 MCP 服務中開啟。開啟前閱讀應用顯示的訪問提示。日常使用應保留獨立的、停用 MCP 的 GUI 入口。

3. 連線程式設計代理

從專案配置的產物目錄讀取 logs/mcp/connections/<pid>-<port>.json 中的有效記錄，其中包含服務 URL、bearer token、程序身份和專案目錄。預設埠為 8765，但可能變化，不要寫死。

代理 MCP 客戶端使用以下連線資訊：

設定	值
傳輸	Streamable HTTP
URL	有效連線記錄中的 `url`
HTTP 請求頭	`Authorization: Bearer <有效记录中的 token>`

各客戶端配置格式不同，讓代理按它支援的方式配置並保管 token。服務只監聽本機迴環地址，因此代理應執行在同一臺機器上，並能訪問專案檔案。沒有原生 MCP 連線能力時，可讓代理用官方 MCP Python SDK 編寫本地客戶端。

讓代理呼叫 list_skills()、讀取 get_skill("develop")，再用 screenshot() 確認目標。如果截圖錯誤或無法截圖，先修復配置再執行任務。詳見 MCP 連線說明（英文）。

4. 提出可複用任務需求

使用這個專案的 MCP 連線，開發可複用 Python 任務：開啟設定、啟用“顯示詳情”、儲存，並驗證該選項保持開啟。先讀相關技能並核實已安裝 API 的簽名。程式碼儲存在正式任務模組裡；每次 MCP 嘗試前恢復並驗證起始狀態，記錄日誌和截圖，斷言可見結果，並驗證重複執行。使用 ok-script 截圖和輸入，不使用 Computer Use。註冊任務，使其無需代理或大模型呼叫即可執行。

代理在本地編寫檔案，並將絕對路徑提交給 MCP。修改已有任務時，先發現原始原始碼、原地編輯、過載已註冊任務，等待過載成功後再測試。查詢 API 和維護任務的完整示例見提示詞指南。

5. 脫離代理執行

讓代理給出專案真實任務名和入口。儲存的任務必須已註冊，並在普通執行時自行準備狀態；GUI/CLI 不會自動呼叫 MCP 的恢復鉤子。

普通 CLI 執行前，停止 MCP 開發執行時並等待退出。同一專案啟動 GUI 會替換已註冊的控制台執行時並關閉它的 MCP 連線。不要在任務嘗試尚未結束時切換模式。典型命令如下：

.\.venv\Scripts\python.exe -m ok run_task EnableOptionTask --config src.config:config
.\.venv\Scripts\python.exe -m ok gui --config src.config:config

選擇 CLI 或 GUI 其中一種執行，不要同時啟動。CLI 引數是已註冊任務名或類名，不是 Python 檔案路徑。日常 GUI 使用優先選擇應用提供的、停用 MCP 的 pythonw.exe 入口或快捷方式；GUI 需要 Qt 依賴。

將任務原始碼、配置、識別素材和依賴約束一起儲存。本地 Python 識別與輸入在日常執行時不消耗模型 Token；新增需求或需要修復時再找程式設計代理。