xmind-mcp-server 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. xmind_mcp_server-0.1.0/LICENSE +21 -0
  2. xmind_mcp_server-0.1.0/PKG-INFO +324 -0
  3. xmind_mcp_server-0.1.0/README.md +284 -0
  4. xmind_mcp_server-0.1.0/pyproject.toml +66 -0
  5. xmind_mcp_server-0.1.0/setup.cfg +4 -0
  6. xmind_mcp_server-0.1.0/src/xmind_mcp/__init__.py +3 -0
  7. xmind_mcp_server-0.1.0/src/xmind_mcp/__main__.py +9 -0
  8. xmind_mcp_server-0.1.0/src/xmind_mcp/cli.py +158 -0
  9. xmind_mcp_server-0.1.0/src/xmind_mcp/config.py +60 -0
  10. xmind_mcp_server-0.1.0/src/xmind_mcp/hardware/__init__.py +14 -0
  11. xmind_mcp_server-0.1.0/src/xmind_mcp/hardware/detector.py +211 -0
  12. xmind_mcp_server-0.1.0/src/xmind_mcp/hardware/installer.py +119 -0
  13. xmind_mcp_server-0.1.0/src/xmind_mcp/ocr/__init__.py +6 -0
  14. xmind_mcp_server-0.1.0/src/xmind_mcp/ocr/base.py +43 -0
  15. xmind_mcp_server-0.1.0/src/xmind_mcp/ocr/manager.py +143 -0
  16. xmind_mcp_server-0.1.0/src/xmind_mcp/ocr/paddleocr_backend.py +90 -0
  17. xmind_mcp_server-0.1.0/src/xmind_mcp/ocr/rapidocr_backend.py +100 -0
  18. xmind_mcp_server-0.1.0/src/xmind_mcp/server.py +67 -0
  19. xmind_mcp_server-0.1.0/src/xmind_mcp/tools.py +584 -0
  20. xmind_mcp_server-0.1.0/src/xmind_mcp/xmind_parser.py +310 -0
  21. xmind_mcp_server-0.1.0/src/xmind_mcp/xmind_writer.py +208 -0
  22. xmind_mcp_server-0.1.0/src/xmind_mcp_server.egg-info/PKG-INFO +324 -0
  23. xmind_mcp_server-0.1.0/src/xmind_mcp_server.egg-info/SOURCES.txt +29 -0
  24. xmind_mcp_server-0.1.0/src/xmind_mcp_server.egg-info/dependency_links.txt +1 -0
  25. xmind_mcp_server-0.1.0/src/xmind_mcp_server.egg-info/entry_points.txt +2 -0
  26. xmind_mcp_server-0.1.0/src/xmind_mcp_server.egg-info/requires.txt +21 -0
  27. xmind_mcp_server-0.1.0/src/xmind_mcp_server.egg-info/top_level.txt +1 -0
  28. xmind_mcp_server-0.1.0/tests/test_parser.py +75 -0
  29. xmind_mcp_server-0.1.0/tests/test_server.py +74 -0
  30. xmind_mcp_server-0.1.0/tests/test_tools.py +184 -0
  31. xmind_mcp_server-0.1.0/tests/test_writer.py +113 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,324 @@
