# 使用 uv
uv pip install git+https://github.com/konbakuyomu/pyocd-debug-mcp.git

# 使用 pip
pip install git+https://github.com/konbakuyomu/pyocd-debug-mcp.git

# 如需 SVD 字段级解析（可选）
uv pip install "pyocd-debug-mcp[svd] @ git+https://github.com/konbakuyomu/pyocd-debug-mcp.git"

git clone https://github.com/konbakuyomu/pyocd-debug-mcp.git
cd pyocd-debug-mcp
uv sync          # 创建虚拟环境并安装依赖

uv run pyocd pack install hc32f460
uv run pyocd pack install hc32f4a0

{
  "mcpServers": {
    "pyocd-debug": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/pyocd-debug-mcp",
        "run", "pyocd-debug-mcp"
      ]
    }
  }
}

claude mcp add pyocd-debug -- uv --directory /path/to/pyocd-debug-mcp run pyocd-debug-mcp

{
  "servers": {
    "pyocd-debug": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/pyocd-debug-mcp",
        "run", "pyocd-debug-mcp"
      ]
    }
  }
}

{
  "target": "hc32f4a0xi",
  "firmware": "build/usart_uart_dma_Debug/usart_uart_dma.hex",
  "elf": "build/usart_uart_dma_Debug/usart_uart_dma.axf",
  "svd": "HC32F4A0PIHB.svd"
}

AI: pyocd_project_load("/path/to/project")    → 自动扫描发现文件
AI: pyocd_project_init("/path/to/project",    → 创建配置
      target="hc32f4a0xi",
      firmware="build/xxx.hex",
      elf="build/xxx.axf",
      svd="HC32F4A0PIHB.svd")

AI: pyocd_probe_list                           → 发现探针
AI: pyocd_session_connect("hc32f460xe")        → 连接
AI: pyocd_flash_program("firmware.hex")        → 烧录
AI: pyocd_elf_attach("firmware.elf")           → 加载符号
AI: pyocd_breakpoint_set(symbol="main")        → 在 main 打断点
AI: pyocd_target_reset(halt=true)              → 复位并停止
AI: pyocd_target_wait_halt(timeout=10)         → 等待命中 main

AI: pyocd_breakpoint_set(symbol="UART_RxCallback")
AI: pyocd_target_wait_halt(timeout=60)         ← 等待数据到来
    ... 60s 内数据到达，断点命中 ...
AI: pyocd_memory_dump(rx_buffer_addr, 64)      → 查看接收缓冲区
AI: pyocd_register_read_all()                  → 查看寄存器现场

AI: pyocd_debug_sample_variable(
      address=0x20001000,   # 全局变量地址
      interval=0.5,          # 每 0.5s
      count=200              # 共 200 次 = 100s
    )
→ 返回所有采样值 + min/max/变化统计

AI: pyocd_debug_fault_analyze()
→ 返回:
  - fault_type: "BusFault"
  - fault_address: "0x40012400"
  - active_faults: [PRECISERR, BFARVALID]
  - exception_frame: {PC_fault, LR_saved, R0-R3, ...}
  - exc_return: {stack_used: "PSP", fpu_context: ...}

AI: pyocd_watchpoint_set(
      address=0x20002000,    # 数组末尾地址
      size=4,
      access_type="write"    # 监控越界写入
    )
AI: pyocd_target_wait_halt(timeout=30)
    ... 越界写入发生，DWT 触发停止 ...
AI: pyocd_target_status()                      → 查看 PC 定位到写入指令
AI: pyocd_debug_backtrace()                    → 查看完整调用链

AI: pyocd_debug_backtrace(max_frames=16)
→ 返回:
  frames:
    [0] USART_RxCallback+0x1A          (pc=0x0800135C)
    [1] DMA_IrqHandler+0x18            (unwound via DWARF CFI)
    [2] main+0x42                      (unwound via DWARF CFI)
  method: "dwarf_cfi"                   ← AC6/GCC: .debug_frame 精确展开
  method: "ehabi"                       ← AC5: .ARM.exidx 精确展开
  method: "heuristic"                   ← 无调试信息时: 栈扫描 + BL 验证

# wait_halt 断点命中时自动附带简短 backtrace:
AI: pyocd_target_wait_halt(timeout=30)
→ { ..., "backtrace": ["UART_RxCallback", "DMA_IrqHandler+0x18", "main+0x1A"] }

# fault_analyze 崩溃时自动附带 backtrace:
AI: pyocd_debug_fault_analyze()
→ { ..., "backtrace": ["HardFault_Handler", "memcpy+0x12", "cJSON_Parse+0x8A", ...] }

# 两种格式等价
AI: pyocd_memory_read(address=0x20000000, size=16)
AI: pyocd_memory_read(address="0x20000000", size=16)

# 断点也支持
AI: pyocd_breakpoint_set(address="0x0800135C")

# 监视点同理
AI: pyocd_watchpoint_set(address="0x20001000", access_type="write")

# read_symbol: 一步读取变量（自动查找地址 + 读取内存 + 类型推断）
AI: pyocd_read_symbol(name="g_rxBuffer")
→ { "name": "g_rxBuffer", "address": "0x20000100", "size": 64,
     "hex_dump": "48 65 6C 6C 6F ...", "as_string": "Hello..." }

# step_out: 执行到当前函数返回
AI: pyocd_target_step_out(timeout=5.0)
→ { "status": "returned", "from_function": "UART_RxCallback",
     "returned_to": "DMA_IrqHandler+0x18" }

pyocd-debug-mcp/
├── pyproject.toml              # 项目配置和依赖
├── src/pyocd_debug_mcp/
│   ├── server.py               # MCP Server 入口，58 个工具注册
│   ├── session_manager.py      # 会话生命周期管理（单例）
│   └── tools/
│       ├── probe.py            # 探针发现
│       ├── target.py           # 目标控制
│       ├── flash.py            # Flash 烧录 + 校验
│       ├── register.py         # 寄存器读写
│       ├── memory.py           # 内存读写
│       ├── breakpoint.py       # 断点管理（HW/SW/AUTO + Reset 恢复）
│       ├── watchpoint.py       # 监视点管理
│       ├── elf.py              # ELF 符号解析
│       ├── svd.py              # SVD 外设寄存器（含批量更新、枚举、描述）
│       ├── rtt.py              # RTT 实时传输（SEGGER RTT 通道读写）
│       ├── debug.py            # 高级调试（故障分析、栈回溯、栈检查、采样）
│       └── project.py          # 项目配置（.pyocd-debug.json 管理）
└── tests/