vscode-cube-mcp 0.1.0__tar.gz

vscode_cube_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vscode_cube_mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vscode_cube_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: vscode-cube-mcp
+Version: 0.1.0
+Summary: MCP server 封装 STM32CubeMX 命令行,通过 MCP 工具配置引脚/外设并生成 HAL 工程
+Author-email: F1ZyCaO_3286 <3286266250@qq.com>
+License: MIT
+Keywords: mcp,stm32,stm32cubemx,embedded,hal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.0.0
+Dynamic: license-file
+
+# Vscode_cube_mcp
+
+> 全部由 deepseek-v4-flash 生成
+
+MCP(Model Context Protocol) server,封装 **STM32CubeMX** 官方命令行脚本模式(`-q`),
+让 AI 助手可以直接加载 .ioc 工程、改引脚/外设配置、生成 HAL 代码、导出引脚表。
+
+每次调用:命令序列写入临时脚本 → 启动 `STM32CubeMX -q` → 超时强杀
+→ 过滤 log4j 噪音 → 检测 KO 失败标记 → 返回干净输出。
+
+## 功能
+
+| 工具 | 说明 |
+|------|------|
+| `cubemx_script` | 任意 CubeMX 脚本命令序列(逃生通道) |
+| `cubemx_load` | 加载 .ioc 并回读关键配置(只读) |
+| `cubemx_configure` | 加载 .ioc,执行 `set` 命令序列,`saveas` 写回 |
+| `cubemx_generate` | 加载 .ioc 并 `project generate` 生成 HAL 工程 |
+| `cubemx_export_pinout` | 导出引脚配置 CSV(只读) |
+
+## 要求
+
+- Python **>= 3.10**,安装依赖 `mcp>=2.0`
+- **STM32CubeMX**(ST 专有软件,请从 ST 官网免费下载并自行遵守其许可)—— 本工具仅运行时调用其命令行,不包含、不修改其任何代码
+
+## 安装
+
+```bash
+pip install vscode-cube-mcp        # 从 PyPI(发布后)
+# 或本地开发安装
+pip install -e .
+```
+
+## 配置(环境变量)
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `ST_CUBEMX_EXE` | PATH 中的 `STM32CubeMX` / 常见 Windows 安装位置 | STM32CubeMX 可执行文件完整路径 |
+| `ST_CUBEMX_ALLOWED_ROOTS` | 当前工作目录 | .ioc 允许访问的根目录,`os.pathsep` 分隔(`;` for Windows) |
+| `ST_CUBEMX_TIMEOUT` | `240` | CubeMX 子进程超时秒数 |
+
+示例(Windows PowerShell):
+
+```powershell
+$env:ST_CUBEMX_EXE = "C:\MINE\STM\STM\STM32CubeMX.exe"
+$env:ST_CUBEMX_ALLOWED_ROOTS = "C:\MINE\STM32Project\STM32VScode"
+```
+
+> 安全设计:所有 .ioc / 生成路径都必须在 `ST_CUBEMX_ALLOWED_ROOTS` 白名单内,
+> 白名单外的路径会被拒绝(路径校验见 `_check_path`)。
+
+## 使用(接入 MCP 客户端)
+
+把 server 注册到支持 MCP 的客户端(如 Reasonix / Claude Desktop 等),
+stdio 方式启动:
+
+```json
+{
+  "mcpServers": {
+    "Vscode_cube_mcp": {
+      "command": "python",
+      "args": ["-m", "cubemx_mcp"]
+    }
+  }
+}
+```
+
+或直接用 console 入口:
+
+```bash
+vscode-cube-mcp
+```
+
+## 开发
+
+```bash
+python -m unittest test_cubemx_mcp -v   # 运行单元测试(不依赖 CubeMX)
+```
+
+测试覆盖:`_cleanup` 噪音过滤、`_check_path` 白名单校验、`_find_cubemx` /
+`_allowed_roots` 配置解析、`_run_script`(mock 子进程)的 KO 检测与超时路径。
+
+## 许可与依赖声明
+
+- **本工具代码**:MIT License(见 `LICENSE`)
+- **mcp SDK**(唯一 Python 依赖):MIT License(modelcontextprotocol/python-sdk)
+- **STM32CubeMX**:ST 专有软件,运行时外部调用,需用户自备并遵守其许可条款
+
+## 实践经验(2026-08-05,OLED_MCP 项目踩坑记录)
+
+用 `cubemx_generate` 生成的新工程,在 VSCode 里用 **STM32 VS Code Extension** 打开时可能遇到:
+Run and Debug 迟迟不出现 / ST 扩展识别工程很慢 / 报 `OLED_MCPsettings\ide.store.json` 之类 ENOENT。
+
+**根因**:CubeMX CLI 生成的新工程缺少 ST 扩展识别工程所需的文件:
+
+| 文件 | 作用 |
+|------|------|
+| `.settings/ide.store.json` | 声明 `sourceType=STM32CubeMX`、`device`、`core`(扩展识别硬件的关键) |
+| `.settings/bundles.store.json`、`bundles-lock.store.json` | bundles(工具链)版本锁定 |
+| `.vscode/settings.json` | cube-cmake / clangd 配置 |
+| `.vscode/c_cpp_properties.json` | compile_commands.json 索引 |
+| `.clangd` | clangd 配置 |
+
+**正确做法(对齐实例工程,如 OLED_HAL)**:
+1. 生成新工程后,**不要手写 launch.json**(实例工程没有,ST 扩展会自动提供调试配置);
+2. 在 VSCode 里**重新加载窗口**(Reload Window),扩展会识别工程并自动补齐上述文件(device 名取自 `.ioc`,如 `STM32F103C8T6`);
+3. 若扩展没自动补齐,可从同芯片的实例工程复制 `.settings/`、`.vscode/`、`.clangd`(注意核对 `ide.store.json` 里的 `device` 是否一致)。
+
+**其他教训**:
+- 若确实要手写 launch.json,ST 扩展的调试器类型是 `stlinkgdbtarget`,`deviceName` 必须与 `.settings/ide.store.json` 的 `device` 一致(如 `STM32F103C8T6`,不是 `STM32F103C8Tx`),否则扩展可能解析异常;
+- 本机 STM32 VS Code Extension 全家桶调试类型:`stlinkgdbtarget`(ST-Link)/ `jlinkgdbtarget`(J-Link)/ `stgdbtarget`(通用 GDB);
+- `cubemx_generate` 的 `project path` 对已存在目录返回 KO 是正常现象,generate 默认在 .ioc 同目录生成,结果不受影响。
+
+## 能力边界:不是真正意义上的"从零开始"
+
+所有工具都要求先有一个 `.ioc` 文件(`cubemx_load` / `cubemx_configure` / `cubemx_generate` 起手都是 `config load`,且 `_ioc_path()` 校验文件必须存在):
+
+- CubeMX 的 `-q` 脚本模式**没有 `new project` 命令**,"新建工程 → 选芯片"是 GUI 独有的流程;
+- 因此"生成新工程"的实际做法是:**复制一个 6.18 原生生成的 .ioc(TEST / OLED_HAL 这类)改造**(改 `ProjectManager.ProjectName` / `ProjectFileName`,再用 `set` 命令加外设/引脚)后 `cubemx_generate`;
+- 手写全新 .ioc 理论可行,但 6.18-RC3 对手写/非原生 .ioc 加载会 NPE,不推荐。