1
+ Metadata-Version: 2.4
2
+ Name: xmind-mcp-server
3
+ Version: 0.1.0
4
+ Summary: 让大模型读写 XMind 文件,支持图片 OCR 的 MCP Server
5
+ Author-email: GarryWhite <garrywhite@example.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/GarryWhite109909/xmind-mcp-server
8
+ Project-URL: Repository, https://github.com/GarryWhite109909/xmind-mcp-server
9
+ Project-URL: Issues, https://github.com/GarryWhite109909/xmind-mcp-server/issues
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Operating System :: OS Independent
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: mcp>=2.0.0
23
+ Requires-Dist: psutil>=5.9.0
24
+ Requires-Dist: Pillow>=10.0.0
25
+ Provides-Extra: rapidocr
26
+ Requires-Dist: rapidocr-onnxruntime>=1.2.0; extra == "rapidocr"
27
+ Requires-Dist: onnxruntime>=1.16.0; extra == "rapidocr"
28
+ Provides-Extra: paddleocr
29
+ Requires-Dist: paddleocr>=2.7.0; extra == "paddleocr"
30
+ Requires-Dist: paddlepaddle>=2.6.0; extra == "paddleocr"
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
33
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
34
+ Provides-Extra: all
35
+ Requires-Dist: rapidocr-onnxruntime>=1.2.0; extra == "all"
36
+ Requires-Dist: onnxruntime>=1.16.0; extra == "all"
37
+ Requires-Dist: pytest>=7.0.0; extra == "all"
38
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
39
+ Dynamic: license-file
40
+
41
+ # XMind MCP Server
42
+
43
+ > 让大模型真正“看懂”并“修改” XMind 思维导图的本地 MCP Server。
44
+
45
+ [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
46
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
47
+
48
+ XMind MCP Server 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的本地服务。它把 XMind 文件解析、图片 OCR、节点编辑和文件写回能力封装成一套标准工具,供 Trae、Claude Desktop、Cursor 等支持 MCP 的客户端调用。
49
+
50
+ ---
51
+
52
+ ## ✨ 核心亮点
53
+
54
+ ### 1. 不只是读文字,还能读图片
55
+
56
+ 普通方式只能让模型看到节点的标题文字。XMind MCP Server 会对节点中的图片进行本地 OCR,把图片里的文字也喂给模型,真正“看懂”整份思维导图。
57
+
58
+ ```text
59
+ 📄 工作表: 操作系统
60
+ └─ [L0] [id: root-1] 操作系统
61
+ └─ [L1] [id: abc-123] 📷图片
62
+ ↳ [OCR] 中央处理器
63
+ (CPU)
64
+ ```
65
+
66
+ ### 2. 既能读,也能写
67
+
68
+ 支持通过自然语言指令让模型直接修改 XMind 文件:
69
+
70
+ - 添加子节点
71
+ - 修改标题 / 备注
72
+ - 删除节点
73
+ - 移动节点
74
+ - 保存回原文件或另存为新文件
75
+
76
+ ### 3. 本地 OCR,零云端依赖
77
+
78
+ 内置 RapidOCR(默认)和 PaddleOCR 两种后端,全部在本地运行:
79
+
80
+ - 不调用任何云端多模态 API
81
+ - 不消耗 Token
82
+ - 图片内容识别不上传到第三方
83
+
84
+ ### 4. 自动硬件检测与最佳配置
85
+
86
+ 首次启动自动检测 GPU、CPU、内存,并选择最适合的推理后端:
87
+
88
+ | 显卡 | Windows | Linux | macOS |
89
+ |------|---------|-------|-------|
90
+ | NVIDIA | CUDA ✅ | CUDA ✅ | CPU |
91
+ | AMD | DirectML ✅ | CPU | CPU |
92
+ | Intel | DirectML ✅ | CPU | CPU |
93
+ | 无独显 | CPU ✅ | CPU ✅ | CPU ✅ |
94
+
95
+ ### 5. 安全写回,保留原文件结构
96
+
97
+ 保存时不会破坏 XMind 文件中的样式、主题、附件、manifest 等资源,只修改 `content.json`,再安全重组 ZIP。
98
+
99
+ ---
100
+
101
+ ## 🆚 与纯 Python 脚本对比
102
+
103
+ | 能力 | 纯 Python 脚本 | XMind MCP Server |
104
+ |------|---------------|------------------|
105
+ | 读文本节点 | ✅ 可以 | ✅ 可以 |
106
+ | 找图片位置 | ⚠️ 容易漏(summary、attachment、notes 里的图) | ✅ 封装完整 |
107
+ | 理解图片内容 | ❌ 必须依赖多模态模型 | ✅ 本地 OCR,不依赖模型能力 |
108
+ | 写回 xmind | ⚠️ 要手动处理 manifest checksum、ZIP 重组 | ✅ 封装安全写回 |
109
+ | 批量处理 | ⚠️ 自己写循环 | ✅ 统一接口 |
110
+ | 被大模型调用 | ❌ 需要额外包装 | ✅ MCP 标准协议 |
111
+
112
+ ---
113
+
114
+ ## 📦 安装
115
+
116
+ > **PyPI 发布状态**:包名 `xmind-mcp-server` 目前尚未发布到 PyPI。当前只能通过源码或 Git 安装。未来发布到 PyPI 后,即可使用 `pip install xmind-mcp-server`。
117
+
118
+ ### 从 GitHub 安装(推荐)
119
+
120
+ ```bash
121
+ pip install "git+https://github.com/GarryWhite109909/xmind-mcp-server.git#egg=xmind-mcp-server[rapidocr]"
122
+ ```
123
+
124
+ ### 从源码安装
125
+
126
+ ```bash
127
+ git clone https://github.com/GarryWhite109909/xmind-mcp-server.git
128
+ cd xmind-mcp-server
129
+ pip install -e ".[dev]"
130
+ ```
131
+
132
+ ---
133
+
134
+ ## 🚀 快速开始
135
+
136
+ ### 1. 首次启动(自动配置)
137
+
138
+ ```bash
139
+ xmind-mcp
140
+ ```
141
+
142
+ 首次运行会:
143
+
144
+ 1. 检测操作系统、CPU、内存、显卡
145
+ 2. 选择合适的 OCR 引擎和推理设备
146
+ 3. 安装对应的推理依赖(如 onnxruntime-gpu / directml)
147
+ 4. 写入配置到 `~/.xmind-mcp/config.json`
148
+
149
+ 第二次运行直接启动,无需重复配置。
150
+
151
+ ### 2. 在 Trae / Claude Desktop / Cursor 中配置
152
+
153
+ #### Trae
154
+
155
+ 打开设置 → MCP,添加服务器:
156
+
157
+ ```json
158
+ {
159
+ "mcpServers": {
160
+ "xmind-mcp": {
161
+ "command": "xmind-mcp",
162
+ "args": []
163
+ }
164
+ }
165
+ }
166
+ ```
167
+
168
+ 如果 `xmind-mcp` 不在系统 PATH,使用 Python 解释器绝对路径:
169
+
170
+ ```json
171
+ {
172
+ "mcpServers": {
173
+ "xmind-mcp": {
174
+ "command": "C:\\Users\\<你的用户名>\\.miniconda\\python.exe",
175
+ "args": ["-m", "xmind_mcp"]
176
+ }
177
+ }
178
+ }
179
+ ```
180
+
181
+ > 💡 修改代码后,需要在 Trae 中禁用再启用该 MCP,或重启 Trae,才能加载最新版本。
182
+
183
+ #### Claude Desktop
184
+
185
+ 编辑 `claude_desktop_config.json`:
186
+
187
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
188
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
189
+
190
+ ```json
191
+ {
192
+ "mcpServers": {
193
+ "xmind-mcp": {
194
+ "command": "xmind-mcp",
195
+ "args": []
196
+ }
197
+ }
198
+ }
199
+ ```
200
+
201
+ ---
202
+
203
+ ## 🛠️ 工具一览
204
+
205
+ ### 读取类
206
+
207
+ | 工具 | 说明 |
208
+ |------|------|
209
+ | `read_structure` | 读取节点树结构,默认输出层级 + 节点 ID |
210
+ | `read_all` | 节点树 + 图片 OCR + notes/labels/markers 元数据 |
211
+ | `list_images` | 列出所有含图片的节点 |
212
+ | `read_image_ocr` | 对指定节点的图片做 OCR |
213
+ | `find_node` | 按标题关键词搜索节点,返回 ID 和路径 |
214
+ | `export_markdown` | 导出为 Markdown 大纲 |
215
+
216
+ ### 编辑类
217
+
218
+ | 工具 | 说明 |
219
+ |------|------|
220
+ | `add_node` | 在指定父节点下添加子节点 |
221
+ | `update_node` | 更新节点标题 / 备注 |
222
+ | `delete_node` | 删除节点及其子节点 |
223
+ | `move_node` | 移动节点到新父节点下 |
224
+ | `save_file` | 保存修改,可覆盖或另存为 |
225
+
226
+ 所有编辑工具都支持 `auto_save=true`,设置后会自动保存,无需再手动调用 `save_file`。
227
+
228
+ ### 系统类
229
+
230
+ | 工具 | 说明 |
231
+ |------|------|
232
+ | `get_hardware_info` | 查看硬件检测和 OCR 配置 |
233
+
234
+ ---
235
+
236
+ ## 💬 使用示例
237
+
238
+ ### 例 1:让模型总结一份 XMind
239
+
240
+ > 请读取 `D:\\docs\\操作系统.xmind`,总结其中的核心概念,并识别所有图片里的文字。
241
+
242
+ 模型会调用:
243
+
244
+ 1. `read_all` 读取完整结构和图片 OCR
245
+ 2. 基于返回内容生成总结
246
+
247
+ ### 例 2:搜索节点并编辑
248
+
249
+ > 在 `D:\\docs\\操作系统.xmind` 中找到“进程”相关节点,给它们都加上一条备注“需重点复习”。
250
+
251
+ 模型会调用:
252
+
253
+ 1. `find_node` 搜索“进程”
254
+ 2. `update_node` 更新备注(可设置 `auto_save=true`)
255
+
256
+ ### 例 3:导出为 Markdown
257
+
258
+ > 把 `D:\\docs\\操作系统.xmind` 导出成 Markdown 大纲,保留节点 ID。
259
+
260
+ 模型会调用 `export_markdown`,返回:
261
+
262
+ ```markdown
263
+ # 操作系统
264
+
265
+ - 操作系统 `id:root-1`
266
+ - 进程 `id:child-1`
267
+ - 线程 `id:child-2`
268
+ ```
269
+
270
+ ---
271
+
272
+ ## ⚙️ 命令行参数
273
+
274
+ ```bash
275
+ xmind-mcp # 启动 MCP Server(首次自动配置)
276
+ xmind-mcp --setup # 重新检测硬件并配置
277
+ xmind-mcp --info # 打印当前硬件和配置信息
278
+ xmind-mcp --engine rapidocr # 指定 OCR 引擎
279
+ xmind-mcp --device cuda # 强制指定推理设备
280
+ ```
281
+
282
+ 切换 OCR 引擎:
283
+
284
+ ```bash
285
+ xmind-mcp --setup --engine paddleocr
286
+ ```
287
+
288
+ ---
289
+
290
+ ## 📁 本地文件位置
291
+
292
+ | 文件/目录 | 说明 |
293
+ |----------|------|
294
+ | `~/.xmind-mcp/config.json` | 硬件检测结果、OCR 引擎、推理设备配置 |
295
+ | `~/.xmind-mcp/ocr_cache.db` | OCR 结果缓存,避免同一张图重复识别 |
296
+ | `~/.xmind-mcp/models/` | OCR 模型下载缓存 |
297
+
298
+ > MCP 关闭时会自动释放 OCR 模型占用的内存 / 显存。
299
+
300
+ ---
301
+
302
+ ## ✅ 支持的 XMind 版本
303
+
304
+ - ✅ XMind Zen / XMind 2020+ / 2022 / 2024(JSON 格式)
305
+ - ❌ XMind 8 及更早(XML 格式,暂不支持)
306
+
307
+ ---
308
+
309
+ ## 🧪 开发 & 测试
310
+
311
+ ```bash
312
+ git clone https://github.com/GarryWhite109909/xmind-mcp-server.git
313
+ cd xmind-mcp-server
314
+ pip install -e ".[dev]"
315
+ pytest
316
+ ```
317
+
318
+ 当前测试覆盖:文件解析、节点增删改查、图片加载、OCR、MCP Server 协议握手、Markdown 导出等。
319
+
320
+ ---
321
+
322
+ ## 📄 License
323
+
324
+ MIT © GarryWhite
@@ -0,0 +1,284 @@
1
+ # XMind MCP Server
2
+
3
+ > 让大模型真正“看懂”并“修改” XMind 思维导图的本地 MCP Server。
4
+
5
+ [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
6
+ [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7
+
8
+ XMind MCP Server 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的本地服务。它把 XMind 文件解析、图片 OCR、节点编辑和文件写回能力封装成一套标准工具,供 Trae、Claude Desktop、Cursor 等支持 MCP 的客户端调用。
9
+
10
+ ---
11
+
12
+ ## ✨ 核心亮点
13
+
14
+ ### 1. 不只是读文字,还能读图片
15
+
16
+ 普通方式只能让模型看到节点的标题文字。XMind MCP Server 会对节点中的图片进行本地 OCR,把图片里的文字也喂给模型,真正“看懂”整份思维导图。
17
+
18
+ ```text
19
+ 📄 工作表: 操作系统
20
+ └─ [L0] [id: root-1] 操作系统
21
+ └─ [L1] [id: abc-123] 📷图片
22
+ ↳ [OCR] 中央处理器
23
+ (CPU)
24
+ ```
25
+
26
+ ### 2. 既能读,也能写
27
+
28
+ 支持通过自然语言指令让模型直接修改 XMind 文件:
29
+
30
+ - 添加子节点
31
+ - 修改标题 / 备注
32
+ - 删除节点
33
+ - 移动节点
34
+ - 保存回原文件或另存为新文件
35
+
36
+ ### 3. 本地 OCR,零云端依赖
37
+
38
+ 内置 RapidOCR(默认)和 PaddleOCR 两种后端,全部在本地运行:
39
+
40
+ - 不调用任何云端多模态 API
41
+ - 不消耗 Token
42
+ - 图片内容识别不上传到第三方
43
+
44
+ ### 4. 自动硬件检测与最佳配置
45
+
46
+ 首次启动自动检测 GPU、CPU、内存,并选择最适合的推理后端:
47
+
48
+ | 显卡 | Windows | Linux | macOS |
49
+ |------|---------|-------|-------|
50
+ | NVIDIA | CUDA ✅ | CUDA ✅ | CPU |
51
+ | AMD | DirectML ✅ | CPU | CPU |
52
+ | Intel | DirectML ✅ | CPU | CPU |
53
+ | 无独显 | CPU ✅ | CPU ✅ | CPU ✅ |
54
+
55
+ ### 5. 安全写回,保留原文件结构
56
+
57
+ 保存时不会破坏 XMind 文件中的样式、主题、附件、manifest 等资源,只修改 `content.json`,再安全重组 ZIP。
58
+
59
+ ---
60
+
61
+ ## 🆚 与纯 Python 脚本对比
62
+
63
+ | 能力 | 纯 Python 脚本 | XMind MCP Server |
64
+ |------|---------------|------------------|
65
+ | 读文本节点 | ✅ 可以 | ✅ 可以 |
66
+ | 找图片位置 | ⚠️ 容易漏(summary、attachment、notes 里的图) | ✅ 封装完整 |
67
+ | 理解图片内容 | ❌ 必须依赖多模态模型 | ✅ 本地 OCR,不依赖模型能力 |
68
+ | 写回 xmind | ⚠️ 要手动处理 manifest checksum、ZIP 重组 | ✅ 封装安全写回 |
69
+ | 批量处理 | ⚠️ 自己写循环 | ✅ 统一接口 |
70
+ | 被大模型调用 | ❌ 需要额外包装 | ✅ MCP 标准协议 |
71
+
72
+ ---
73
+
74
+ ## 📦 安装
75
+
76
+ > **PyPI 发布状态**:包名 `xmind-mcp-server` 目前尚未发布到 PyPI。当前只能通过源码或 Git 安装。未来发布到 PyPI 后,即可使用 `pip install xmind-mcp-server`。
77
+
78
+ ### 从 GitHub 安装(推荐)
79
+
80
+ ```bash
81
+ pip install "git+https://github.com/GarryWhite109909/xmind-mcp-server.git#egg=xmind-mcp-server[rapidocr]"
82
+ ```
83
+
84
+ ### 从源码安装
85
+
86
+ ```bash
87
+ git clone https://github.com/GarryWhite109909/xmind-mcp-server.git
88
+ cd xmind-mcp-server
89
+ pip install -e ".[dev]"
90
+ ```
91
+
92
+ ---
93
+
94
+ ## 🚀 快速开始
95
+
96
+ ### 1. 首次启动(自动配置)
97
+
98
+ ```bash
99
+ xmind-mcp
100
+ ```
101
+
102
+ 首次运行会:
103
+
104
+ 1. 检测操作系统、CPU、内存、显卡
105
+ 2. 选择合适的 OCR 引擎和推理设备
106
+ 3. 安装对应的推理依赖(如 onnxruntime-gpu / directml)
107
+ 4. 写入配置到 `~/.xmind-mcp/config.json`
108
+
109
+ 第二次运行直接启动,无需重复配置。
110
+
111
+ ### 2. 在 Trae / Claude Desktop / Cursor 中配置
112
+
113
+ #### Trae
114
+
115
+ 打开设置 → MCP,添加服务器:
116
+
117
+ ```json
118
+ {
119
+ "mcpServers": {
120
+ "xmind-mcp": {
121
+ "command": "xmind-mcp",
122
+ "args": []
123
+ }
124
+ }
125
+ }
126
+ ```
127
+
128
+ 如果 `xmind-mcp` 不在系统 PATH,使用 Python 解释器绝对路径:
129
+
130
+ ```json
131
+ {
132
+ "mcpServers": {
133
+ "xmind-mcp": {
134
+ "command": "C:\\Users\\<你的用户名>\\.miniconda\\python.exe",
135
+ "args": ["-m", "xmind_mcp"]
136
+ }
137
+ }
138
+ }
139
+ ```
140
+
141
+ > 💡 修改代码后,需要在 Trae 中禁用再启用该 MCP,或重启 Trae,才能加载最新版本。
142
+
143
+ #### Claude Desktop
144
+
145
+ 编辑 `claude_desktop_config.json`:
146
+
147
+ - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
148
+ - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
149
+
150
+ ```json
151
+ {
152
+ "mcpServers": {
153
+ "xmind-mcp": {
154
+ "command": "xmind-mcp",
155
+ "args": []
156
+ }
157
+ }
158
+ }
159
+ ```
160
+
161
+ ---
162
+
163
+ ## 🛠️ 工具一览
164
+
165
+ ### 读取类
166
+
167
+ | 工具 | 说明 |
168
+ |------|------|
169
+ | `read_structure` | 读取节点树结构,默认输出层级 + 节点 ID |
170
+ | `read_all` | 节点树 + 图片 OCR + notes/labels/markers 元数据 |
171
+ | `list_images` | 列出所有含图片的节点 |
172
+ | `read_image_ocr` | 对指定节点的图片做 OCR |
173
+ | `find_node` | 按标题关键词搜索节点,返回 ID 和路径 |
174
+ | `export_markdown` | 导出为 Markdown 大纲 |
175
+
176
+ ### 编辑类
177
+
178
+ | 工具 | 说明 |
179
+ |------|------|
180
+ | `add_node` | 在指定父节点下添加子节点 |
181
+ | `update_node` | 更新节点标题 / 备注 |
182
+ | `delete_node` | 删除节点及其子节点 |
183
+ | `move_node` | 移动节点到新父节点下 |
184
+ | `save_file` | 保存修改,可覆盖或另存为 |
185
+
186
+ 所有编辑工具都支持 `auto_save=true`,设置后会自动保存,无需再手动调用 `save_file`。
187
+
188
+ ### 系统类
189
+
190
+ | 工具 | 说明 |
191
+ |------|------|
192
+ | `get_hardware_info` | 查看硬件检测和 OCR 配置 |
193
+
194
+ ---
195
+
196
+ ## 💬 使用示例
197
+
198
+ ### 例 1:让模型总结一份 XMind
199
+
200
+ > 请读取 `D:\\docs\\操作系统.xmind`,总结其中的核心概念,并识别所有图片里的文字。
201
+
202
+ 模型会调用:
203
+
204
+ 1. `read_all` 读取完整结构和图片 OCR
205
+ 2. 基于返回内容生成总结
206
+
207
+ ### 例 2:搜索节点并编辑
208
+
209
+ > 在 `D:\\docs\\操作系统.xmind` 中找到“进程”相关节点,给它们都加上一条备注“需重点复习”。
210
+
211
+ 模型会调用:
212
+
213
+ 1. `find_node` 搜索“进程”
214
+ 2. `update_node` 更新备注(可设置 `auto_save=true`)
215
+
216
+ ### 例 3:导出为 Markdown
217
+
218
+ > 把 `D:\\docs\\操作系统.xmind` 导出成 Markdown 大纲,保留节点 ID。
219
+
220
+ 模型会调用 `export_markdown`,返回:
221
+
222
+ ```markdown
223
+ # 操作系统
224
+
225
+ - 操作系统 `id:root-1`
226
+ - 进程 `id:child-1`
227
+ - 线程 `id:child-2`
228
+ ```
229
+
230
+ ---
231
+
232
+ ## ⚙️ 命令行参数
233
+
234
+ ```bash
235
+ xmind-mcp # 启动 MCP Server(首次自动配置)
236
+ xmind-mcp --setup # 重新检测硬件并配置
237
+ xmind-mcp --info # 打印当前硬件和配置信息
238
+ xmind-mcp --engine rapidocr # 指定 OCR 引擎
239
+ xmind-mcp --device cuda # 强制指定推理设备
240
+ ```
241
+
242
+ 切换 OCR 引擎:
243
+
244
+ ```bash
245
+ xmind-mcp --setup --engine paddleocr
246
+ ```
247
+
248
+ ---
249
+
250
+ ## 📁 本地文件位置
251
+
252
+ | 文件/目录 | 说明 |
253
+ |----------|------|
254
+ | `~/.xmind-mcp/config.json` | 硬件检测结果、OCR 引擎、推理设备配置 |
255
+ | `~/.xmind-mcp/ocr_cache.db` | OCR 结果缓存,避免同一张图重复识别 |
256
+ | `~/.xmind-mcp/models/` | OCR 模型下载缓存 |
257
+
258
+ > MCP 关闭时会自动释放 OCR 模型占用的内存 / 显存。
259
+
260
+ ---
261
+
262
+ ## ✅ 支持的 XMind 版本
263
+
264
+ - ✅ XMind Zen / XMind 2020+ / 2022 / 2024(JSON 格式)
265
+ - ❌ XMind 8 及更早(XML 格式,暂不支持)
266
+
267
+ ---
268
+
269
+ ## 🧪 开发 & 测试
270
+
271
+ ```bash
272
+ git clone https://github.com/GarryWhite109909/xmind-mcp-server.git
273
+ cd xmind-mcp-server
274
+ pip install -e ".[dev]"
275
+ pytest
276
+ ```
277
+
278
+ 当前测试覆盖:文件解析、节点增删改查、图片加载、OCR、MCP Server 协议握手、Markdown 导出等。
279
+
280
+ ---
281
+
282
+ ## 📄 License
283
+
284
+ MIT © GarryWhite
@@ -0,0 +1,66 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "xmind-mcp-server"
7
+ version = "0.1.0"
8
+ description = "让大模型读写 XMind 文件,支持图片 OCR 的 MCP Server"
9
+ readme = "README.md"
10
+ license = {text = "MIT"}
11
+ authors = [
12
+ {name = "GarryWhite", email = "garrywhite@example.com"},
13
+ ]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.10",
20
+ "Programming Language :: Python :: 3.11",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Operating System :: OS Independent",
24
+ ]
25
+ requires-python = ">=3.10"
26
+ dependencies = [
27
+ "mcp>=2.0.0",
28
+ "psutil>=5.9.0",
29
+ "Pillow>=10.0.0",
30
+ ]
31
+
32
+ [project.optional-dependencies]
33
+ rapidocr = [
34
+ "rapidocr-onnxruntime>=1.2.0",
35
+ "onnxruntime>=1.16.0",
36
+ ]
37
+ paddleocr = [
38
+ "paddleocr>=2.7.0",
39
+ "paddlepaddle>=2.6.0",
40
+ ]
41
+ dev = [
42
+ "pytest>=7.0.0",
43
+ "pytest-asyncio>=0.21.0",
44
+ ]
45
+ all = [
46
+ "rapidocr-onnxruntime>=1.2.0",
47
+ "onnxruntime>=1.16.0",
48
+ "pytest>=7.0.0",
49
+ "pytest-asyncio>=0.21.0",
50
+ ]
51
+
52
+ [project.scripts]
53
+ xmind-mcp = "xmind_mcp.cli:main"
54
+
55
+ [project.urls]
56
+ Homepage = "https://github.com/GarryWhite109909/xmind-mcp-server"
57
+ Repository = "https://github.com/GarryWhite109909/xmind-mcp-server"
58
+ Issues = "https://github.com/GarryWhite109909/xmind-mcp-server/issues"
59
+
60
+ [tool.setuptools.packages.find]
61
+ where = ["src"]
62
+
63
+ [tool.pytest.ini_options]
64
+ testpaths = ["tests"]
65
+ pythonpath = ["src"]
66
+ asyncio_mode = "auto"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """xmind-mcp-server: 让大模型读写 XMind 文件,支持图片 OCR。"""
2
+
3
+ __version__ = "0.1.0"