内容
# mindnode-mcp
[](LICENSE)
[](https://www.python.org/)
**中文** | [日本語](README.ja.md)
一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 助手（例如 Claude）**直接读取和写入您的 MindNode 思维导图**，通过解析 `.mindnode` 文件格式本身。无需 AppleScript，无需快捷方式，无需导出/导入。
您可以要求您的助手 *"读取我的项目地图"*，*"将这三个想法添加到营销节点下"*，*"将 API 节点连接到 Auth 节点"*，或 *"将此大纲转换为新的思维导图"* — 它直接操作 MindNode 同步的文件。
> **为什么存在此项目：** MindNode 放弃了其 AppleScript 字典，其快捷方式/URL 方案自动化功能有限。但是，`.mindnode` 文档只是一个包，其 `contents.xml` 是一个 Apple **二进制 plist** — 一个干净的递归节点树。读取/写入它，您就可以获得完全的编程控制。
## 要求
- **macOS**，安装 [MindNode](https://mindnode.com) （格式版本 9 — 当前的 MindNode 版本）
- **Python 3.11+** 和 [uv](https://github.com/astral-sh/uv)
- 一个 MCP 客户端（例如 [Claude Code](https://claude.com/claude-code)）
## 安装
```bash
git clone https://github.com/masamitsu-konya/mindnode-mcp.git
cd mindnode-mcp
uv sync
```
在 Claude Code 中注册它（用户范围 = 在任何地方可用）：
```bash
claude mcp add --scope user mindnode -- uv --directory "$PWD" run mindnode-mcp
```
然后启动一个新的会话并运行 `/mcp`（或 `claude mcp list`）以确认它显示 **mindnode ✔ Connected**。
默认情况下，它会自动在 iCloud 容器中找到您的 MindNode 文档。您可以通过 `MINDNODE_DOCS_DIR` 环境变量将其指向其他位置（本地库或测试的固定文件夹）。
## 用法
用普通语言与您的助手交流 — 它会选择合适的工具。示例：
| 您说的话 | 会发生什么 |
|---------|--------------|
| "列出我的思维导图" | `list_documents` → 名称 + 日期，最新的在前 |
| "读取我的 *项目计划* 地图" | `read_document` → 完整的节点树为 JSON |
| "在我的所有地图中搜索 'pricing'" | `search_nodes` → 每个匹配的节点 + 其文档 |
| "在 *Roadmap* 中添加 '雇用设计师' 到团队节点下" | `add_node` |
| "连接 '前端' 到 'API'，标签为 '调用'" | `add_connection` |
| "将 '启动' 节点标记为 #urgent" | `add_tag`（如果新标签则创建） |
| "将 '交付 v1' 标记为完成" | `set_task` |
| "将 ~/Desktop/wireframe.png 附件到设计节点" | `attach_image` |
| "创建一个新的思维导图 'Q3 目标'，带有分支 销售、产品、招聘" | `create_map` |
节点可以通过其文本（不区分大小写的子字符串足够）或其确切 ID（ID 由 `read_document` 返回）来引用。
## 工具
| 工具 | 类型 | 它做什么 |
|------|------|--------------|
| `list_documents` | 读取 | 所有 `.mindnode` 文件，最新的在前 |
| `read_document` | 读取 | 思维导图为 `{id, text, note?, task?, tags?, attachment?, children?}` 树，加上 `connections` 和文档的标签列表 |
| `search_nodes` | 读取 | 节点文本 + 笔记中的子字符串搜索，在一个文档或所有文档中 |
| `add_node` | 写入 | 在父节点下（通过 ID 或文本）添加一个节点，带有可选的笔记 |
| `add_connection` | 写入 | 用可选的标签和箭头方向交叉链接两个现有节点 |
| `add_tag` / `remove_tag` | 写入 | 为节点添加/删除标签（标签是文档范围的，自动创建） |
| `set_task` | 写入 | 将节点转换为复选框任务并设置完成/待处理 |
| `attach_image` | 写入 | 将本地图像附件到节点（复制到包的 `resources/`） |
| `create_map` | 写入 | 从标题 + （可选的）大纲创建一个新的 `.mindnode` |
### 连接（交叉链接）
任意两个节点之间的自由链接，独立于父/子树（存储在 `canvas.crossConnections[]`）。`add_connection(document, start, end, label?, direction?)` — `direction` ∈ `forward`（默认）/ `backward` / `both` / `none`。
`read_document` 返回每个节点为 `{id, start_id, end_id, start_text, end_text, direction, label?}`。
### 标签、任务、附件
`read_document` 针对每个节点显示这些（并在顶部列出所有标签名称）：
- **标签** — 规范化：`canvas.tags[]` 定义 `{tagID, name, color}`，`node.tags[]` 引用 tagIDs。`add_tag` 自动定义一个具有该名称的标签（如果不存在），然后附加它（幂等）。
- **任务** — `node.task = {state, uuids}`，其中 `state` 1 = 待处理，2 = 已完成。`set_task(document, node, done)` 切换它。
- **附件（图像）** — `node.attachment = {fileName, size, tintKind, type}`；图像字节存储在 `resources/<fileName>`。`attach_image` 复制文件并链接它，将显示宽度限制为 300px（匹配 MindNode）。
## 工作原理
`.mindnode` 文档是一个 **包目录**。其 `contents.xml` — 尽管有扩展名 — 是一个 Apple **二进制 plist**，保存思维导图（格式 **版本 9**）：
```
canvas.mindMaps[].mainNode # 每个地图的根节点
├─ nodeID # UUID
├─ title.text # 节点的文本，存储为小型 HTML
├─ note / task / tags / attachment
└─ subnodes[] # 子节点（相同的形状，递归）
canvas.crossConnections[] # 节点之间的自由链接
canvas.tags[] # 标签定义
```
服务器使用 Python 标准 `plistlib` 读取和写入此文件，因此它不需要 **第三方 plist 库**。节点文本通过最小的 HTML 编码/解码（具有正确的转义）进行往返。
## 写安全性
这些工具会修改您的真实文件，因此每次写入：
- **备份** `contents.xml` 到时间戳 `.bak-*`，
- 写入临时文件，然后 **原子替换** 它（无部分写入），
- **保留它未修改的键** （样式、布局、打印信息），并且
- 删除过时的 QuickLook 预览，以便它重新生成。
`create_map` 克隆现有文档作为结构骨架（保留所有不透明的辅助文件有效），并仅覆盖节点树。
> **警告 — MindNode 中打开的文档。** 写入直接进入磁盘。如果 MindNode（或另一台设备通过 iCloud）打开相同的文档，则其下一个自动保存可能会覆盖更改，或者您可能会获得 iCloud 冲突副本。在编写前关闭 MindNode 中的文档，或在编辑后重新打开以获取更新。备份使其可恢复，但最好避免。
## 开发
```bash
uv run python tests/smoke.py
```
烟雾测试针对您的真实文档（只读）和所有写入操作针对临时副本 — 它永远不会修改您的实际地图。它还断言生成的结构（节点、连接、标签、任务、图像附件）与真实 MindNode 文件的模式匹配。
## 状态和路线图
- [x] 读取 — 列表 / 读取 / 搜索
- [x] 写入 — add_node / create_map
- [x] 连接 / 交叉链接 — 读取 + add_connection
- [x] 标签、任务、图像附件 — 读取 + 写入
- [ ] 非图像附件（链接、贴纸）
- [ ] 标签颜色调色板 / 重命名，任务删除
- [ ] 连接航点编辑
## 许可证
[MIT](LICENSE) © 2026 Masamitsu Konya
