# xmind-mcp

**让 AI Agent 直接生成、读取、转换、校验并渲染 `.xmind` 思维导图的 MCP 服务器 + CLI。**

生成的文件与 Xmind 官方客户端完全兼容(基于官方模板实测的 vana JSON 格式),PNG/SVG 渲染以图像内容直接回显在对话里。

![demo](sample/demo.png)

## 功能一览

| 能力 | MCP 工具 | CLI |
| --- | --- | --- |
| 从 Markdown 大纲生成 .xmind(可选 23 种布局) | `create_xmind` | `xmind-mcp create a.md out.xmind --structure <class>` |
| 读取导图为大纲(含旧版 content.xml) | `read_xmind` | `xmind-mcp read file.xmind` |
| 渲染 PNG/SVG(PNG 直接回显对话;五向布局) | `render_mindmap` | `xmind-mcp render file.xmind -o out.png` |
| **交互式 HTML 查看器**(缩放/平移/折叠/备注/导出) | `render_mindmap --format html` | `xmind-mcp render file.xmind -o out.html --format html` |
| 调起官方客户端原生渲染(全布局) | `open_in_xmind` | 双击 / `start file.xmind` |
| `.xmind ↔ Markdown ↔ OPML ↔ FreeMind` 互转 | `convert_xmind` | `xmind-mcp convert in.xmind out.md` |
| 文件统计(主题数/深度/布局) | `xmind_info` | `xmind-mcp info file.xmind` |
| 结构校验(空标题/超深/损坏) | `validate_xmind` | `xmind-mcp validate file.xmind` |

### 布局支持(23 种全量枚举,源自官方布局选择器)

| 布局 | structureClass | PNG 预览 | 官方客户端 |
| --- | --- | --- | --- |
| 逻辑图(右/左) | `logic.right` / `logic.left` | ✓ | ✓ |
| 平衡图 | `map.clockwise` / `map.anticlockwise` / `map.unbalanced` | ✓ | ✓ |
| 组织图(下/上) | `org-chart.down` / `org-chart.up` | ✓(肘形连线) | ✓ |
| 树形图(左/右/分支对齐) | `tree.*` | 近似预览(逻辑图引擎) | ✓ |
| 鱼骨图(左头/右头) | `fishbone.leftHeaded` / `rightHeaded` | 回落预览 | ✓ 原生渲染 |
| 括号图(左/右) | `brace.left` / `brace.right` | 回落预览 | ✓ 原生渲染 |
| 时间线 ×4 | `timeline.vertical/horizontal/sided.horizontal/through.vertical` | 回落预览 | ✓ 原生渲染 |
| 树状表 ×2 / 电子表格 ×2 | `treetable*` / `spreadsheet*` | 回落预览 | ✓ 原生渲染 |

回落策略:文件仍写入真实布局声明(官方客户端原生渲染),PNG 预览回落并注明,可调 `open_in_xmind` 看原版。RTL/BTT 书写方向变体由客户端自动应用,不参与生成。

## 快速开始

### 安装(Node ≥ 20)

```bash
git clone https://github.com/1parado/xmind_mcp.git
cd xmind_mcp
npm install        # prepare 钩子自动执行 tsc 构建 dist/
npm test           # 24 项测试
node test/smoke_mcp.mjs   # stdio 握手冒烟测试
```

不克隆仓库也可以直接用 npx 拉取运行:

```bash
npx github:1parado/xmind_mcp serve
```

### 接入 MCP 客户端(ZCode / Claude Desktop 等)

把 `<path>` 换成你的实际克隆路径(Windows 注意 JSON 转义 `\\`):

```json
{
  "mcpServers": {
    "xmind": {
      "command": "node",
      "args": ["<path>/xmind_mcp/dist/index.js", "serve"]
    }
  }
}
```

或者不克隆仓库,直接让客户端通过 npx 拉起(Windows 下若客户端不做 shell 包装,`command` 改用 `cmd`、`args` 前加 `/c`):

```json
{
  "mcpServers": {
    "xmind": {
      "command": "npx",
      "args": ["-y", "github:1parado/xmind_mcp", "serve"]
    }
  }
}
```

## Agent 使用示例

对话里直接说:

> 帮我做一张"Q4 产品发布"的导图:三个分支——市场、研发、运营,每个分支给三个要点,保存到 D:\docs\q4.xmind 并渲染给我看。

Agent 会依次调用:

1. `create_xmind({outline_markdown: "# Q4 产品发布\n- 市场\n  - ...", output_path: "D:/docs/q4.xmind"})`
2. `render_mindmap({file_path: "D:/docs/q4.xmind", format: "png"})` → 对话内直接显示 PNG

### Markdown 大纲语法

```markdown
# 中心主题            ← H1 为中心主题(唯一时)
- 分支 A              ← 无序/有序列表按缩进嵌套
  > 备注内容           ← 紧跟的引用块成为该主题备注
  - 子主题 A1
    - 更深层
- 分支 B
```

规则:`#`~`######` 标题定层级;``` 围栏内内容跳过;`**加粗**`/`*斜体*`/`` `代码` ``/`~~删除线~~` 行内标记与 `- [ ]` 复选框前缀自动剥离;多个顶层节点时自动合成中心主题。

## 环境变量

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `XMIND_MCP_ROOT` | 进程 cwd | MCP 文件访问沙箱根目录 |
| `XMIND_MCP_ALLOW_ANY_PATH` | 未设置 | 设为 `1` 放开沙箱(自担风险) |
| `XMIND_OFFICIAL_TEMPLATES` | 未设置 | 指向官方模板目录时启用语料测试 |