# MCP J-Link Server

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-STDIO-green)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

透過 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 讓 AI 直接控制 [SEGGER J-Link](https://www.segger.com/products/debug-probes/j-link/) 嵌入式除錯探針。

讓 AI 自動讀取暫存器、分析記憶體、燒錄韌體、追蹤 RTT 日誌 — 用自然語言描述問題，AI 幫你除錯。

## 功能概覽

| 群組 | 工具 | 說明 |
|------|------|------|
| 探索 | `jlink_list_emulators` `jlink_get_status` | 列舉探針、查看連線狀態 |
| 連線 | `jlink_open` `jlink_connect` `jlink_close` | 開啟/連線/關閉探針 |
| 記憶體 | `jlink_memory_read` `jlink_memory_write` | 讀寫記憶體（8/16/32-bit） |
| 燒錄 | `jlink_flash_file` `jlink_erase_chip` | 韌體燒錄、全片擦除 |
| 執行控制 | `jlink_reset` `jlink_halt` `jlink_go` `jlink_step` | 重置/暫停/繼續/單步 |
| 暫存器 | `jlink_register_read` `jlink_register_read_all` `jlink_register_write` | 讀寫 CPU 暫存器 |
| RTT | `rtt_start` `rtt_read` `rtt_write` `rtt_stop` `rtt_get_status` | SEGGER RTT 即時通訊 |

共 **21 個 MCP 工具**，涵蓋嵌入式除錯的完整工作流程。

## 前置需求

- **Python 3.10+**
- **SEGGER J-Link Software** — [下載安裝](https://www.segger.com/downloads/jlink/)
- **J-Link 探針**（USB 連接）

> **注意**：Python 位元數必須與 J-Link DLL 匹配（64-bit Python 需要 `JLink_x64.dll`）。

## 安裝

```bash
git clone https://github.com/你的帳號/MCP_JLINK.git
cd MCP_JLINK
pip install -e .
```

驗證安裝：

```bash
python -m mcp_jlink
```

伺服器啟動後會透過 STDIO 等待 MCP 請求（按 `Ctrl+C` 結束）。

## 整合設定

### Claude Code / Antigravity

將以下設定加入 MCP 設定檔：

```json
{
  "mcpServers": {
    "jlink": {
      "command": "python",
      "args": ["-m", "mcp_jlink"],
      "cwd": "/path/to/MCP_JLINK"
    }
  }
}
```

### Claude Desktop

在 `claude_desktop_config.json` 中加入相同設定。

## 使用範例

設定完成後，直接用自然語言與 AI 對話：

```
你：我的板子卡住了，幫我看一下停在哪裡
AI：（自動執行 jlink_open → jlink_connect → jlink_halt → 讀取 PC/LR 暫存器 → 分析）
    程式停在 0x0800_1A3C，位於 SysTick_Handler 中。
    LR = 0xFFFF_FFF9，表示從 Thread Mode 進入中斷。
    看起來是 SysTick 中斷處理函式內的無限迴圈...
```

```
你：幫我燒錄 firmware.hex 到 STM32F407VG
AI：（自動執行 jlink_open → jlink_connect("STM32F407VG") → jlink_flash_file → jlink_reset）
    韌體燒錄完成！已寫入 32,768 bytes，耗時 1.2 秒。目標已重置並開始執行。
```

```
你：開啟 RTT 日誌，讓我看看板子在印什麼
AI：（自動執行 rtt_start → rtt_read → 持續讀取）
    RTT Channel 0 輸出：
    [INFO] System boot OK
    [INFO] Sensor init: BME280 detected
    [WARN] WiFi connection timeout, retrying...
```

## J-Link DLL 搜尋

本專案不內含 J-Link SDK，DLL 搜尋優先順序：

1. 環境變數 `JLINK_SDK_PATH`
2. SEGGER 預設安裝路徑下的 `JLink*` 目錄（自動匹配帶版本號名稱如 `JLink_V922`）
3. pylink-square 內建搜尋

## 專案架構

```
src/mcp_jlink/
├── server.py        # FastMCP 伺服器 + 21 個 MCP tool 定義
├── connection.py    # JLinkManager 連線狀態機（單例）
├── errors.py        # 自訂例外 + 前置條件裝飾器
├── __main__.py      # python -m mcp_jlink 進入點
└── __init__.py

skills/               # AI 除錯情境指南（按需載入）
├── SKILL.md          # 主索引 + 情境路由表
├── crash-analysis.md
├── hardfault-diagnosis.md
├── peripheral-verification.md
├── flash-and-verify.md
├── rtt-logging.md
├── memory-leak-detection.md
├── variable-monitoring.md
├── interrupt-analysis.md
├── low-power-debug.md
└── batch-flashing.md
```

## 連線狀態機

```
DISCONNECTED ──open()──> PROBE_OPEN ──connect()──> TARGET_CONNECTED ──rtt_start()──> RTT_ACTIVE
     ^                      |                           |                              |
     └──────close()─────────┴──────────close()──────────┴──────────close()─────────────┘
```

每個工具透過裝飾器自動檢查前置條件，不需要手動管理連線狀態。

## 開發

```bash
# 安裝開發相依
pip install -e ".[dev]"

# 執行測試
pytest
```

## License

MIT