安裝與註冊
nexus_mcp.exe 在哪裡
安裝版：%LOCALAPPDATA%\Programs\NexusTui\<通道>\nexus_mcp.exe（<通道> 是你安裝的更新通道）。
免安裝版：解壓出來的資料夾裡。它不是給人直接執行的——是 AI 工具在背景啟動它。
用 --print-config 產生設定
JSON 設定檔不會展開 %LOCALAPPDATA% 這類環境變數，而且路徑裡的反斜線要寫成 \。
手寫很容易錯，請讓 nexus_mcp.exe 自己印：
"%LOCALAPPDATA%\Programs\NexusTui\<通道>\nexus_mcp.exe" --print-config claude-desktop它會用自己的絕對路徑填好、跳脫好。畫面（stdout）上只有可以直接貼上的內容；設定檔放在哪裡的提示印在
另一個輸出（stderr），所以也可以直接用 > 檔案 導出去。它絕不會自己修改你任何 AI 工具的設定檔。
工具名稱打錯會列出支援的清單。
支援八種：claude-code、claude-desktop、codex、gemini、vscode、cursor、windsurf、cline。
各工具怎麼註冊
| 工具 | --print-config 參數 | 做法 |
|---|---|---|
| Claude Code | claude-code | 印出一行 claude mcp add --scope user nexus -- "<路徑>"，複製到終端機執行 |
| Claude Desktop | claude-desktop | 把 JSON 併進 %APPDATA%\Claude\claude_desktop_config.json（頂層是 mcpServers）。Microsoft Store 版的設定檔在 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\。存檔後完全結束再重開 Claude Desktop |
| Codex | codex | 兩種擇一：執行印出的 codex mcp add nexus -- "<路徑>"，或把印出的 [mcp_servers.nexus] 區塊加進 %USERPROFILE%\.codex\config.toml |
| Gemini CLI | gemini | 印出一行 gemini mcp add --scope user nexus "<路徑>"，複製執行 |
| VS Code（GitHub Copilot 代理模式） | vscode | 頂層是 servers、含 "type": "stdio"。放進工作區的 .vscode\mcp.json，或執行命令「MCP: Open User Configuration」開啟使用者層的 mcp.json |
| Cursor | cursor | 併進 %USERPROFILE%\.cursor\mcp.json（全域）或專案裡的 .cursor\mcp.json |
| Windsurf（現已改名 Devin Desktop） | windsurf | 在 Cascade 面板按 MCP 圖示 → Configure 開啟設定檔，再把 JSON 併進去（新版設定檔在 %APPDATA%\devin\mcp_config.json，舊版是 %USERPROFILE%\.codeium\windsurf\mcp_config.json） |
| Cline | cline | Cline 面板的 MCP Servers → Configure → Configure MCP Servers，開出 cline_mcp_settings.json 後把 JSON 併進去 |
「併進去」的意思是：設定檔裡已經有別的 MCP server 時，只把 "nexus": { ... } 這一段加進既有的
mcpServers（VS Code 是 servers）裡，不要整份覆蓋。
註冊完請重啟該 AI 工具，再問它「nexus 有哪些 tool」——應該看到 17 個。更新 nexus 之後也請重啟
AI 工具，讓它載入新版的 nexus_mcp.exe。
17 個工具一覽
tab 省略時，指的是呼叫當下焦點所在的分頁；回覆一律寫明實際用到的分頁。你在畫面上切換分頁，不會影響
AI 已經指定分頁的指令。
| 工具 | 做什麼 |
|---|---|
nexus_exec | 執行一行指令（跟在指令列輸入一樣），等到完成或逾時，回傳這個指令的 Log 輸出與它產出的檔案路徑 |
nexus_abort | 中止一支正在跑的 Lua 腳本 |
get_commands | 目前這個 nexus 的完整指令表（用法、說明）；下指令前先看 |
get_status | 版本、TUI／GUI、分頁與面板配置（每個面板有 window：0 是主視窗，1～8 是視窗版的獨立視窗）、UART 狀態、Plugin、regdef 檔、Lua 是否在跑；每個掛載有 plugin（設定的名稱）和 plugin_state（active／faulted／unloading／not_mounted，以它為準） |
get_log | 讀 Log：某個指令的輸出，或某個序號之後的所有紀錄 |
wait_event | 等到 Log 或 UART 出現含指定文字的新紀錄，或逾時 |
get_reg_snapshot | 目前快取的 256 位元組暫存器內容與「哪些是真的讀到」的遮罩 |
get_regdef_decoded | 用載入的暫存器定義檔解碼快取：欄位、列舉名稱、條件檢視 |
get_watch | 監看清單：值、觸發條件、觸發次數 |
get_trend | 某個監看值的歷史（降採樣成最多 200 點的 min／max）；缺口與尚無資料的點不帶值，不會被當成「沒變」；回覆附 CSV 檔名，可直接交給 read_file 讀完整細節。圖表請見趨勢圖表與 Excel |
get_uart_log | UART 收發紀錄（文字與原始位元組） |
get_plugin_widgets | Plugin 面板上的控件與目前的值（密碼欄只回星號） |
set_plugin_widget | 設定 Plugin 控件的值，或按下按鈕（密碼欄照常可寫，Log 不記內容） |
read_file | 讀 logs\ 底下的文字檔（分段） |
write_file | 寫檔到 logs\mcp\，回傳絕對路徑，之後可用 run、dump diff 等指令使用 |
term_read | 讀你已開好的 TERM 面板目前的畫面文字（每列一個字串）與游標位置；不含回捲內容。用法見範例 9 |
term_send | 把文字原樣當按鍵打進你已連線的 TERM（Enter 寫成 \r、Ctrl+C 寫成 \u0003）；Log 只記位元組數，不記內容。AI 不能自己 term open／term close |
幾個值得知道的行為：
- 回覆太大不會失敗：單次回覆的紀錄超過約 200 KB 就會截斷並附上「從這裡續讀」的標記，AI 會用
get_log接著讀，不會重跑指令。 - 等待時間建議 50 秒以內：許多 AI 工具約 60 秒就放棄等待並取消該次呼叫。取消時 nexus_mcp 不會重送，但
被取消的指令可能執行過也可能沒有（AI 拿不到它的編號），AI 重試前會先用
get_status／get_log查證， 不會盲目重跑。若被放棄的指令仍佔著 nexus，下一個呼叫可能要稍等或回「busy」。指令還在跑時，AI 會改用get_log或wait_event再問。 - 如果看到「nexus is busy with a user command」：代表你正在執行指令，AI 的請求排隊逾時了； 不是它的指令出了問題。等你的指令結束再重試就好。
- 「nexus 沒有在執行」：程式沒開。開起來之後直接再試，不必重啟 AI 工具。
常見問題
| 現象 | 處置 |
|---|---|
| 每個工具都說 nexus 沒有在執行 | 開啟 nexus_tui.exe 或 nexus_gui.exe 後再試一次 |
| 回「MCP is turned off by the user」 | Device > MCP server 或下 mcp on |
選單右邊是 unavailable | 連線名稱被別的程式佔住；程式每 2 秒重試，或下 mcp on |
| 說最多 8 個同時進行的呼叫已滿 | 等別的 AI 呼叫結束；wait_event 最久會佔一個 10 分鐘 |
| 說「may or may not have run」 | 請求送出後沒收到回覆；不會自動重送，請 AI 用 get_log 查證實際結果 |
| 更新後版本不符 | 重啟 AI 工具 |
| 拒絕連線，說對面不是目前使用者 | nexus 與 AI 工具必須由同一位 Windows 使用者執行 |
| 設定檔載入失敗 | 多半是路徑沒跳脫反斜線，或用了 %LOCALAPPDATA%；改用 --print-config 的輸出 |
| 升級或解除安裝時提示檔案被佔用 | AI 工具讓 nexus_mcp.exe 常駐；安裝程式會自動處理，仍卡住時先關閉 AI 工具 |