Embedded AI Debug Assistant

Embedded AI Debug Assistant is a cross-platform VS Code extension for embedded development. It provides a serial monitor, temporary per-session serial logs, debug-session context, and a local MCP server for external AI clients.

Features

• Serial monitor with UTF-8, hexadecimal, and base64 I/O.
• Serial session logs are temporary files under the operating system temp directory and are deleted during extension cleanup.
• Debug context and joint serial/debug recording for paused sessions.
• Local loopback MCP tools for serial and debug workflows, including explicit debug control and debug_stop.
• Joint Debug/Serial binding from launch.json, with optional ownership-safe serial cleanup through embeddedDebug.serial.autoClose.
• Diagnostics available from Embedded Debug: Open Diagnostics Log. This is the only persistent extension log: it is stored at .embedded-debug/logs/extension-diagnostics.log, or in VS Code global storage when no workspace is open.
• The bundled embedded-ai-debug Agent Skill is contributed natively to VS Code. Activation does not copy files into user or third-party assistant directories.
• The Workspace MCP Broker is contributed through VS Code's native MCP server definition provider. Activation does not edit user or profile mcp.json files.

Debug/Serial configuration

Add serial settings inside the selected Debug configuration when the Debug session should reuse or auto-open a matching serial port:

{
  "embeddedDebug": {
    "serial": {
      "path": "COM5",
      "baudRate": 115200,
      "dataBits": 8,
      "stopBits": 1,
      "parity": "none",
      "flowControl": "none",
      "lineEnding": "crlf",
      "dtr": true,
      "rts": true,
      "autoBind": true,
      "autoOpen": true,
      "autoClose": true
    }
  }
}

autoClose defaults to false. When enabled, only a session auto-opened and owned by that Debug instance is closed at Debug termination; pre-existing UI or MCP sessions are preserved. MCP session responses include a manager instance identity and endpoint so a client connected to another VS Code instance is explicitly detectable.

Workspace-aware MCP endpoints

Each VS Code instance keeps its direct MCP server on http://127.0.0.1:53708/mcp by default. The embeddedDebug.mcp.port setting remains configurable and accepts ports 0 to 65535. If a nonzero configured port is already in use, startup retries exactly once on a dynamic port so additional VS Code windows can still register with the broker. Set it explicitly to 0 to use a dynamic port directly; after startup, always use the actual endpoint reported by the extension.

The extension also starts or reuses a detached local workspace broker at http://127.0.0.1:53709/mcp (embeddedDebug.mcp.brokerPort, also 0..65535). Configure standalone Copilot CLI and other external agents to the broker, not to a specific direct endpoint. Call workspace_list_instances first, then pass workspaceFolder or workspaceInstanceId to every serial/debug proxy call. The direct endpoint remains per VS Code instance and cannot discover other windows.

VS Code discovers the shared embedded-ai-debug Broker endpoint through the extension's MCP server definition provider. Direct endpoints remain internal Broker backends and are not published as standalone Agent MCP entries. See workspace-mcp-broker-design.md for routing, lifecycle, security, and machine-readable errors.

debug_stop requires an explicit debugInstanceId or sessionId for the active VS Code debug session. It accepts waitFor: "terminated" or "none" and a bounded timeoutMs, and reports selectors, previous/observed state, dispatch acceptance, wait completion, and timeout status.

Standalone Copilot CLI setup

The extension automatically starts a local Workspace MCP Broker. VS Code uses the native provider; external agents that do not consume VS Code contributions must be configured explicitly with the shared Broker endpoint:

{
  "mcpServers": {
    "embedded-ai-debug": {
      "type": "http",
      "url": "http://127.0.0.1:53709/mcp"
    }
  }
}

For multiple VS Code windows, call workspace_list_instances first, then pass the selected workspaceFolder or workspaceInstanceId to every serial/debug proxy call. Direct per-window MCP endpoints are internal Broker backends and are not required in the external agent configuration.

Runtime verification workflow

workspace_list_instances
→ debug_list_configurations
→ serial_list_sessions
→ debug_start
→ debug_list_sessions
→ debug_capture_context_with_serial
→ debug_control / debug_set_breakpoint / debug_evaluate
→ debug_stop

For embedded targets, run only one J-Link/Debug instance per target board. Restart by stopping the existing instance and confirming terminated before starting it again.

Development

npm ci
npm test
npm run package

Installers of the packaged VSIX do not need Node.js or npm, and extension activation never downloads npm packages. Source developers need a Node.js/npm version compatible with package-lock.json; use npm ci for reproducible dependencies. npm test compiles the extension. npm run package creates a VS Code extension package (.vsix) that includes runtime dependencies, native SerialPort bindings, and the Agent Skill.