stm32-stlink-mcp

STM32 마이크로컨트롤러를 ST-LINK를 통해 디버깅하기 위한 MCP 서버이며, 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/memory_write + evaluate_expression은 이미 주소를 통해 모든 것에 접근 가능), 실시간/스트리밍 메모리 폴링, 플러그인 시스템, 칩별 메모리 영역 허용 목록, gdb monitor 임의 패스스루, 그리고 옵션 바이트/RDP 도구(Board-Blocking 기능으로 의도적으로 제외)를 포함합니다.

RTT

RTT(SEGGER Real Time Transfer — 실시간으로 언홀팅 콘솔/버블 변수 추적)는 의도적으로 이 서버에 구현하지 않았습니다. ST-LINK_gdbserver의 GDB/MI 콘솔에는 non-stop 모드가 없어서, 이 서버의 debug_connect 세션을 통해 메모리를 읽으려면 먼저 코어를 멈춰야 합니다. 이는 RTT의 목적을 무력화합니다. 올바른 메커니즘은 코어를 절대로 멈추지 않는 직접 AP 메모리 액세스입니다(STM32CubeMonitor 소스가 정확히 이렇게 동작하는 것을 확인했고, STM32_Programmer_CLI의 -r32fast 도 마찬가지입니다).

바로 이 일을 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>" }
    }
  }
}

tcp: true를 설정하여 strtt_start를 시작하면 USB 장치를 직접 점유하는 대신 공용 ST-LINK Server를 통해 연결됩니다. 이렇게 하면 이 서버의 열린 debug_connect 세션과 동시에 실행할 수 있습니다. GdbServerProcess는 항상 ST-LINK_gdbserver에 -t/--shared를 전달하기 때문입니다. tcp: true가 아닌 경우 strtt와 열린 디버그 세션이 동일한 프로브를 두고 경쟁하게 됩니다.

하드웨어 검증 런북

ST-LINK 및 타깃이 연결된 상태에서:

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

그런 다음 Inspector 도구나 MCP 클라이언트로:

1. list_probes → 프로브의 시리얼이 보입니다.

2. debug_connect { file, device, 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를 일시정지 시킵니다. 예상치 않게 CPU가 멈추는 것이 안전하지 않은 방식으로 액추에이터·출력을 활발히 구동 중인 보드에 연결해서는 안 됩니다. 먼저 그러한 사용이 가능한지 확인하기 전에는 그렇게 하지 마세요.