内容
# @lifeng688/xmind-mcp
XMind 思维导图协议（Model Context Protocol）服务器，用于创建、读取、搜索、增量编辑、样式设置、链接和导出本地 XMind 思维导图文件。
让 Claude Desktop、Cursor 和 Claude Code 等 AI 助手直接创建和操作 `.xmind` 文件 - 无需桌面自动化、无需鼠标模拟，只需纯粹的文件 I/O 操作。
## 功能
### 核心思维导图功能
| 工具 | 描述 |
|---|---|
| `create_mindmap` | 从 JSON 主题树创建新的 `.xmind` 文件 |
| `read_mindmap` | 读取并解析现有的 `.xmind` 文件为结构化的 JSON |
| `markdown_to_mindmap` | 将 Markdown（标题 + 列表）转换为 `.xmind` 文件 |
| `export_to_markdown` | 将 `.xmind` 文件导出为 Markdown 格式 |
| `list_mindmaps` | 列出工作区目录中的所有 `.xmind` 文件 |
| `add_topic` | 在现有节点下添加子主题 |
| `update_topic` | 更新现有主题的标题、备注、标签、标记、超链接、链接、样式预设或样式 |
| `delete_topic` | 删除主题及其所有子主题（根节点受保护） |
| `search_topics` | 按标题、备注、标签、超链接、链接目标、样式预设和标记搜索主题 |
### v0.2.0 - 视觉元数据和链接
- **主题样式支持** - `fillColor`、`textColor`、`borderColor`、`branchColor`、`fontSize`、`bold`、`italic`、`underline`、`borderWidth`、`branchWidth`、`shape`、`fontFamily`
- **原生超链接支持** - 简单的 Web URL 速记（`href: "https://..."`）
- **向后兼容的超链接字段** - `hyperlink` 作为 `href` 的别名
- **结构化链接支持** - `link: { type: "web"|"file"|"folder"|"topic", target: "..." }`
- **标记支持** - `priority-1` 到 `priority-5`、`done`、`todo`、`star`、`heart`、`flag`、`warning`、`risk`、`blocked`、`check`、`progress`、`important`、`smiley-*`、`arrow-*`、`callout`
- **样式预设支持** - `important`、`success`、`warning`、`danger`、`info`、`idea`、`task`、`done`、`blocked`（每个都解析为颜色 + 可选标记）
- **Markdown 链接解析** - `[title](url)` 标题和列表项成为带有 Web 链接的主题
- **Markdown 导出保留链接** - Web 链接导出为 Markdown 链接 `[title](url)`
- **备注和标签支持** - 纯文本备注和自由格式标签/标签
- **改进的工具描述** - 所有 MCP 工具描述现在都指导 LLMs 使用视觉增强功能创建更丰富的思维导图
## 安装
```bash
# 全局安装
npm install -g @lifeng688/xmind-mcp
# 或直接运行，无需安装
npx @lifeng688/xmind-mcp
```
## MCP 客户端配置
### Claude Desktop / Cursor (Windows)
添加到您的 MCP 配置文件（`mcp.json`）：
```json
{
"mcpServers": {
"xmind": {
"command": "npx",
"args": ["@lifeng688/xmind-mcp"],
"env": {
"XMIND_WORKSPACE_DIR": "E:/xmind-workspace"
}
}
}
}
```
### Claude Desktop / Cursor (macOS / Linux)
```json
{
"mcpServers": {
"xmind": {
"command": "npx",
"args": ["@lifeng688/xmind-mcp"],
"env": {
"XMIND_WORKSPACE_DIR": "/Users/your-name/xmind-workspace"
}
}
}
}
```
### Claude Code
```bash
# 添加到您的项目的 .claude/settings.local.json
# 或直接运行：
npx @lifeng688/xmind-mcp
```
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `XMIND_WORKSPACE_DIR` | `./data/mindmaps` | 所有 `.xmind` 文件的根目录。**强烈建议**设置此变量以避免不受限制的文件访问。 |
| `XMIND_OUTPUT_DIR` | （无） | 可选的额外输出目录。 |
| `XMIND_ALLOW_OVERWRITE` | `false` | 是否允许覆盖现有的 `.xmind` 文件。 |
| `XMIND_AUTO_BACKUP` | `true` | 在修改前自动备份文件。 |
| `XMIND_AUDIT_LOG` | `true` | 将审计日志写入 `logs/audit.log`。 |
| `XMIND_MAX_TOPICS` | `500` | 每个思维导图的最大主题数。 |
| `LOG_LEVEL` | `info` | 日志级别（`debug`、`info`、`warn`、`error`）。 |
| `NODE_ENV` | `production` | 运行时环境。 |
> **建议：** 始终将 `XMIND_WORKSPACE_DIR` 设置为专用目录。不要将其指向系统根目录或敏感目录。
## 工具
| 工具 | 描述 |
|---|---|
| `create_mindmap` | 从 JSON 主题树创建新的 `.xmind` 文件。支持 `stylePreset`、`link`、`href`、`style`、`markers`、`labels`、`note`。 |
| `read_mindmap` | 读取并解析现有的 `.xmind` 文件。返回 `title`、`root` 树（带有所有 v0.2 字段）和 `topicCount`。 |
| `markdown_to_mindmap` | 将 Markdown 转换为 `.xmind`。解析 `[title](url)` 标题和列表项为带有 Web 链接的主题。 |
| `export_to_markdown` | 将 `.xmind` 导出为 Markdown。Web 链接成为 `[title](url)`，样式预设成为 `Style: name`，其他链接成为 `Link: type:url`。 |
| `list_mindmaps` | 列出工作区目录中的所有 `.xmind` 文件（递归）。 |
| `add_topic` | 在现有节点下添加子主题。支持 `link`、`href`、`stylePreset`、`style`、`markers`、`labels`、`note`。 |
| `update_topic` | 更新现有主题的任何属性。支持 `title`、`note`、`labels`、`markers`、`href`、`link`、`stylePreset`、`style`。传递 `null` 以删除字段。 |
| `delete_topic` | 删除主题及其整个子树。根节点受保护。 |
| `search_topics` | 按标题、备注、标签、超链接、链接目标、样式预设和标记搜索主题。 |
## 主题模式示例
### 基本主题
```json
{
"id": "task-1",
"title": "实现样式适配器",
"stylePreset": "task",
"markers": ["todo"]
}
```
### 带有 Web 链接的主题（通过 href）
```json
{
"id": "xmind-docs",
"title": "XMind 文档",
"href": "https://xmind.app/"
}
```
### 带有结构化链接的主题
```json
{
"id": "resource-npm",
"title": "npm 包",
"link": {
"type": "web",
"target": "https://www.npmjs.com/package/@lifeng688/xmind-mcp"
}
}
```
### 带有显式样式的主题
```json
{
"id": "risk-node",
"title": "高风险项",
"style": {
"textColor": "#991B1B",
"fillColor": "#FEE2E2",
"borderColor": "#DC2626",
"branchColor": "#DC2626",
"bold": true
}
}
```
### 带有标记的主题
```json
{
"id": "milestone",
"title": "发布 v0.2.0",
"markers": ["done", "star"],
"stylePreset": "success"
}
```
## 自然语言示例
您可以自然地与您的 AI 助手交流。以下是一些示例：
1. **项目规划**
> 为 xmind-mcp v0.2.0 创建项目路线图思维导图。使用 task、done、warning、blocked 和 important 样式。添加 npm 和 GitHub 链接到发布资源。
2. **Markdown 转换**
> 将此 Markdown 大纲转换为 XMind 思维导图。保留 Markdown 链接为真实主题链接。
3. **添加资源**
> 在“资源”下添加一个新资源主题，链接到 https://xmind.app/，并将其样式设置为重要。
4. **风险分析**
> 创建风险分析思维导图。使用 warning 表示普通风险，danger 表示严重风险，success 表示缓解措施，info 表示背景备注。
## v0.2.0 新增功能
- **视觉元数据支持** - 主题现在可以通过 `style` 字段具有颜色、粗体文本、字体大小和边框。
- **样式预设支持** - 九种语义预设（`important`、`success`、`warning`、`danger`、`info`、`idea`、`task`、`done`、`blocked`），解析为一致的配色方案和可选标记。
- **结构化主题链接** - `link: { type, target }` 用于 Web、文件、文件夹和主题引用。
- **原生超链接支持** - 简单的 `href: "https://..."` 用于 Web URL，优于旧的 `hyperlink` 字段。
- **标记扩展** - 支持 XMind 原生标记以外的语义标记（`important`、`flag`、`check`、`progress`、`blocked`、`warning`、`risk`），通过自定义元数据持久化以实现往返保真度。
- **Markdown 链接解析** - `### [Title](url)` 标题和 `- [Title](url)` 列表项解析为带有 Web 链接的主题。
- **Markdown 导出保留链接** - Web 链接导出为 `[title](url)`，其他链接类型导出为 `Link: type:url`。
- **改进的工具描述** - 所有 MCP 工具描述现在都指导 LLMs 使用视觉增强功能创建更丰富的思维导图。
## 测试
该项目使用 MCP JSON 测试运行器验证核心功能：
```bash
node run-mcp-json-test.mjs ./tests/xmind/v0.2/01-style-color.json
node run-mcp-json-test.mjs ./tests/xmind/v0.2/02-hyperlink.json
node run-mcp-json-test.mjs ./tests/xmind/v0.2/03-markers-priority.json
node run-mcp-json-test.mjs ./tests/xmind/v0.2/04-topic-link-support.json
node run-mcp-json-test.mjs ./tests/xmind/v0.2/05-style-preset.json
node run-mcp-json-test.mjs ./tests/xmind/v0.2/06-markdown-link-parsing.json
node run-mcp-json-test.mjs ./tests/xmind/v0.2/06-markdown-link-parsing.json
```
测试覆盖率：
- `01-style-color.json` - 样式预设和原始样式的往返
- `02-hyperlink.json` - href/hyperlink 在所有嵌套级别的读取/写入
- `03-markers-priority.json` - 具有完整往返保真度的语义标记
- `04-topic-link-support.json` - Web/文件/文件夹/主题链接支持
- `05-style-preset.json` - 样式预设解析、标记、更新/覆盖
- `06-markdown-link-parsing.json` - Markdown 链接解析和导出
## 安全
- **路径防护** - 所有文件路径都通过 `resolveWorkspacePath()` 解析，该函数防止目录遍历（`../`）攻击。文件必须位于配置的工作区目录内。
- **自动备份** - 在任何修改操作（添加/更新/删除）之前，原始文件会备份到 `workspaceDir/.backup/`，并带有时间戳。
- **审计日志** - 每个工具调用（成功或失败）都会记录为 `logs/audit.log` 中的 JSON 行。
- **主题上限** - 可配置的每个文件最大主题数（默认：500）。
- **工作区限制** - 始终将 `XMIND_WORKSPACE_DIR` 设置为专用目录。不要将其指向系统根目录或敏感目录。
- **本地链接由用户控制** - `file:` 和 `folder:` 链接类型引用本地路径。请谨慎使用，并仅与受信任的输入一起使用。
## 限制
1. **仅支持现代格式** - 支持带有 `content.json` 的 ZIP 基础 `.xmind` 文件。旧 XMind 8 文件（`content.xml`）返回明确的错误。
2. **单个工作表** - 对 `.xmind` 文件的第一个工作表进行操作。
3. **完整文件重写** - 编辑操作读取完整树，在内存中修改，然后重新生成整个 `.xmind` 文件。
4. **无 XMind 主题或布局** - 关注主题树结构，不关注视觉布局。
5. **无图像或附件** - 不支持这些。
## 许可证
MIT
## 路线图
参见 [docs/roadmap.md](docs/roadmap.md) 以获取计划的功能和里程碑。