vscode_cube_mcp-0.1.0/README.md

@@ -0,0 +1,120 @@
+# Vscode_cube_mcp
+
+> 全部由 deepseek-v4-flash 生成
+
+MCP(Model Context Protocol) server,封装 **STM32CubeMX** 官方命令行脚本模式(`-q`),
+让 AI 助手可以直接加载 .ioc 工程、改引脚/外设配置、生成 HAL 代码、导出引脚表。
+
+每次调用:命令序列写入临时脚本 → 启动 `STM32CubeMX -q` → 超时强杀
+→ 过滤 log4j 噪音 → 检测 KO 失败标记 → 返回干净输出。
+
+## 功能
+
+| 工具 | 说明 |
+|------|------|
+| `cubemx_script` | 任意 CubeMX 脚本命令序列(逃生通道) |
+| `cubemx_load` | 加载 .ioc 并回读关键配置(只读) |
+| `cubemx_configure` | 加载 .ioc,执行 `set` 命令序列,`saveas` 写回 |
+| `cubemx_generate` | 加载 .ioc 并 `project generate` 生成 HAL 工程 |
+| `cubemx_export_pinout` | 导出引脚配置 CSV(只读) |
+
+## 要求
+
+- Python **>= 3.10**,安装依赖 `mcp>=2.0`
+- **STM32CubeMX**(ST 专有软件,请从 ST 官网免费下载并自行遵守其许可)—— 本工具仅运行时调用其命令行,不包含、不修改其任何代码
+
+## 安装
+
+```bash
+pip install vscode-cube-mcp        # 从 PyPI(发布后)
+# 或本地开发安装
+pip install -e .
+```
+
+## 配置(环境变量)
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `ST_CUBEMX_EXE` | PATH 中的 `STM32CubeMX` / 常见 Windows 安装位置 | STM32CubeMX 可执行文件完整路径 |
+| `ST_CUBEMX_ALLOWED_ROOTS` | 当前工作目录 | .ioc 允许访问的根目录,`os.pathsep` 分隔(`;` for Windows) |
+| `ST_CUBEMX_TIMEOUT` | `240` | CubeMX 子进程超时秒数 |
+
+示例(Windows PowerShell):
+
+```powershell
+$env:ST_CUBEMX_EXE = "C:\MINE\STM\STM\STM32CubeMX.exe"
+$env:ST_CUBEMX_ALLOWED_ROOTS = "C:\MINE\STM32Project\STM32VScode"
+```
+
+> 安全设计:所有 .ioc / 生成路径都必须在 `ST_CUBEMX_ALLOWED_ROOTS` 白名单内,
+> 白名单外的路径会被拒绝(路径校验见 `_check_path`)。
+
+## 使用(接入 MCP 客户端)
+
+把 server 注册到支持 MCP 的客户端(如 Reasonix / Claude Desktop 等),
+stdio 方式启动:
+
+```json
+{
+  "mcpServers": {
+    "Vscode_cube_mcp": {
+      "command": "python",
+      "args": ["-m", "cubemx_mcp"]
+    }
+  }
+}
+```
+
+或直接用 console 入口:
+
+```bash
+vscode-cube-mcp
+```
+
+## 开发
+
+```bash
+python -m unittest test_cubemx_mcp -v   # 运行单元测试(不依赖 CubeMX)
+```
+
+测试覆盖:`_cleanup` 噪音过滤、`_check_path` 白名单校验、`_find_cubemx` /
+`_allowed_roots` 配置解析、`_run_script`(mock 子进程)的 KO 检测与超时路径。
+
+## 许可与依赖声明
+
+- **本工具代码**:MIT License(见 `LICENSE`)
+- **mcp SDK**(唯一 Python 依赖):MIT License(modelcontextprotocol/python-sdk)
+- **STM32CubeMX**:ST 专有软件,运行时外部调用,需用户自备并遵守其许可条款
+
+## 实践经验(2026-08-05,OLED_MCP 项目踩坑记录)
+
+用 `cubemx_generate` 生成的新工程,在 VSCode 里用 **STM32 VS Code Extension** 打开时可能遇到:
+Run and Debug 迟迟不出现 / ST 扩展识别工程很慢 / 报 `OLED_MCPsettings\ide.store.json` 之类 ENOENT。
+
+**根因**:CubeMX CLI 生成的新工程缺少 ST 扩展识别工程所需的文件:
+
+| 文件 | 作用 |
+|------|------|
+| `.settings/ide.store.json` | 声明 `sourceType=STM32CubeMX`、`device`、`core`(扩展识别硬件的关键) |
+| `.settings/bundles.store.json`、`bundles-lock.store.json` | bundles(工具链)版本锁定 |
+| `.vscode/settings.json` | cube-cmake / clangd 配置 |
+| `.vscode/c_cpp_properties.json` | compile_commands.json 索引 |
+| `.clangd` | clangd 配置 |
+
+**正确做法(对齐实例工程,如 OLED_HAL)**:
+1. 生成新工程后,**不要手写 launch.json**(实例工程没有,ST 扩展会自动提供调试配置);
+2. 在 VSCode 里**重新加载窗口**(Reload Window),扩展会识别工程并自动补齐上述文件(device 名取自 `.ioc`,如 `STM32F103C8T6`);
+3. 若扩展没自动补齐,可从同芯片的实例工程复制 `.settings/`、`.vscode/`、`.clangd`(注意核对 `ide.store.json` 里的 `device` 是否一致)。
+
+**其他教训**:
+- 若确实要手写 launch.json,ST 扩展的调试器类型是 `stlinkgdbtarget`,`deviceName` 必须与 `.settings/ide.store.json` 的 `device` 一致(如 `STM32F103C8T6`,不是 `STM32F103C8Tx`),否则扩展可能解析异常;
+- 本机 STM32 VS Code Extension 全家桶调试类型:`stlinkgdbtarget`(ST-Link)/ `jlinkgdbtarget`(J-Link)/ `stgdbtarget`(通用 GDB);
+- `cubemx_generate` 的 `project path` 对已存在目录返回 KO 是正常现象,generate 默认在 .ioc 同目录生成,结果不受影响。
+
+## 能力边界:不是真正意义上的"从零开始"
+
+所有工具都要求先有一个 `.ioc` 文件(`cubemx_load` / `cubemx_configure` / `cubemx_generate` 起手都是 `config load`,且 `_ioc_path()` 校验文件必须存在):
+
+- CubeMX 的 `-q` 脚本模式**没有 `new project` 命令**,"新建工程 → 选芯片"是 GUI 独有的流程;
+- 因此"生成新工程"的实际做法是:**复制一个 6.18 原生生成的 .ioc(TEST / OLED_HAL 这类)改造**(改 `ProjectManager.ProjectName` / `ProjectFileName`,再用 `set` 命令加外设/引脚)后 `cubemx_generate`;
+- 手写全新 .ioc 理论可行,但 6.18-RC3 对手写/非原生 .ioc 加载会 NPE,不推荐。

