CodeBuddy中使用 MCP 工具将 XMind 思维导图转换为 Markdown —— 实操流程汇总

CodeBuddy中使用 MCP 工具将 XMind 思维导图转换为 Markdown ------ 实操流程汇总

一、背景与目标

XMind 思维导图擅长发散与结构化思考，但在文本编辑器、文档站点或支持 Markdown 的协作平台上，Markdown 更利于检索、引用与二次编辑。本次目标：把一份 XMind 导图（转换为 Markdown，保存为 D:\test\test.md，兼顾"图形化结构"与"文本化流通"。

二、本地接入 MCP 服务 `xmind-to-markdown` 的流程

本次转换依赖一个本地 MCP 服务，其配置位于 c:\Users\admin\.codebuddy\mcp.json，核心内容如下：

json 复制代码

{
  "mcpServers": {
    "xmind-to-markdown": {
      "type": "stdio",
      "command": "C:/Users/admin/AppData/Roaming/Python/Python314/Scripts/xmind-to-markdown-mcp.exe",
      "args": [],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      },
      "description": "XMind 转 Markdown 转换工具"
    }
  }
}

接入流程可拆为四步：

安装转换工具（Python 包）

通过 Python 的包管理器安装，安装后会在 Python 的 Scripts 目录生成可执行入口 xmind-to-markdown-mcp.exe（路径指向 ...\Python314\Scripts\...，说明基于 Python 3.14 环境，使用 pip install 类命令安装）。
复制代码
```
pip install xmind-to-markdown-mcp
```
编写 MCP 配置文件

在 CodeBuddy 的配置目录（C:\Users\admin\.codebuddy\）下创建/编辑 mcp.json，在 mcpServers 中新增 xmind-to-markdown 节点。

或直接CodeBuddy页面右上角设置-MCP-配置MCP
配置关键项
- type: "stdio"：CodeBuddy 以子进程方式拉起该 exe，通过标准输入输出（stdin/stdout）与之通信；
- command：指向安装生成的 .exe 绝对路径，必须与实际安装位置一致，否则服务无法启动；
- env.PYTHONIOENCODING: "utf-8"：强制 Python 标准流以 UTF-8 编码，避免中文节点出现乱码或解码报错（关键项）；
- args: []：当前无需额外启动参数。
加载与验证服务

保存配置后重启/重载 CodeBuddy 的 MCP 连接，确认 xmind-to-markdown 服务在线，并已暴露 read_xmind_structure 与 convert_xmind_to_markdown 两个工具，即可开始转换。

三、转换操作步骤（详细）

切换Craft模式，对话直接输入：

把 D:\test/test.xmind 转成 Markdown，并保存到 D:/test/test.md

转换效果：

四、前面遇到的问题汇总

在复核与接入过程中，发现/需留意以下问题：

4.1 中文编码问题（配置已规避，但易踩坑）

MCP 服务通过 Python 子进程运行，Windows 下标准流默认编码可能导致中文节点乱码/抛 UnicodeDecodeError。配置文件中的 PYTHONIOENCODING=utf-8 正是为此而设；若将来更换环境或手动启动 exe，务必带上该环境变量。

4.2 路径转义与分隔符

JSON 入参里 Windows 路径需用双反斜杠 \\ 或统一正斜杠 /（如 D:/test/test.xmind），混用 D:\test/test.xmind 这类写法虽有时可用，但存在解析歧义风险。

4.3 服务启动失败的常见诱因

command 指向的 exe 路径错误（Python 版本/安装目录不符）；
未安装对应 Python 包，导致 exe 不存在；
配置文件 JSON 语法错误（如缺逗号、引号不匹配），会使整个 mcpServers 加载失败。

五、转换效果

层级保留 ：导图嵌套关系映射为 Markdown 标题层级（#、##、### ...）；
内容完整：节点文本原样输出，缩进/嵌套对应标题深度；

六、注意事项与最佳实践

转换前先用 read_xmind_structure 预览结构，确认源文件可读；
转换后人工抽查关键分支，确认深层节点未丢失；
保持 PYTHONIOENCODING=utf-8 配置，守护中文内容；
源/目标路径使用正斜杠或双反斜杠，规避转义问题；
建议转换后立即核对目标文件是否真实落盘。

七、小结

借助 xmind-to-markdown MCP 服务，经"安装工具 → 配置 mcp.json → 重载服务 → 调用转换 → 校验落盘"五步，即可把 XMind 导图无损转为 Markdown。过程中需特别留意 exe 路径准确性、中文编码环境变量、以及转换产物是否真正写入磁盘 三类问题，方能稳定运行。

CodeBuddy中使用 MCP 工具将 XMind 思维导图转换为 Markdown —— 实操流程汇总