xmind-mcp-server: Instructions file for Codex

XMind MCP Server — 项目规则

本地 MCP Server：解析 / 编辑 / 写回 XMind（JSON 格式），把节点图片作为 ImageContent 直接交给多模态模型。不包含 OCR，也不要重新引入 OCR、 模型推理、GPU 检测或启动时 pip 安装。

常用命令

# 创建环境并安装（开发）
python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[dev]"   # Windows
# .venv/bin/python -m pip install -e ".[dev]"         # POSIX

# 跑测试（已有 .venv 时）
.venv/Scripts/python.exe -m pytest -q
# .venv/bin/python -m pytest -q

# 静态检查
.venv/Scripts/ruff.exe check src tests
# ruff check src tests

# 启动（stdio，给 MCP 客户端用）
xmind-mcp
xmind-mcp --info
xmind-mcp --toolset read

# 可选：用 XMind 官方 CLI 校验生成的结构（需要先登录）
xmind validate path/to/file.xmind

发布前至少跑：ruff check src tests 和 pytest -q。测试不允许联网、不允许依赖真实 XMind 安装。

目录地图

硬约定

1. 所有写操作走 XMindWriter。 不要直接重写 zip；save() 负责备份、 跨进程冲突检测、清理过期缩略图、原子替换。
2. 改完 raw_content 必须调用 xm.refresh_from_raw()。 节点树和 find_topic 的 ID 索引都由它重建；漏调用会让后续查询看到旧树。
3. 保存前不要绕过冲突检测。 覆盖原文件时若磁盘摘要与 xm.source_digest 不同，必须抛 FileChangedError，让调用方另存。
4. 工具要在五处登记： tool_schemas.py 的 build_tool_list()、TOOLSETS、 _READ_ONLY_TOOLS（只读工具）、_DESTRUCTIVE_TOOLS（会删/覆盖的工具）， 以及 tools.py 的 XMindTools._handlers。 test_every_listed_tool_has_handler 会抓漂移；工具总数变化时同步 test_server.py 和 README。
5. 路径参数一律以 _path 结尾。 _guard_paths 只校验这个后缀； 新工具如果叫 file / target 会绕过 allowed_roots。
6. 图片只走 types.ImageContent。 统一用 prepare_image() 缩放、转 JPEG、 控制体积；不要在工具里直接返回原始 base64。
7. 版本号两处同步： pyproject.toml 与 src/xmind_mcp/__init__.py。
8. 配置向后兼容： Config.load() 忽略不认识的字段，旧的 image_mode=ocr/both 归一化为 inline；不要因为旧配置报错。
9. 用户数据默认保留： 备份目录 ~/.xmind-mcp/backups/ 不随卸载删除； 删除/覆盖用户文件前先备份，并在返回文案里说明。
10. 对外文案用中文，标识符用英文。 工具描述要告诉模型“什么时候用、 参数收什么”，不要写营销句。