stm32-stlink-mcp

Servidor MCP para depurar microcontroladores STM32 a través de ST-LINK, construido sobre el conjunto de herramientas STM32CubeCLT de STMicroelectronics — ST-LINK_gdbserver, STM32_Programmer_CLI y arm-none-eabi-gdb (controlado mediante GDB/MI2). No se utiliza OpenOCD, J-Link ni probe-rs.

Arquitectura

Una sesión de depuración es un par de procesos hijos, que refleja exactamente el flujo de trabajo documentado por 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 se controla en modo MI2 para que el servidor obtenga paso a paso a nivel de fuente, puntos de interrupción simbólicos y evaluación de expresiones con conocimiento de símbolos de forma gratuita, en lugar de implementar manualmente el Protocolo Serial Remoto de GDB. ST-LINK_gdbserver posee el manejador USB de la sonda durante toda la sesión; el flasheo mediante load de gdb (MI: -target-download) es delegado transparentemente por el servidor a STM32CubeProgrammer, por lo que no se necesita desmontar la sesión para reflashear. Un flasheo independiente de un solo disparo (flash_standalone, sin sesión requerida) invoca directamente a STM32_Programmer_CLI y por lo tanto entra en conflicto con una sesión ya abierta en la misma sonda — consulte la descripción de la herramienta.

Related MCP server: dbgprobe-mcp-server

Instalación

npm install
npm run build

Requiere que STM32CubeCLT esté instalado y que sus directorios bin/ sean accesibles — ya sea en PATH (el instalador de CLT lo hace por defecto) o mediante STMCP_CUBECLT_PATH / anulaciones por herramienta. Ejecute npm run doctor para comprobarlo.

Ejecución

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

Registro con un cliente MCP

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

Configuración (variables de entorno)

Herramientas

Diferido a v2

Herramientas de registros periféricos SVD (memory_read/write + evaluate_expression ya alcanzan todo por dirección), sondeo de memoria en vivo/streaming, un sistema de plugins, listas blancas de regiones de memoria por chip, paso directo arbitrario de monitor de gdb, y herramientas de option-bytes/RDP (capaces de bloquear el dispositivo, intencionalmente fuera de alcance).

RTT

RTT (SEGGER Real Time Transfer — trazado en vivo de consola/variables sin detención) está intencionalmente no implementado en este servidor. El stub GDB/MI de ST-LINK_gdbserver no tiene modo no-stop, por lo que leer memoria a través de la sesión debug_connect de este servidor requiere detener el núcleo primero — lo que contradice el propósito de RTT. El mecanismo correcto es el acceso directo a memoria AP que nunca detiene el núcleo (confirmado al leer el código fuente de STM32CubeMonitor de ST, que usa exactamente esto, y por -r32fast de STM32_Programmer_CLI).

Eso es lo que strtt ya hace, y strtt-mcp lo envuelve como su propio servidor MCP (strtt_start/strtt_stop/strtt_status/strtt_read/strtt_write). Regístrelo junto a este servidor en lugar de a través de él:

{
  "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>" }
    }
  }
}

Inicie strtt_start con tcp: true para conectarse a través del servidor ST-LINK compartido en lugar de reclamar el dispositivo USB directamente — esto permite que se ejecute concurrentemente con una sesión debug_connect abierta aquí, ya que GdbServerProcess siempre pasa -t/--shared a ST-LINK_gdbserver. Sin tcp: true, strtt y una sesión de depuración abierta competirán por la misma sonda.

Manual de verificación de hardware

Con un ST-LINK y un objetivo conectados:

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

Luego, mediante el inspector o un cliente MCP:

1. list_probes → aparece el serial de la sonda.

2. debug_connect { elfPath, device, interface: "swd", serial } → devuelve un sessionId.

3. breakpoint_set { sessionId, location: "main" } → devuelve un número de punto de interrupción.

4. debug_run { sessionId } → se detiene con 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 } → indicadores benignos/cero justo después del reinicio.

8. debug_disconnect { sessionId } → confirme que no hay procesos huérfanos: ps aux | grep -E 'ST-LINK_gdbserver|arm-none-eabi-gdb'.

9. flash_standalone { file, reset: "hard", run: true } sin ninguna sesión abierta.

10. Prueba negativa: abra una sesión, luego llame a flash_standalone en el mismo serial → espere DEVICE_BUSY.

Nota: debug_connect detiene la CPU del objetivo. No se conecte a una placa que esté manejando activamente actuadores/salidas de manera que una detención no planificada sea insegura, sin antes confirmar que está bien.