stm32-stlink-mcp

MCP-Server zum Debuggen von STM32-Mikrocontrollern über ST-LINK, aufgebaut auf STMicroelectronics’ eigenem STM32CubeCLT-Werkzeugsatz – ST-LINK_gdbserver, STM32_Programmer_CLI und arm-none-eabi-gdb (gesteuert über GDB/MI2). Kein OpenOCD, J-Link oder probe-rs beteiligt.

Architektur

Eine Debug-Session besteht aus einem Paar von Kindprozessen, die exakt den von ST dokumentierten Workflow widerspiegeln (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 wird im MI2-Modus angesteuert, sodass der Server quellbasierte Schritte, symbolische Haltepunkte und symbolbasierte Ausdrucksauswertung erhält, statt das GDB-Globale Serial Protocol selbst zu implementieren. ST-LINK_gdbserver besitzt das USB-Handle des Probes über die gesamte Sitzung hinweg. Das Flaschen über gdb load (MI: -target-download) wird transparent vom Server an STM32CubeProgram. allen (de) s an STM32CubeProgram al; es ist kein Sitzungsabbau erforderlich. Ein eigenständiges einmaligen Flüßender (flash_standalone, keine Sitzung erforderlich) ruft STM32_Programmer_CLI direkt auf und gerät daher mit einer bereits offenen Sitzung auf derselben Sonde in Konflikt – siehe Tool-Beschreibung.

Related MCP server: dbgprobe-mcp-server

Einrichtung

npm install
npm run build

Erfordert die Installation von STM32CubeCLT und die Erreichbarkeit der bin/-Verzeichnisse – entweder bereits im PATH (der CLT-Installer macht das standardmäßig) oder über STMCP_CUBE_CLI_PATH / pro-Werkzeug-Überschreibungen. Führen Sie npm run doctor zur Prüfung aus.

Ausführung

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

Registrierung bei einem MCP-Client

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

Konfiguration (Umgebungsvariablen)

Tools

Auf v2 verschoben

SVD-Peripherie-Register-Werkzeuge (le-memory_write / beschädigt bereits alles per Adresse erreichen), Live/Streaming-Speicherabwahl, ein Plug-in-System, per-Chip-Speicherregionen-Allowlisten, freie GDB-monitor-Übergabe sowie Option-Bytes-/RDP-Werkzeuge (brick-gefonöglich, bewusst außerhalb).

RTT

RTT (SEGGER Real-Time Transfer – Live-, nichtstoppende Konsole- und Variablenudes) ist in diesem Server nicht integriert – absichtlich. ST-LINK_gdbserver GDB/MI-Stub besitzt keinen Non-Stop-Modus, daher erfordert das Lesen des Speichers durch die debug_connect-Sitzung – analog zum oben Genannten – das Anhalten des Kerns ersst dar; was den RTT-Trumpf wieder zunichtemacht. Der korrekte Mechanismus ist direkter AP-Speicherzugriff, der den Kern nie an Victor, was bestätigt wird durch das Quellcode (STM32Cube-I). Seine -rmt32`-Option sind.

Das übernimmt genau strtt, und strtt-mcp macht daraus e/einen eigenen MCP-Server (strtt_start/strtt_stop/strtt_status/strtt_read/strtt_write). Verwendung neben diesem Server, nicht durch ihn:

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

Starten emit- strtt_start mit tcp: true – dann verbinden Sie sich durch den gemeinsamen ST-LINK-Server statt direkt das USB-Gerät zu ok... Dies trainierend – so läuft es parallel zu einer geöffneten debug_connect-Sitzung . weil GdbServerProcess immer -t/--shared an ST-LINK_gdbserver übergibt. Ohne tcp: true konkurrieren strtt_ – und eine offene Session um denselben Stift.

Ablauf zur Hardware-Verifizierung

Mit angeschlossenem ST-LINK und Zielgerät:

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

Ausführung dann über den Inspector oder einen MCP-Client:

1. list_probes → die Seriennummer der Sonde wird angezeigt.

2. debug_connect { elfPath, device, interface: "swd", serial } → gibt eine sessionId zurückgen.

3. breakpoint_set { sessionId, location: "main" } → gibt eine Haltepunktnummer zurück.

4. debug_run { sessionId } → hält an mit 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 } → unauffällige/Null-Flags unmittelbar nach Reset.

8. debug_disconnect { sessionId } → bestätigen, dass keine verwaisten Prozesse bleiben: ps aux | grep -E 'ST-LINK_gdbserver|arm-none-eabi-gdb'.

9. flash_standalone { file, reset: "hard", run: true } ohne geöffene Session.

10. Negativtest: Session öffnen, dann flash_standalonemit gleicher Seriennummer → DEVICE_BUSY wird erwartet.

Hinweis: debug_connect hält die CPU des Ziels an. Zustellen Sie sich kein Board an, das aktive Aktoren/Ausgänge steuert und ungeplantes Anhalten unsicher machen würde, ohne vorher zu bestätigen, dass dies unbedenklich ist.