{
  "markdown": "# McuBuddy — AI-Powered MCU and Embedded Firmware Debugging MCP Server\n\n<!-- mcp-name: io.github.cunjun/mcubuddy -->\n\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n**Languages:** [English](README.md) | [中文](README_zh.md)\n\n**Extend AI from firmware analysis to real MCUs, closing the loop across diagnosis, code changes, build, flashing, and validation in verified environments.**\n\n`McuBuddy` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for\nMCU board-level debugging. It exposes debug probes, Keil MDK projects, ELF/DWARF symbols,\nCPU and memory state, SVD peripheral registers, UART/RTT logs, FreeRTOS state, Flash operations,\nand GDB servers as structured tools that AI assistants can call.\n\nIt is designed for firmware development, board bring-up, fault isolation, debugging automation,\nand AI-assisted validation.\n\nMcuBuddy starts with 19 stable tools in the `default` toolset. Add only the domains a workflow\nneeds with `MCUBUDDY_TOOLSETS=probe,diagnose` (available domains: `probe`, `diagnose`,\n`build_flash`, `rtos`, `logs`, and `experimental`). The `core` profile is the only profile;\nstartup toolset selection is explicit and immutable.\n\n> [!IMPORTANT]\n> Automation does not replace engineering responsibility. Humans remain responsible for goals and\n> acceptance criteria, wiring and power safety, high-risk operation approval, code review, and new\n> environment validation. Motors, relays, and other safety-related devices also require recovery\n> plans and independent protection.\n\n**Quick links:** [Quick Start](#-quick-start) · [Project Guide](PROJECT_GUIDE.md) ·\n[Tool Reference](docs/tool-reference.md) · [Support Matrix](docs/support-matrix.md)\n\n## ✨ Key Features\n\n- **Real-hardware debugging**: Discover and connect to ST-Link, J-Link, CMSIS-DAP, and other\n  probes; control target execution; and inspect registers, memory, breakpoints, and watchpoints.\n- **Keil project workflow**: Discover `.uvprojx` / `.uvproj` files, select a target, invoke Keil\n  MDK through `UV4.exe` for builds or downloads, and feed the generated AXF/ELF into debugging.\n- **Source-level fault diagnosis**: Use ELF/DWARF data to resolve addresses to functions, source\n  lines, local variables, and call stacks when investigating HardFaults, startup failures, stack\n  overflows, and memory corruption.\n- **Peripheral and RTOS inspection**: Decode peripheral registers through CMSIS-SVD and inspect\n  FreeRTOS tasks, task contexts, and stack usage.\n- **Logs and runtime observability**: Read UART, RTT, and selected J-Link SWO logs, and manage\n  pyOCD/J-Link GDB server lifecycles.\n- **Evidence-driven results**: Return structured target, state, and validation evidence so AI can\n  continue an investigation instead of guessing code changes from symptoms alone.\n- **Actionable hardware boundaries**: Distinguish MCU limitations, firmware-inapplicable tools,\n  configuration problems, tool failures, and insufficient evidence, including impact and the next\n  safe check so unsupported paths are not debugged as firmware defects.\n\n## 🏗️ How It Works\n\n```mermaid\nflowchart LR\n    AI[\"AI Client<br/>Codex / Claude Code\"] --> MCP[\"McuBuddy<br/>MCP Server\"]\n    MCP --> EB[\"Execution Boundary<br/>Serialized Session\"]\n    EB --> TOOLS[\"Debugging Tools<br/>Diagnostics / Symbols / SVD / RTOS / Logs\"]\n    TOOLS --> KEIL[\"Keil MDK / UV4.exe<br/>Build / Optional Download\"]\n    TOOLS --> PROBE[\"Probe Backends<br/>pyOCD / J-Link / probe-rs\"]\n    KEIL --> IMAGE[\"AXF / ELF / HEX / BIN\"]\n    IMAGE --> TOOLS\n    PROBE --> BOARD[\"Real MCU Board\"]\n```\n\nMCP is not a protocol for invoking Keil. The AI calls `McuBuddy` through MCP; `McuBuddy` then\nuses Keil MDK through `UV4.exe`, pyOCD, J-Link, or another internal backend as required.\n\n## 🚀 Quick Start\n\n### 1. Prerequisites\n\nBasic requirements:\n\n- Python 3.10 or later;\n- a powered MCU development board;\n- a correctly connected ST-Link, J-Link, or CMSIS-DAP probe;\n- the target chip name;\n- preferably, an ELF/AXF image containing debug information.\n\nKeil build and download features require Windows with Keil MDK installed. McuBuddy invokes\nµVision through `UV4.exe`, including in Keil MDK v5 installations.\n\n### 2. Installation\n\n```bash\npip install \"McuBuddy @ git+https://github.com/cunjun/McuBuddy.git\"\n```\n\nThis installs McuBuddy once for all local firmware projects. Do not clone or copy the McuBuddy\nrepository into each target project. McuBuddy is a local-only MCP backend: the client starts one\n`stdio` process per connection, and McuBuddy does not expose HTTP, SSE, WebSocket, or another MCP\nnetwork listener.\n\nThe target project, Keil installation, ELF/SVD files, probe, and serial port must be directly\nvisible to the machine running McuBuddy. To update, reinstall from the official repository at\n`https://github.com/cunjun/McuBuddy`; McuBuddy never checks for, downloads, or installs updates\nautomatically.\n\nInstall the optional dependency when using the J-Link Python backend:\n\n```bash\npip install \"McuBuddy[jlink]\"\n```\n\nFor development from source:\n\n```bash\ngit clone https://github.com/cunjun/McuBuddy.git\ncd McuBuddy\npip install -e \".[dev]\"\n```\n\n### 3. Configure an MCP Client\n\n```json\n{\n  \"mcpServers\": {\n    \"McuBuddy\": {\n      \"command\": \"McuBuddy\",\n      \"args\": []\n    }\n  }\n}\n```\n\nFor a Windows source checkout, explicitly configure the virtual-environment Python executable and\nworking directory. See [Installation and First Connection](PROJECT_GUIDE.md#3-installation-and-first-connection),\nthen restart the AI client.\n\n### 4. Run a First Read-Only Check\n\nAfter connecting the probe and powering the board, tell the AI:\n\n```text\nUse McuBuddy to inspect the current debugging environment, discover connected probes,\nand perform a first read-only check of the board without writing Flash.\nBefore starting, tell me what information is still missing.\n```\n\nThe recommended sequence is to check the environment and target first, then configure the probe\nand read the minimum target state:\n\n```text\ndoctor()\nlist_connected_probes()\nmatch_chip_name(\"py32f030x8\")\nconfigure_probe(target=\"py32f030x8\", backend=\"pyocd\")\nprobe_connect(target=\"py32f030x8\")\nread_stopped_context()\n```\n\n`probe_connect` and `read_stopped_context` are available in the default `core` profile. Reading a\nstable stopped context may halt the target, so it is still execution-changing. If the device must\nnot be halted, instruct the AI to perform only non-intrusive probe and environment checks.\n\n## 💬 Automated Debugging Example\n\n```text\nUse McuBuddy to debug <project path>. The MCU is <exact model>, and the probe is\n<ST-Link/J-Link/CMSIS-DAP>. First collect board-level evidence and locate the problem. After\nauthorization, modify the code, build and flash it, then validate the result on the real board.\n```\n\nFor the evidence-first decision order and common scenarios, see\n[Common Debugging Workflows](PROJECT_GUIDE.md#6-common-debugging-workflows).\n\n## 🧰 Backends and Hardware Validation\n\n| Path | Current Role | Main Capabilities |\n| --- | --- | --- |\n| pyOCD + ST-Link/CMSIS-DAP | Primary backend | Control, memory, Flash, source debugging, RTT, RTOS, and GDB server |\n| J-Link | Primary backend | Control, memory, Flash, source debugging, native RTT, DWT, and GDB server |\n| probe-rs sidecar | Extended preview | ARM/RISC-V/Xtensa discovery, configurable core control, registers, memory, hardware breakpoints, Flash, and RTT |\n| Keil MDK (Windows, via `UV4.exe`) | Build/download backend | Project discovery, target configuration, build, logs, and optional download; supports MDK v5 installations |\n\nPrimary validation coverage includes:\n\n- STM32L496VETx + ST-Link / pyOCD;\n- STM32F103C8 + J-Link;\n- built-in target preflight profiles for STM32F103ZE and PY32F030X8.\n\n“Implemented in code” does not mean “validated on every board.” Use the\n[Support Matrix](docs/support-matrix.md) and `list_validation_records()` as the source of truth.\n\n## 🛡️ Safety Model\n\n`McuBuddy` provides machine-readable safety classifications through `list_tool_safety()`.\n\n| Category | Examples | Default Requirement |\n| --- | --- | --- |\n| Read-only | Target matching, register/memory reads, symbol resolution, logs, diagnostics | No confirmation required |\n| Execution-changing | halt, resume, reset, continue, stepping | Does not write Flash, but changes execution state |\n| Runtime-state write | Memory/register writes, breakpoints, watchpoints, SVD field writes | Explicit confirmation |\n| Persistent destructive operation | Flash erase/program, Keil firmware download | Explicit confirmation |\n| Host process | Keil build, GDB server start/stop | Starts or stops a local process |\n\nSafety principles:\n\n1. For an unknown target, match the chip and probe first; do not guess addresses.\n2. Read evidence before halting, resetting, or writing.\n3. Before a Flash operation, confirm the target, scope, image, and recovery method.\n4. For motors, relays, power switches, and other actuators, prefer breakpoints and low-energy tests.\n5. Send actuator commands with `uart_send_with_cleanup`, then call `finish_debug_session` before\n   returning a final conclusion. Server shutdown repeats the same idempotent cleanup as a fallback.\n\n## 🔒 Sessions and Concurrency\n\n- Operations that share probe, Keil, ELF/SVD, log, and runtime configuration are serialized within\n  the same `Session`.\n- Different sessions can run concurrently when they control unrelated boards.\n- Stateless queries such as target matching and tool safety information can run alongside session\n  operations.\n- Cancellation cannot forcibly terminate a call that has entered a synchronous SDK. The server\n  waits for the worker thread to finish before releasing the session lock.\n\nThis prevents one request from switching backends, disconnecting the probe, or changing shared\nstate while another probe operation is still running.\n\n## 📦 mcubuddy Skill\n\nThe repository includes `skills/mcubuddy`, which guides Codex and Claude Code to use these tools in an\n“evidence first, judgment second” sequence instead of treating MCP tools as an unordered command list.\n\nThe Skill is an optional workflow enhancement, not a prerequisite for hardware debugging. A correctly\ninstalled and configured local McuBuddy MCP server remains fully usable without it.\n\nInstalled releases bundle the Skill. Register the persistent Codex integration without cloning the\nrepository:\n\n```powershell\nuv tool install McuBuddy\nMcuBuddy setup codex --confirm --json\n```\n\nInstall for Codex:\n\n```powershell\npython .\\skills\\mcubuddy\\scripts\\install_skill.py --target codex --overwrite\n```\n\nInstall for Claude Code:\n\n```powershell\npython .\\skills\\mcubuddy\\scripts\\install_skill.py --target cc --overwrite\n```\n\nRestart the client or open a new session after installation. For source-checkout recovery,\ninstallation registration, and usage boundaries, see\n[Boundaries Between McuBuddy, MCP, and the Skill](PROJECT_GUIDE.md#2-boundaries-between-mcubuddy-mcp-and-the-skill)\nfor details.\n\n## ⚠️ Current Limitations\n\n- Keil build and download currently require Windows with Keil MDK and invoke µVision through\n  `UV4.exe`, including in MDK v5 installations.\n- The probe-rs sidecar covers Flash and RTT but still requires target-specific real-board\n  validation and does not yet have an official binary release.\n- RTOS inspection depends on FreeRTOS symbols and an ELF/AXF that match the target firmware.\n- SVD files are not bundled automatically for every chip and usually come from a CMSIS-Pack or\n  the chip vendor.\n- SWO text capture depends on chip configuration, probe capabilities, pin multiplexing, and board wiring.\n- Device patches and connection strategies remain lightweight mechanisms rather than a complete\n  board plugin system.\n\n## 📚 Documentation\n\n- Complete project overview and workflows: [Project Guide](PROJECT_GUIDE.md)\n- Chinese project overview: [项目指南](PROJECT_GUIDE_zh.md)\n- Complete tool index: [Tool Reference](docs/tool-reference.md)\n- Chinese tool usage: [MCP 工具中文参考](docs/mcp-tools-reference-zh.md)\n- Backend and hardware validation: [Support Matrix](docs/support-matrix.md)\n- Project design: [Architecture](docs/architecture.md)\n- Release history: [Changelog](CHANGELOG.md)\n\n## 🧪 Local Development\n\n```bash\npip install -e \".[dev]\"\npytest\nruff check src tests\n```\n\nSee the [Project Guide](PROJECT_GUIDE.md) for repository layout and documentation ownership.\n\n## 🙏 Upstream and Acknowledgements\n\nMcuBuddy is based on [SolarWang233/mcudbg](https://github.com/SolarWang233/mcudbg)\nand continues its MIT-licensed work with additional architecture, safety boundaries, evidence\nworkflows, backend support, and documentation. The original copyright notice is preserved in\n[LICENSE](LICENSE), with provenance details in [NOTICE](NOTICE).\n\n## 📄 License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n---\n\nIf `McuBuddy` helps with your MCU debugging workflow, consider giving the project a Star.\nIf you have suggestions, open an Issue or email\n[zhou229449@gmail.com](mailto:zhou229449@gmail.com).\n",
  "bytes": 13225,
  "sha": "da6e650b6e2340b1c0eef7a10ed407d7b2cf271176009b3c75fd024394ba94a8",
  "repo_slug": "cunjun/mcubuddy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cunjun_mcubuddy_fb065f27/readme"
}