stm32-stlink-mcp

MCP-сервер для отладки микроконтроллеров STM32 через ST-LINK, построенный на собственном наборе инструментов STMicroelectronics STM32CubeCLT — ST-LINK_gdbserver, STM32_Programmer_CLI и arm-none-eabi-gdb (управляется через GDB/MI2). Без участия OpenOCD, J-Link или probe-rs.

Архитектура

Сеанс отладки — это пара дочерних процессов, в точности повторяющая документированный рабочий процесс ST (UM2576, «STM32CubeIDE ST-LINK GDB server»):

 arm-none-eabi-gdb  --interpreter=mi2  --(TCP, target extended-remote)-->  ST-LINK_gdbserver  --(USB)-->  ST-LINK  --(SWD)-->  STM32

arm-none-eabi-gdb работает в режиме MI2, поэтому сервер получает пошаговое выполнение на уровне исходного кода, символьные точки останова и вычисление выражений с учётом символов без дополнительных усилий, вместо того чтобы самостоятельно реализовывать GDB Remote Serial Protocol. ST-LINK_gdbserver владеет USB-дескриптором программатора в течение всего времени жизни сеанса; прошивка через gdb-команду load (в MI — -target-download) прозрачно делегируется сервером инструменту STM32CubeProgrammer, поэтому для перепрошивки не требуется завершать сеанс. Автономная однократная прошивка (flash_standalone, сеанс не требуется) вызывает STM32_Programmer_CLI напрямую и поэтому конфликтует с уже открытым сеансом на том же программаторе — см. описание инструмента.

Related MCP server: dbgprobe-mcp-server

Настройка

npm install
npm run build

Требуется установленный STM32CubeCLT и доступные каталоги bin/ — либо уже в PATH (установщик CLT делает это по умолчанию), либо через STMCP_CUBECLT_PATH / переопределения для отдельных инструментов. Выполните npm run doctor для проверки.

Запуск

node dist/index.js serve     # starts the MCP server on stdio (default mode)
node dist/index.js doctor    # pre-flight check: tool resolution, connected probes, udev rules
node dist/index.js doctor --json

Регистрация в MCP-клиенте

{
  "mcpServers": {
    "stm32-stlink": {
      "command": "node",
      "args": ["<path-to-this-repo>/stmcp/dist/index.js"]
    }
  }
}

Конфигурация (переменные окружения)

Инструменты

Отложено до v2

Инструменты для регистров периферии SVD (memory_read/write + evaluate_expression уже обращаются ко всему по адресу), живой/потоковый опрос памяти, система плагинов, списки разрешённых областей памяти для каждого чипа, произвольный проброс команд gdb monitor, а также инструменты option-bytes/RDP (способные «окирпичить» устройство; намеренно вне области охвата).

RTT

RTT (SEGGER Real Time Transfer — живая трассировка консоли/переменных без остановки ядра) намеренно не реализован в этом сервере. У GDB/MI-заглушки ST-LINK_gdbserver нет режима non-stop, поэтому чтение памяти через сеанс debug_connect этого сервера требует сначала остановить ядро — что сводит на нет смысл RTT. Правильный механизм — прямой доступ к памяти AP, который никогда не останавливает ядро (подтверждено чтением исходного кода STM32CubeMonitor от ST, в котором используется именно это, а также опцией -r32fast из STM32_Programmer_CLI).

Именно это уже делает strtt, а strtt-mcp оборачивает его в собственный MCP-сервер (strtt_start/strtt_stop/strtt_status/strtt_read/strtt_write). Регистрируйте его рядом с этим сервером, а не через него:

{
  "mcpServers": {
    "stm32-stlink": { "command": "node", "args": ["<...>/mcp-server/dist/index.js"] },
    "strtt": {
      "command": "node",
      "args": ["<path-to-strtt-repo>/mcp/dist/index.js"],
      "env": { "STRTT_BIN": "<path-to-strtt-binary>" }
    }
  }
}

Запускайте strtt_start с параметром tcp: true, чтобы подключаться через общий ST-LINK Server, а не захватывать USB-устройство напрямую — это позволяет ему работать одновременно с открытым сеансом debug_connect здесь, поскольку GdbServerProcess всегда передаёт -t/--shared серверу ST-LINK_gdbserver. Без tcp: true strtt и открытый сеанс отладки будут конкурировать за один и тот же программатор.

Сценарий проверки на оборудовании

При подключённых ST-LINK и целевом устройстве:

node dist/index.js doctor                     # confirm probe + tools resolve
npx @modelcontextprotocol/inspector node dist/index.js   # interactive tool testing

Затем через инспектор или MCP-клиент:

1. list_probes → появляется серийный номер программатора.

2. debug_connect { elfPath, device, interface: "swd", serial } → возвращает sessionId.

3. breakpoint_set { sessionId, location: "main" } → возвращает номер точки останова.

4. debug_run { sessionId } → останавливается с reason: "breakpoint-hit".

5. register_read { sessionId, registers: ["pc","sp","lr","r0"] }.

6. evaluate_expression { sessionId, expression: "<a known global>" }.

7. read_fault_registers { sessionId } → безобидные/нулевые флаги сразу после сброса.

8. debug_disconnect { sessionId } → убедитесь, что не осталось осиротевших процессов: ps aux | grep -E 'ST-LINK_gdbserver|arm-none-eabi-gdb'.

9. flash_standalone { file, reset: "hard", run: true } без открытого сеанса.

10. Негативный тест: откройте сеанс, затем вызовите flash_standalone на том же серийном номере → ожидайте DEVICE_BUSY.

Примечание: debug_connect останавливает CPU целевого устройства. Не подключайтесь к плате, которая активно управляет исполнительными механизмами/выходами, в ситуации, когда незапланированная остановка может быть небезопасна, предварительно не убедившись, что это допустимо.