用 TRAE 开发 Xmind-MCP 的心路历程
TRAE 是面向开发者、职场人与学生的 AI 办公平台，有 TRAE Work 和 TRAE IDE 两款产品。
TRAE Work 侧重学习、办公与工程执行场景，无论你是开发者、职场人、学生，都可以用它写方案、做分析、处理文件、推进协作，并完成需要持续执行、检查和产出结果的自动化任务。支持 桌面端、网页版 和 移动端，多端协作，随时发起任务、查看进展、持续推进。
TRAE IDE 适合写代码、读项目、改 Bug 等开发工作，更适合期望精细控制自己的代码改动和执行过程的开发者。
作者：张博思，TRAE 开发者用户
摘要：本文记录了一个从“被 AI 生成的损坏文件搞到抓狂”到“自己动手开发一个 Xmind-MCP 工具”的全过程。如果你也曾为 AI 生成的思维导图无法打开而烦恼，或者对如何为 AI 扩展能力感到好奇，这里有我的踩坑、思考与实践经验。项目已开源（仓库见文末阅读原文），欢迎围观。
缘起：一个被 AI“逼上梁山”的下午
故事始于一个普通的下午，我让 TRAE 帮我规划一份 Playwright 的学习路线。为了更直观，我突发奇想，让它把学习计划转成 Xmind 格式的思维导图。
AI 很快给了我一个 Xmind 文件，但当我尝试用 Xmind 打开时，却收到了无情的错误提示。
我不死心，把错误代码发给 AI，指望它能帮我修复。
然而，反复修改了几次，生成的 Xmind 文件依然无法打开。那时我意识到，AI 可能缺乏创建 Xmind 文件的技能。
既然 AI 做不到，那就给它一个工具帮他做到！于是，我决定自己动手，开发一个能让 AI 真正操作 Xmind 文件的 MCP（模型上下文协议）工具。
为什么我选择把 XMind 工具做成 MCP 格式
原因其实很简单，总结下来就三点：
第一，我不想让写的操作 Xmind 的代码只发挥一次作用。它需要能跨项目复用，并且能方便分享，让更多人都能用上，实实在在地提升效率。因此需要将代码打包。
第二，如果打包成 jar 包或 npm 包，不仅使用门槛偏高，还会受限于项目的编程语言，用起来没有那么灵活便捷。
第三，也是最核心的一点 —— 我做这个工具的初衷，就是让 AI 能帮我们直接生成 Xmind 文档。而当下主流的、能让 AI 接入外部能力的方式就是 MCP，所以它自然成了实现这个目标的最优解。
从 0 到 1：我的 Xmind-MCP 开发笔记
技术选型：在 Node 碰壁后，转向 Python
这是我第一次尝试自己做一个 MCP，所以一开始没什么头绪。还好有 TRAE 陪我慢慢探索。最初，我看到很多 MCP 工具是通过 npx 安装的，便猜测或许可以用 Node 代码实现。我让 AI 帮我尝试了十几个不同的 npm 包，结果无一成功。
在反复验证后，我得出一个结论：目前来看，当前没有使用 Node 生成正常的 Xmind 文件的方案。于是，我把目光转向了后端语言，最终选择了 Python。
攻克核心：既然 AI 不懂，就给它一个“范本”
转向 Python 后，挑战依然存在。起初反复尝试，发现产出的文件在 Xmind 中打开时，依然会因为 XML 格式问题报错。不过，报错的信息和刚开始的不一样。这让我意识到，方向对了，只是细节不对。
既然 AI 不知道正确的 Xmind 文件内部结构是什么样的，那我就给它一个标准答案。
我打开 Xmind，手动创建了一个简单的 Xmind 文件，把它放在项目目录中作为“模板”交给 AI，让它参考这个文件的内部结构和 XML 格式来重新编写生成 Xmind 的逻辑。这个方法立竿见影，仅用几轮对话，AI 就帮我写出了能生成可正常打开的 Xmind 文件的核心代码！
这也给我带来一个在 AI coding 中的宝贵经验：当 AI 不知道一件事怎么做时，给他一个“标准答案”。这听起来像不像 skills 的思路？
封装成 MCP：服务器方案的弯路与 PyPI 的正途
核心功能完成后，下一步是把它封装成一个能被 AI 调用的 MCP 工具。
第一次封装 MCP 没有经验，因此我向 AI 了解封装 MCP 的方案。AI 给出的最佳的建议是——将 Xmind MCP 部署到服务器上，通过 HTTP 接口的方式提供 Xmind 相关的服务。为此，我还认真研究和对比了各种免费服务器方案。
我对服务器部署的方案进行逐一验证，最后证明本 Xmind MCP 无法通过 HTTP 的方式成功安装并提供服务。
我故技重施，在 TRAE 的 MCP 市场中查看热门 MCP 的安装方式并提供给 AI 用于参考。我发现大部分 MCP 是不需要服务器，支持本地安装的。例如我最近正在学习的 playwright。
同时我查看了官方文档模型上下文协议（MCP） - 文档 - TRAE CN，支持本地打包安装的方式大抵有这三种
既然本项目使用的编程语言是 Python，选择很显然是 uvx ！而如果需要使用 uvx 的方式安装，首先需要打包发布到 PyPI 平台。
于是，我注册了 PyPI 账号，把我的项目打了包并发布。
当使用pip install xmind-mcp成功的那一刻，感觉非常奇妙。写了这么多年代码，终于让别人也能install我的包了！
确定 MCP 的安装方式后，还需要确定 MCP 的连接方式。常见的 MCP 连接方式有 FastMCP 和 stdio 两种，我选择了 FastMCP。
在配置 FastMCP 的过程又遇到了些波折，发现不同的大模型在解决同一个问题时的表现也各有千秋。
很意外的是，GPT5 等海外模型没成功帮我解决 MCP 连接的问题，但是 Kimi K2 解决成功了。
这段经历让我学到一个宝贵的教训：
遇到问题，如果几轮对话都无法解决，不要死磕，不妨换个模型试试。就像遇到问题没有头绪时，咨询下其他人的意见，可能就豁然开朗了。
实战与迭代：从“能用”到“好用”
MCP 工具初步跑通后，新的问题出现了：生成的 Xmind 文件保存在哪里？
我发现，由于 MCP 是通过 uvx 安装在 uv 的环境下，它运行时获取到的“当前目录”并不是我项目的工作区目录，导致生成的文件“不知所踪”。
为了解决这个问题，我从产品思维出发，做了两点改进：
1、入参设置输出路径：增加一个必填的输出路径参数，让 AI 可以指定生成的文件保存的位置。
2、明确路径反馈：让 MCP 在执行成功后，必须返回生成文件的绝对路径，方便用户找到。
我在本地测试通过后，我邀请了社区的 Nolan 大佬帮忙测试。果然，“不出意外就要出意外了”。在他的项目里，AI 似乎没完全理解如何正确调用我的 Xmind MCP，导致生成的 Xmind 结构错乱。
我认为问题出在 AI 对工具的“理解”上。我需要让我的 MCP “自我介绍”得更清楚。
于是我在 TRAE 请教 AI 有没有好的解决办法
结果和我猜想的一样，需要完善 MCP 的自描述。
接下来我使用 TRAE 优化了 MCP 的自描述信息，详细说明了每个方法中每个参数的用途和数据结构，特别是核心的 data 参数应该如何组织层级关系。
这次优化效果显著。经过 4 天、21 个版本的迭代，在 TRAE 的持续帮助下，这个 Xmind MCP 工具终于达到了稳定好用的状态。现在，AI 已经能一次性生成结构清晰、内容正确的思维导图了。
三步用上 Xmind-MCP
使用这个工具非常简单，毕竟，给 AI 用的工具，就不该为难人类用户。
第一步：复制配置在 TRAE 对话框的“设置” -> “MCP”标签页下，点击“手动添加”，然后粘贴以下 JSON 配置：
{
"mcpServers": {
"Xmind": {
"command": "uvx",
"args": [
"xmind-mcp",
"--mode",
"fastmcp"
]
}
}
}
第二步：安装环境依赖如果你的电脑没有安装过 Python 或 uv，TRAE 会引导你进行安装。对于 Windows 用户，安装 uv 后，请确保将 uv 的安装路径（通常是 C:\Users\YourUsername\.uv\bin）手动添加到系统环境变量的 Path 中。
第三步：选择智能体并开始使用安装成功后，选择你刚刚配置了 Xmind-MCP 的那个智能体，然后就可以直接向 AI 下达指令了。
例如，你可以说：“帮我使用 xmind mcp 生成一个关于 agent 学习的 xmind 文件。”
欢迎大家体验，有任何问题或建议，随时可以向我反馈！
Xmind MCP 能做什么？
目前，Xmind-MCP 支持以下核心功能：
- 读取思维导图：读取 Xmind 文件中每个节点的信息
- 创建思维导图：使用结构化数据（如 JSON）创建新的 Xmind 文件。
- 文件格式转换：支持将 TXT、Markdown、HTML、Word、Excel 等多种格式的内容直接转换成 Xmind 思维导图。
- 分析思维导图结构：分析 Xmind 文件中的节点数和最大层级等信息，并给出是否健康的评价。
- 文件检索：列出指定目录下的所有 Xmind 文件。