vscode_cube_mcp-0.1.0/cubemx_mcp.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Vscode_cube_mcp: MCP server 封装 STM32CubeMX 官方 -q 脚本控制台(无状态子进程)。
+
+每次调用:命令序列写入临时脚本 -> 启动 STM32CubeMX -q -> 超时强杀
+-> 过滤 log4j 噪音 -> 检测 KO 失败标记 -> 返回干净输出。
+
+Tools:
+  cubemx_script(script)            任意脚本(逃生通道)
+  cubemx_load(ioc)                 config load + 回读配置(只读)
+  cubemx_configure(ioc, cmds)      load + set 命令序列 + saveas(写回 .ioc)
+  cubemx_generate(ioc, project_dir) load + project generate
+  cubemx_export_pinout(ioc)        csv pinout 导出(只读)
+
+配置(环境变量,不硬编码本机路径):
+  ST_CUBEMX_EXE            STM32CubeMX 可执行文件路径;未设置时尝试 PATH 中的
+                           STM32CubeMX 及常见 Windows 安装位置,最后退回命令名。
+  ST_CUBEMX_ALLOWED_ROOTS  .ioc 允许访问的根目录(os.pathsep 分隔);
+                           未设置时默认仅允许当前工作目录。
+  ST_CUBEMX_TIMEOUT        CubeMX 子进程超时秒数,默认 240。
+
+能力边界:本 MCP 不是真正意义上的"从零开始" —— 所有工具都要求先有
+一个 .ioc(CubeMX -q 脚本模式没有 new project 命令),详见 README.md。
+"""
+
+import asyncio
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import threading
+
+from mcp.server import MCPServer
+
+
+# ------------------------------------------------------------------ config
+def _find_cubemx() -> str:
+    """解析 STM32CubeMX 可执行文件路径(环境变量 > PATH > 常见安装位置)。"""
+    exe = os.environ.get("ST_CUBEMX_EXE", "").strip()
+    if exe:
+        return exe
+    candidates = ["STM32CubeMX"]
+    if os.name == "nt":
+        for env_key in ("ProgramFiles", "ProgramFiles(x86)"):
+            base = os.environ.get(env_key)
+            if base:
+                candidates.append(
+                    os.path.join(base, "STMicroelectronics", "STM32Cube", "STM32CubeMX", "STM32CubeMX.exe")
+                )
+    for c in candidates:
+        if os.path.isfile(c) or shutil.which(c):
+            return c
+    return candidates[0]
+
+
+def _allowed_roots() -> list:
+    """解析允许访问的根目录列表(环境变量 os.pathsep 分隔,默认当前目录)。"""
+    raw = os.environ.get("ST_CUBEMX_ALLOWED_ROOTS", "")
+    roots = [r.strip() for r in raw.split(os.pathsep) if r.strip()]
+    return roots or [os.getcwd()]
+
+
+CUBEMX_EXE = _find_cubemx()
+ALLOWED_ROOTS = _allowed_roots()
+TIMEOUT_SECONDS = int(os.environ.get("ST_CUBEMX_TIMEOUT", "240"))
+
+NOISE_RE = re.compile(
+    r"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3} \[(INFO|WARN|DEBUG|TRACE)\]|"
+    r"^(Picked up|log4j[: ]|[A-Z][a-z]{2} \d{2}, \d{4} \d{1,2}:\d{2}:\d{2} (AM|PM)|"
+    r"WARNING: Could not open|Configure log4j|Cannot load)",
+    re.MULTILINE,
+)
+
+# CubeMX 有单实例锁,串行化防止并发互踩
+_LOCK = threading.Lock()
+
+mcp = MCPServer("Vscode_cube_mcp")
+
+
+# ---------------------------------------------------------------- helpers
+def _check_path(p: str) -> str:
+    """校验路径在允许根目录下,返回绝对路径。"""
+    ap = os.path.abspath(p)
+    for root in ALLOWED_ROOTS:
+        if ap.lower().startswith(os.path.abspath(root).lower()):
+            return ap
+    raise ValueError(f"路径不在白名单内(仅允许 {ALLOWED_ROOTS}): {p}")
+
+
+def _cleanup(raw: str) -> str:
+    lines = []
+    for ln in raw.splitlines():
+        if NOISE_RE.match(ln):
+            continue
+        s = ln.strip()
+        if s:
+            lines.append(s)
+    return "\n".join(lines)
+
+
+def _run_script(script: str) -> dict:
+    """执行 CubeMX 脚本,返回 {ok, output, exit_code}。"""
+    fd, tmp = tempfile.mkstemp(prefix="cubemx_mcp_", suffix=".txt")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(script.strip() + "\n")
+            f.write("exit\n")
+        with _LOCK:
+            proc = subprocess.run(
+                [CUBEMX_EXE, "-q", tmp],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=TIMEOUT_SECONDS,
+                cwd=os.path.dirname(CUBEMX_EXE) if os.path.dirname(CUBEMX_EXE) else None,
+            )
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "output": f"TIMEOUT: CubeMX 子进程超过 {TIMEOUT_SECONDS}s 被终止", "exit_code": None}
+    finally:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+
+    raw = (proc.stdout or "") + "\n" + (proc.stderr or "")
+    output = _cleanup(raw)
+    ok = proc.returncode == 0 and not any(line.strip() == "KO" for line in output.splitlines())
+    return {"ok": ok, "output": output, "exit_code": proc.returncode}
+
+
+def _ioc_path(ioc: str) -> str:
+    ap = _check_path(ioc)
+    if not os.path.isfile(ap):
+        raise ValueError(f".ioc 文件不存在: {ap}")
+    if not ap.lower().endswith(".ioc"):
+        raise ValueError(f"不是 .ioc 文件: {ap}")
+    return ap
+
+
+# ------------------------------------------------------------------ tools
+@mcp.tool()
+def cubemx_script(script: str) -> str:
+    """执行任意 CubeMX 脚本命令序列(逃生通道,原样传给 -q)。
+
+    常用命令示例:
+      config load "C:/path/proj.ioc"
+      set mode USART1 Asynchronous
+      set pin PB13 GPIO_Output
+      set gpio parameters PB13 GPIO_Label=LED
+      config saveas "C:/path/proj.ioc"
+      project generate
+    """
+    r = _run_script(script)
+    return f"[{'OK' if r['ok'] else 'FAIL'} exit={r['exit_code']}]\n{r['output']}"
+
+
+@mcp.tool()
+def cubemx_load(ioc: str) -> str:
+    """加载 .ioc 工程并回读关键配置(只读,不修改任何文件)。
+
+    参数:
+      ioc: 工程 .ioc 文件绝对路径(须在允许目录内)
+    """
+    ap = _ioc_path(ioc)
+    r = _run_script(f'config load "{ap}"')
+    return f"[{'OK' if r['ok'] else 'FAIL'} exit={r['exit_code']}]\n{r['output']}"
+
+
+@mcp.tool()
+def cubemx_configure(ioc: str, commands: list) -> str:
+    """加载 .ioc,依次执行 set 命令,最后 saveas 写回原文件。
+
+    参数:
+      ioc: 工程 .ioc 文件绝对路径(会被写回,先备份再调用)
+      commands: 命令列表,如 ["set mode USART1 Asynchronous", "set pin PB13 GPIO_Output"]
+    """
+    ap = _ioc_path(ioc)
+    lines = [f'config load "{ap}"']
+    lines.extend(commands)
+    lines.append(f'config saveas "{ap}"')
+    r = _run_script("\n".join(lines))
+    return f"[{'OK' if r['ok'] else 'FAIL'} exit={r['exit_code']}]\n{r['output']}"
+
+
+@mcp.tool()
+def cubemx_generate(ioc: str, project_dir: str = "") -> str:
+    """加载 .ioc 并执行 project generate 生成 HAL 代码。
+
+    参数:
+      ioc: 工程 .ioc 文件绝对路径
+      project_dir: 生成目标目录;留空则在 .ioc 所在目录生成。
+                   强烈建议指向副本/测试目录,避免覆盖现有工程。
+    """
+    ap = _ioc_path(ioc)
+    lines = [f'config load "{ap}"']
+    if project_dir:
+        pd = _check_path(project_dir)
+        os.makedirs(pd, exist_ok=True)
+        lines.append(f'project path "{pd}"')
+    lines.append("project generate")
+    r = _run_script("\n".join(lines))
+    return f"[{'OK' if r['ok'] else 'FAIL'} exit={r['exit_code']}]\n{r['output']}"
+
+
+@mcp.tool()
+def cubemx_export_pinout(ioc: str) -> str:
+    """加载 .ioc 并导出当前引脚配置 CSV(只读,CSV 写系统临时目录后读回)。
+
+    参数:
+      ioc: 工程 .ioc 文件绝对路径
+    """
+    ap = _ioc_path(ioc)
+    fd, csv = tempfile.mkstemp(prefix="cubemx_pinout_", suffix=".csv")
+    os.close(fd)
+    try:
+        r = _run_script(f'config load "{ap}"\ncsv pinout "{csv}"')
+        if not r["ok"]:
+            return f"[FAIL exit={r['exit_code']}]\n{r['output']}"
+        with open(csv, encoding="utf-8", errors="replace") as f:
+            content = f.read()
+        return f"[OK]\n{r['output']}\n--- CSV ---\n{content}"
+    finally:
+        try:
+            os.remove(csv)
+        except OSError:
+            pass
+
+
+def main() -> None:
+    asyncio.run(mcp.run_stdio_async())
+
+
+if __name__ == "__main__":
+    main()

vscode_cube_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vscode-cube-mcp"
+version = "0.1.0"
+description = "MCP server 封装 STM32CubeMX 命令行,通过 MCP 工具配置引脚/外设并生成 HAL 工程"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "F1ZyCaO_3286", email = "3286266250@qq.com" }]
+keywords = ["mcp", "stm32", "stm32cubemx", "embedded", "hal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Embedded Systems",
+]
+dependencies = ["mcp>=2.0.0"]
+
+[project.scripts]
+vscode-cube-mcp = "cubemx_mcp:main"
+
+[tool.setuptools]
+py-modules = ["cubemx_mcp"]

vscode_cube_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vscode_cube_mcp-0.1.0/vscode_cube_mcp.egg-info/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: vscode-cube-mcp
+Version: 0.1.0
+Summary: MCP server 封装 STM32CubeMX 命令行,通过 MCP 工具配置引脚/外设并生成 HAL 工程
+Author-email: F1ZyCaO_3286 <3286266250@qq.com>
+License: MIT
+Keywords: mcp,stm32,stm32cubemx,embedded,hal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.0.0
+Dynamic: license-file
+
+# Vscode_cube_mcp
+
+> 全部由 deepseek-v4-flash 生成
+
+MCP(Model Context Protocol) server,封装 **STM32CubeMX** 官方命令行脚本模式(`-q`),
+让 AI 助手可以直接加载 .ioc 工程、改引脚/外设配置、生成 HAL 代码、导出引脚表。
+
+每次调用:命令序列写入临时脚本 → 启动 `STM32CubeMX -q` → 超时强杀
+→ 过滤 log4j 噪音 → 检测 KO 失败标记 → 返回干净输出。
+
+## 功能
+
+| 工具 | 说明 |
+|------|------|
+| `cubemx_script` | 任意 CubeMX 脚本命令序列(逃生通道) |
+| `cubemx_load` | 加载 .ioc 并回读关键配置(只读) |
+| `cubemx_configure` | 加载 .ioc,执行 `set` 命令序列,`saveas` 写回 |
+| `cubemx_generate` | 加载 .ioc 并 `project generate` 生成 HAL 工程 |
+| `cubemx_export_pinout` | 导出引脚配置 CSV(只读) |
+
+## 要求
+
+- Python **>= 3.10**,安装依赖 `mcp>=2.0`
+- **STM32CubeMX**(ST 专有软件,请从 ST 官网免费下载并自行遵守其许可)—— 本工具仅运行时调用其命令行,不包含、不修改其任何代码
+
+## 安装
+
+```bash
+pip install vscode-cube-mcp        # 从 PyPI(发布后)
+# 或本地开发安装
+pip install -e .
+```
+
+## 配置(环境变量)
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `ST_CUBEMX_EXE` | PATH 中的 `STM32CubeMX` / 常见 Windows 安装位置 | STM32CubeMX 可执行文件完整路径 |
+| `ST_CUBEMX_ALLOWED_ROOTS` | 当前工作目录 | .ioc 允许访问的根目录,`os.pathsep` 分隔(`;` for Windows) |
+| `ST_CUBEMX_TIMEOUT` | `240` | CubeMX 子进程超时秒数 |
+
+示例(Windows PowerShell):
+
+```powershell
+$env:ST_CUBEMX_EXE = "C:\MINE\STM\STM\STM32CubeMX.exe"
+$env:ST_CUBEMX_ALLOWED_ROOTS = "C:\MINE\STM32Project\STM32VScode"
+```
+
+> 安全设计:所有 .ioc / 生成路径都必须在 `ST_CUBEMX_ALLOWED_ROOTS` 白名单内,
+> 白名单外的路径会被拒绝(路径校验见 `_check_path`)。
+
+## 使用(接入 MCP 客户端)
+
+把 server 注册到支持 MCP 的客户端(如 Reasonix / Claude Desktop 等),
+stdio 方式启动:
+
+```json
+{
+  "mcpServers": {
+    "Vscode_cube_mcp": {
+      "command": "python",
+      "args": ["-m", "cubemx_mcp"]
+    }
+  }
+}
+```
+
+或直接用 console 入口:
+
+```bash
+vscode-cube-mcp
+```
+
+## 开发
+
+```bash
+python -m unittest test_cubemx_mcp -v   # 运行单元测试(不依赖 CubeMX)
+```
+
+测试覆盖:`_cleanup` 噪音过滤、`_check_path` 白名单校验、`_find_cubemx` /
+`_allowed_roots` 配置解析、`_run_script`(mock 子进程)的 KO 检测与超时路径。
+
+## 许可与依赖声明
+
+- **本工具代码**:MIT License(见 `LICENSE`)
+- **mcp SDK**(唯一 Python 依赖):MIT License(modelcontextprotocol/python-sdk)
+- **STM32CubeMX**:ST 专有软件,运行时外部调用,需用户自备并遵守其许可条款
+
+## 实践经验(2026-08-05,OLED_MCP 项目踩坑记录)
+
+用 `cubemx_generate` 生成的新工程,在 VSCode 里用 **STM32 VS Code Extension** 打开时可能遇到:
+Run and Debug 迟迟不出现 / ST 扩展识别工程很慢 / 报 `OLED_MCPsettings\ide.store.json` 之类 ENOENT。
+
+**根因**:CubeMX CLI 生成的新工程缺少 ST 扩展识别工程所需的文件:
+
+| 文件 | 作用 |
+|------|------|
+| `.settings/ide.store.json` | 声明 `sourceType=STM32CubeMX`、`device`、`core`(扩展识别硬件的关键) |
+| `.settings/bundles.store.json`、`bundles-lock.store.json` | bundles(工具链)版本锁定 |
+| `.vscode/settings.json` | cube-cmake / clangd 配置 |
+| `.vscode/c_cpp_properties.json` | compile_commands.json 索引 |
+| `.clangd` | clangd 配置 |
+
+**正确做法(对齐实例工程,如 OLED_HAL)**:
+1. 生成新工程后,**不要手写 launch.json**(实例工程没有,ST 扩展会自动提供调试配置);
+2. 在 VSCode 里**重新加载窗口**(Reload Window),扩展会识别工程并自动补齐上述文件(device 名取自 `.ioc`,如 `STM32F103C8T6`);
+3. 若扩展没自动补齐,可从同芯片的实例工程复制 `.settings/`、`.vscode/`、`.clangd`(注意核对 `ide.store.json` 里的 `device` 是否一致)。
+
+**其他教训**:
+- 若确实要手写 launch.json,ST 扩展的调试器类型是 `stlinkgdbtarget`,`deviceName` 必须与 `.settings/ide.store.json` 的 `device` 一致(如 `STM32F103C8T6`,不是 `STM32F103C8Tx`),否则扩展可能解析异常;
+- 本机 STM32 VS Code Extension 全家桶调试类型:`stlinkgdbtarget`(ST-Link)/ `jlinkgdbtarget`(J-Link)/ `stgdbtarget`(通用 GDB);
+- `cubemx_generate` 的 `project path` 对已存在目录返回 KO 是正常现象,generate 默认在 .ioc 同目录生成,结果不受影响。
+
+## 能力边界:不是真正意义上的"从零开始"
+
+所有工具都要求先有一个 `.ioc` 文件(`cubemx_load` / `cubemx_configure` / `cubemx_generate` 起手都是 `config load`,且 `_ioc_path()` 校验文件必须存在):
+
+- CubeMX 的 `-q` 脚本模式**没有 `new project` 命令**,"新建工程 → 选芯片"是 GUI 独有的流程;
+- 因此"生成新工程"的实际做法是:**复制一个 6.18 原生生成的 .ioc(TEST / OLED_HAL 这类)改造**(改 `ProjectManager.ProjectName` / `ProjectFileName`,再用 `set` 命令加外设/引脚)后 `cubemx_generate`;
+- 手写全新 .ioc 理论可行,但 6.18-RC3 对手写/非原生 .ioc 加载会 NPE,不推荐。

vscode_cube_mcp-0.1.0/vscode_cube_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+cubemx_mcp.py
+pyproject.toml
+vscode_cube_mcp.egg-info/PKG-INFO
+vscode_cube_mcp.egg-info/SOURCES.txt
+vscode_cube_mcp.egg-info/dependency_links.txt
+vscode_cube_mcp.egg-info/entry_points.txt
+vscode_cube_mcp.egg-info/requires.txt
+vscode_cube_mcp.egg-info/top_level.txt

vscode_cube_mcp-0.1.0/vscode_cube_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vscode_cube_mcp-0.1.0/vscode_cube_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vscode-cube-mcp = cubemx_mcp:main

vscode_cube_mcp-0.1.0/vscode_cube_mcp.egg-info/requires.txt

@@ -0,0 +1 @@
+mcp>=2.0.0

vscode_cube_mcp-0.1.0/vscode_cube_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+cubemx_mcp