ETTerms/docs/serial-mcp-guide.md

Serial MCP 使用手冊

讓 Kiro CLI / Claude CLI 等 AI agent 直接收發 serial，而且你能在 ETTerms GUI 即時看到 AI 的每一筆收發。

---

這是什麼

ETTerms.SerialMcp 是一支獨立的 stdio MCP server。重點設計：

• COM port 由 ETTerms GUI 唯一持有，MCP server 自己不開 port。
• GUI 內跑一支本機 named pipe（\\.\pipe\etterms-serial）；MCP server 經這條 pipe 把 attach / write / read 轉發給 GUI，由 GUI 代為讀寫實體 port。
• AI 送出的資料會以 [AI] 標色 echo 進 GUI 終端機，所以你看到的就是 AI 看到的。

ETTerms GUI（唯一開 COM32 的人）
├─ Tab1: Serial 連線 COM32（即時顯示，AI 的寫入標 [AI]）
├─ named pipe: \\.\pipe\etterms-serial
└─ Tab2: PowerShell 跑 kiro-cli → 啟動 ETTerms.SerialMcp → 連回 pipe

---

前置需求

1. 已安裝 .NET 8（dotnet --list-runtimes 有 WindowsDesktop 8.0.x）。
2. 已編譯出 MCP 執行檔：

   cd <你的 repo>\ETTerms
   dotnet build ETTerms.slnx
   

   產物在：src\ETTerms.SerialMcp\bin\Debug\net8.0\ETTerms.SerialMcp.exe
3. 已安裝並可在終端機執行 kiro-cli。

---

步驟 1：註冊 MCP 到 Kiro

用編譯好的 exe 註冊（不要用 dotnet run——它會把建置訊息印到 stdout，污染 JSON-RPC）。 建議用 global scope，這樣不論從哪個工作目錄啟動 kiro 都抓得到：

kiro-cli mcp add --name serial --scope global --force `
  --command "<你的 repo>\ETTerms\src\ETTerms.SerialMcp\bin\Debug\net8.0\ETTerms.SerialMcp.exe"

成功會顯示：

✓ Added MCP server 'serial' to global config in C:\Users\<you>\.kiro\settings\mcp.json

設定檔位置：

• global：~\.kiro\settings\mcp.json
• workspace：<專案>\.kiro\settings\mcp.json（只在該目錄啟動 kiro 才生效）

---

步驟 2：重啟 kiro session

⚠️ MCP server 只在 kiro session 啟動時載入。 若你在註冊前就開著 kiro chat，必須重開：

1. 在 kiro chat 內輸入 /quit 回到 PowerShell。
2. 重新執行 kiro-cli。
3. 輸入 /mcp，應看到：

   serial   Status: ✓ Initialized
   Tools: serial_list, serial_attach, serial_write, serial_read, serial_detach
   

/mcp 顯示 Initialized 只代表 MCP server 起得來，還沒連 pipe（連 pipe 是第一次呼叫 serial 工具時才發生）。

---

步驟 3：使用

先在 ETTerms GUI 開好要操作的 serial 連線（雙擊側欄連線開分頁），AI 才能 attach 上去。

然後直接對 AI 講白話即可，例如：

列出目前的 serial session，接上 COM32，送 root 然後讀回應。

AI 會依序呼叫 serial_list → serial_attach → serial_write → serial_read， 而你在 GUI 的 COM32 分頁會即時看到紫色 [AI] root 與裝置回應。

⚠️ 重要：session 名稱 = COM port 名稱

GUI 裡連線的顯示名稱（例如 BP1）與橋接用的session 名稱不同。 serial_list 回傳的是 COM port 名稱（例如 COM32），attach 時要用它：

GUI 顯示	serial_list 回傳 / attach 用
BP1	COM32
BP2	COM17

---

工具清單

工具	參數	說明
serial_list	—	列出 GUI 目前開著的 serial session（名稱 + baud）
serial_attach	portName（如 COM32）	綁定到某個 GUI session；write/read 前必須先 attach
serial_write	text, appendNewline（預設 true）	送出文字（GUI 以 [AI] 標色顯示）
serial_read	waitFor?（等待子字串）, timeoutMs?（預設 3000）	取出累積的 RX，回傳後清空 buffer
serial_detach	—	解除綁定（不會關閉 GUI 的 port）

---

疑難排解

症狀	原因	解法
/mcp 顯示 0 configured	還沒註冊，或 kiro session 早於註冊就開了	執行步驟 1，再 /quit 重開 kiro
/mcp 註冊了但仍看不到	用了 workspace scope，但 kiro 的工作目錄不同	改用 --scope global --force 重註冊
工具回 bridge not connected; is the ETTerms GUI running?	ETTerms GUI 沒開	先開 GUI（GUI 啟動時才會起 pipe server）
工具回 no open serial session '...' in GUI	該 COM port 在 GUI 沒開，或名稱打錯	先在 GUI 開該連線；用 serial_list 確認正確的 COM 名稱
pipe 行為怪異 / 收不到	同時有別的程式佔用 pipe	pipe 一次只服務一個 client，關掉其他連 etterms-serial 的程式
註冊後 stdout 有奇怪輸出	用了 dotnet run 當 command	改用編譯好的 .exe 路徑

---

移除

kiro-cli mcp remove --name serial

---

進階：用 agent.json 設定（替代 mcp add）

也可直接寫進 agent 設定的 mcpServers（global：~\.kiro\settings\mcp.json）：

{
  "mcpServers": {
    "serial": {
      "command": "<你的 repo>\\ETTerms\\src\\ETTerms.SerialMcp\\bin\\Debug\\net8.0\\ETTerms.SerialMcp.exe"
    }
  }
}