Skip to content

v2.5.0

Pre-release
Pre-release

Choose a tag to compare

View all tags
@MatthiasHertelArm MatthiasHertelArm released this 23 Sep 20:29
v2.5.0
0900776

Highlights

  • The code derived from microsoft/DebugMCP is rewritten (Open-CMSIS-Pack#53). The server, the debugging handler and executor, multi-window routing, the configuration managers, activation and the build config were each rewritten from a behaviour specification by an implementer who did not see the old file. No source file carries the Microsoft copyright line any more. The method and per-file evidence are in docs/provenance/. The license files are unchanged pending the review in Open-CMSIS-Pack#54.
  • Failures are failures (Open-CMSIS-Pack#11). Every failed tool call is isError, starts with an error code ([NO_SESSION], [TARGET_RUNNING], [PROBE_BUSY], …) and puts the next step on its own line. A tool error in another VS Code window is no longer reported as "Could not reach the VS Code window".
  • cmsis_action follows the task it started (Open-CMSIS-Pack#47, Open-CMSIS-Pack#46, Open-CMSIS-Pack#12). "CMSIS Load", "CMSIS Run" and builds are tracked as jobs, and a long build returns running until you ask for cmsis_action {action: "status"}. Probe-owning actions and flash refuse with PROBE_BUSY while a CMSIS Run task or a debug session holds the probe. flash uses the CMSIS Debugger's bundled pyOCD.
  • GDB commands reach GDB in CMSIS Debugger sessions (Open-CMSIS-Pack#56, Open-CMSIS-Pack#13).
    • evaluate_expression("-exec …") returns GDB's output, and reset now really resets (J-Link included).
    • Breakpoints go through VS Code's model and report whether they bound. Logpoints fill in {expr} and honour their condition.
    • Breakpoint changes on a running target pause, apply and resume. A "target is running" refusal returns TARGET_RUNNING instead of a toast.
  • Language guides. Python and C/C++ are rewritten, and C/C++ is now served as a resource. JavaScript, Java, Go and C# are removed. Review in Open-CMSIS-Pack#55.
  • Verification. 736 unit tests and both transport suites pass. Four recorded behaviour baselines replay identically apart from the intended changes: the MCP surface, 33 scripted gdbtarget sessions with their DAP traffic, 85 configuration scenarios and 153 executor cases. Not yet tried on hardware; this pre-release is for that.

[2.5.0] - 2026-09-23

Changed

  • The code that still derived from microsoft/DebugMCP is replaced by independently written code (Open-CMSIS-Pack#53). The files are the MCP server, the debugging handler and executor, the debug state, secret redaction, the logger, the multi-window control server, registry and router, both configuration managers, extension activation, the esbuild/ESLint/test-runner configs and the skill-trigger scripts. Each was rewritten from a behaviour specification by an implementer who did not see the previous version. docs/provenance/ records the method, the specifications and the per-file result: at most five lines of any rewritten file occur anywhere in DebugMCP's history, and those are declarations the exported names dictate. No source file carries the Microsoft copyright line any more.
  • Behaviour is unchanged, including the known bugs, which are fixed separately. Four recorded oracles replay identically:
    • the agent-visible surface: tools, schemas, instructions, resources and every reply without a session;
    • 28 scripted debug sessions, with their DAP requests and replies;
    • 85 configuration scenarios, with every agent config file written byte for byte;
    • 124 executor cases.
      The wire protocol between windows and the registry format are unchanged, so windows on 2.3.10 and on this version still route to each other.
  • New module layout. The tool registrations, resources and instructions move from src/debugMCPServer.ts to src/debugTools.ts. The executor splits into src/executor/ (contract, snapshot, GDB memory ladder, reset, session reports), and the handler into src/handler/ (fence, cmsis_action, flash, GDB and target texts, test hooks).
  • Texts that still matched DebugMCP are reworded, with the same meaning.
    • The first two sentences of the server instructions.
    • The descriptions of stop_debugging, step_over, step_into, step_out, continue_execution, restart_debugging, remove_breakpoint, clear_all_breakpoints, list_breakpoints, list_variable_names, get_variables_values and evaluate_expression, the skill sentence of start_debugging, and six field descriptions (tools/list: 28 890 bytes).
    • Replies of the stop, restart, step, continue and breakpoint tools and the root-cause checkpoint on stop. evaluate_expression now reports the type on its own line: Evaluated: …, Result: …, Type: ….
    • The redaction notice, the setup and migration notifications, the launch-configuration picker and the resource names.
  • Documentation and configuration written anew.
    • The architecture docs of the rewritten components, plus a new docs/architecture/windowRouting.md.
    • AGENTS.md, with stale facts corrected: 4-space indentation, Streamable HTTP only (/sse answers 410), pdftotext optional since pdf.js is bundled.
    • The root-cause part and the opening step list of the agent guide (get_debug_instructions).
    • tsconfig.json, with the same effective configuration.
    • A 39-line .gitignore in place of the inherited Visual Studio template, whose [Bb]uild[Ll]og.* pattern once swallowed buildLog.ts. What git tracks and ignores is unchanged, except that a root .vscode/ folder is now ignored as a whole.
  • The Python and C/C++ troubleshooting guides are written anew, and the C/C++ guide is now served. It is available as cmsis-developer-assistant://docs/troubleshooting/cpp; before, it shipped but was never registered. It covers host programs and C/C++ firmware, and leaves target topics to the embedded guides. The resource descriptions now name the language, for example "Advice for debugging C/C++ programs".

Fixed

  • Failed tool calls are reported as failures (Open-CMSIS-Pack#11).

    • Previously, 28 tools could never set MCP isError: the debugging tools behind the handler fence, plus the documentation and build-artefact tools. Refusals such as "no active solution" or "Refusing to flash" came back as success text.
    • A failed call is now isError, and its text starts with an error code and puts the next step on its own line, for example [NO_SESSION] Cannot read memory: …⏎No active debug session. ….
    • structuredContent carries status, error_code, message, hint and, for several matching windows, the candidate list. A wait that ran out, or a build still running, is not a failure: it carries status timeout or running.
    • The codes are NO_SESSION, TARGET_RUNNING, TIMEOUT, AMBIGUOUS_WINDOW, WINDOW_UNREACHABLE, WORKER_TIMEOUT, CMSIS_NO_SOLUTION, TASK_FAILED, PROBE_BUSY, PROBE_WEDGED, PORT_HELD, TOOL_DISABLED, INVALID_ARGUMENT and INTERNAL.
    • The server instructions, the skill and the agent guide explain how to read them. tools/list is unchanged.

  • A tool error in another VS Code window is no longer reported as "Could not reach the VS Code window … It may have been closed".

    • The router now tells a failed call from a lost connection, and keeps its target window after a handler error or a worker timeout.
    • The control channel between windows carries typed results. It uses envelope version 2, negotiated by a request header, and windows on 2.3.10 still interoperate.

  • cmsis_action follows the CMSIS task it started, and refuses when the probe is busy (Open-CMSIS-Pack#47, Open-CMSIS-Pack#46, Open-CMSIS-Pack#12).

    • Build and flash tasks are tracked as jobs, bound to the task execution they started. Load+Run counts as done when Load exited 0 and CMSIS Run has stayed up for 2 s.
    • A task still running when the wait ends returns status running. cmsis_action {action: "status"} reports the jobs and live CMSIS tasks of the window, and a repeated build attaches to the one in flight instead of starting a second.
    • timeoutMs for cmsis_action and flash goes up to 600 s. The default wait stays 60 s, because some clients cut longer calls.
    • load, erase, load_and_run, load_and_debug and flash refuse with PROBE_BUSY while a debug session or a CMSIS Run task holds the probe. attach to a running Run task stays allowed. stop_run waits until the CMSIS tasks have ended and terminates leftovers itself.
    • Previously, task names such as "CMSIS Load" did not match the case-sensitive filter, and the end of any task counted as the end of the action.
    • A missing task label fails at once with INVALID_ARGUMENT. get_session_status names the CMSIS jobs and tasks. A load_and_debug whose session has no threads yet is running, not "did not survive".

  • flash uses the CMSIS Debugger's bundled pyOCD, then the one in .cmsis/tools-environment.yml, then PATH. It no longer advises pip install pyocd (part of Open-CMSIS-Pack#45).

  • GDB commands reach GDB in CMSIS Debugger sessions (Open-CMSIS-Pack#56).

    • We sent them as -exec …. That is the Microsoft C/C++ adapter's prefix; the CMSIS Debugger's adapter (cdt-gdb-adapter) takes > and evaluated -exec … as a C expression.
    • As a result, monitor reset, the GDB memory-read fallbacks and agents' own evaluate_expression("-exec …") did nothing, and reset on J-Link often reported "did NOT appear to have reset".
    • Commands now use each adapter's own prefix. On gdbtarget the console output is collected and returned. evaluate_expression accepts -exec <command> and >command, and neither is secret-redacted. The memory fallbacks use expressions and MI -data-read-memory-bytes, and reset flushes GDB's register cache before it verifies.

  • Breakpoints go through VS Code's model only, and logpoints on gdbtarget are GDB dprintfs.

    • Previously, add_breakpoint also sent GDB break and clear_all_breakpoints sent GDB delete. Once commands reach GDB, that would duplicate every breakpoint and delete the adapter's own.
    • Binding is now reported from the adapter's verified state and message, and list_breakpoints shows it.
    • On gdbtarget, logpoints are GDB dprintfs (MI -dprintf-insert), so {expr:%08lx} is filled in and a condition really applies. They are tracked by number, removed and cleared by number (never a bare delete), and listed with their hit counts. Other adapters keep VS Code logpoints.

  • Breakpoint changes and restarts are safe while a CMSIS target runs (Open-CMSIS-Pack#13).

    • add_breakpoint, add_logpoint, remove_breakpoint and clear_all_breakpoints pause a running gdbtarget target, apply the change, check it and resume, and say how long the target was paused.
    • restart_debugging pauses, then stops the session and starts its launch configuration again through the debug API, instead of the UI's restart command.
    • On gdbtarget, a step, continue or pause refused with GDB's "target is running" returns TARGET_RUNNING instead of retrying through VS Code's UI, where the refusal appeared as a toast.

  • The agent guides no longer claim that a breakpoint condition keeps the core from halting (the FPB has no condition logic; GDB evaluates the condition and resumes), and no longer advise -exec break / -exec condition.

Added

  • Provenance tooling for Open-CMSIS-Pack#53:
    • src/test/provenance.test.ts keeps any file from gaining the Microsoft copyright line.
    • npm run provenance:check measures each file against every commit of DebugMCP up to the last synced one; --gate fails on rewritten or new files above the limit.
    • npm run test:surface, test/transport/dap-scenarios.js, test/transport/config-scenarios.js and test/transport/executor-cases.js record and replay behaviour for refactorings.

Removed

  • dist/extension.js.map and dist/pdfWorker.js are no longer tracked. dist/ has been ignored since 2026-09-03, both files are build output, and the source map embedded the pre-rewrite sources.
  • vsc-extension-quickstart.md, the extension generator's template.
  • The JavaScript, Java, Go and C# troubleshooting guides, and the troubleshooting/javascript, java and csharp resources (go.md was never served). Those languages can still be debugged through the same tools.

Pre-release (odd minor). Full changelog: https://github.com/MatthiasHertelArm/CMSIS-Developer-Assistant/blob/v2.5.0/CHANGELOG.md. Previous pre-release: https://github.com/MatthiasHertelArm/CMSIS-Developer-Assistant/releases/tag/v2.3.10. Built from branch pr/2.5.0-core-rewrite, based on Open-CMSIS-Pack main (2.3.10 plus Open-CMSIS-Pack#43); not yet proposed upstream. Open reviews: Open-CMSIS-Pack#54 (license), Open-CMSIS-Pack#55 (Python and C/C++ guides).

Assets 7
Loading