etwenandClaude Opus 4.8
28538594d7
Phase 9 (AI integration) complete -- AI agents can send/receive serial while the user watches live in the GUI, with the GUI as sole COM-port owner. - ETTerms.SerialMcp: stdio MCP server (net8.0 + ModelContextProtocol SDK) exposing serial_list / serial_attach / serial_write / serial_read (waitFor + timeoutMs) / serial_detach; forwards over named pipe. - GUI SerialBridgeServer (pipe etterms-serial) + SerialBridge endpoint; SessionPage.WriteFromAi echoes MCP-sourced TX tagged [AI] (magenta). - App icon: window title bar / taskbar / exe now use Choco_256x256.ico (embedded via AppAssets); title bar shows ETTerms Version vX.Y.Z. - About page: large Choco icon (Zoom, no crop). - Docs: ARCHITECTURE.md + CLAUDE.md mark Phase 9 done; docs/serial-mcp-guide.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
143 lines
5.1 KiB
Markdown
143 lines
5.1 KiB
Markdown
# 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 執行檔：
|
||
```powershell
|
||
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 都抓得到：
|
||
|
||
```powershell
|
||
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` 路徑 |
|
||
|
||
---
|
||
|
||
## 移除
|
||
|
||
```powershell
|
||
kiro-cli mcp remove --name serial
|
||
```
|
||
|
||
---
|
||
|
||
## 進階：用 agent.json 設定（替代 mcp add）
|
||
|
||
也可直接寫進 agent 設定的 `mcpServers`（global：`~\.kiro\settings\mcp.json`）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"serial": {
|
||
"command": "<你的 repo>\\ETTerms\\src\\ETTerms.SerialMcp\\bin\\Debug\\net8.0\\ETTerms.SerialMcp.exe"
|
||
}
|
||
}
|
||
}
|
||
```
|