Xmindmcp

🚀 XMind AI MCP – 智能思维导图工具包

XMind AI MCP 是一个强大的工具包，可将多种格式的文件转换为 XMind 格式，具备 AI 分析功能，并且拥有基于 UVX 部署的 MCP 服务器，为思维导图的创建和处理带来极大便利。

🔄 变更日志

• 1.3.1 版本：修复 analyze_mind_map 与新读取结构（无 data.structure）的兼容性问题。

✨ 主要特性

1. 通用文件转换器

• 多格式转换：支持将 Markdown、文本、HTML、Word、Excel 等格式转换为 XMind 格式。
• 智能检测：自动检测文件类型和结构。
• 批量处理：可同时转换多个文件。
• 灵活输出：可自定义输出路径和文件名。

2. MCP 服务器（UVX）

• 仅支持 UVX 部署：不支持直接使用 python 或 pip。
• 集成开发环境（IDE）集成：可与 Trae 和 MCP 工具无缝协作。
• 支持 FastMCP 和 STDIO 模式。

3. 人工智能驱动分析

• 结构分析：优化思维导图结构。
• 主题建议：由 AI 生成推荐主题。
• 质量评估：进行全面评估和验证。

📁 项目结构

XmindMcp/
├── configs/                      # MCP 服务器配置
├── docs/                         # 文档和指南
├── examples/                     # 示例输入
├── output/                       # 生成的 XMind 文件
├── tests/                        # 测试套件
├── universal_xmind_converter.py  # 独立转换器命令行界面
├── xmind_core_engine.py          # 核心引擎
├── xmind_mcp_server.py           # MCP 服务器（FastMCP / STDIO）
├── xmind_mcp/                    # 包入口（`xmind-mcp`）
│   ├── __init__.py
│   └── __main__.py
└── configs/mcp_config.json       # MCP 服务器配置（仅环境配置）

🔄 架构概述

graph TD
    User([用户]) -->|命令行界面| Converter[universal_xmind_converter.py]
    User -->|MCP| MCP[xmind_mcp_server.py]
    User -->|测试| TestRunner[tests/run_all_tests.py]

    MCP -->|工具| Core[xmind_core_engine.py]
    Core -->|转换| Converter
    Core -->|验证| Validator[validate_xmind_structure.py]
    Core -->|AI| AIExt[xmind_ai_extensions.py]

    Converter -->|读取| Examples[examples/]
    Converter -->|写入| Output[output/]

    classDef userLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef serverLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef engineLayer fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef fileLayer fill:#fce4ec,stroke:#880e4f,stroke-width:2px

    class User,TestRunner userLayer
    class MCP serverLayer
    class Core,AIExt engineLayer
    class Examples,Output fileLayer

🚀 快速开始（UVX）

安装 UV（如果尚未安装）

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

运行（已发布的包）

uvx xmind-mcp --mode fastmcp
uvx xmind-mcp --version
uvx xmind-mcp --help

本地开发（在仓库根目录）

uvx --from . xmind-mcp --mode fastmcp
# 备用（STDIO）
uvx xmind-mcp --stdio

💻 Trae MCP 集成（UVX）

标准配置（推荐）

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "uvx",
      "args": ["xmind-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "XMind MCP - UVX 已安装",
      "disabled": false,
      "autoApprove": []
    }
  }
}

本地开发配置（无绝对路径）

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "uvx",
      "args": ["--from", ".", "xmind-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "XMind MCP - 本地开发",
      "disabled": false,
      "autoApprove": []
    }
  }
}

📦 独立转换（命令行界面）

单文件转换

python universal_xmind_converter.py examples/test_markdown.md
python universal_xmind_converter.py examples/test_document.docx --output output/my_mind_map.xmind

批量转换

python universal_xmind_converter.py examples/ --batch
python universal_xmind_converter.py examples/ --batch --format markdown,html,txt

🛠️ 可用的 MCP 工具

• read_xmind_file(file_path) – 读取 XMind 文件内容
• create_mind_map(title, topics_json, output_path?) – 创建新的思维导图
• analyze_mind_map(file_path) – 分析思维导图的结构和指标
• convert_to_xmind(source_filepath, output_filepath?) – 将文件转换为 XMind 格式
• list_xmind_files(directory?, recursive?) – 列出 XMind 文件
• translate_xmind_titles(source_filepath, output_filepath?, target_lang?, overwrite?)

💻 使用示例（Trae MCP）

转换 Markdown 文件

convert_to_xmind({
  "source_filepath": "examples/test_markdown.md"
  # 省略 output_filepath 以使用服务器的默认绝对输出目录（如果已配置）
})

创建思维导图（使用配置中的默认输出目录）

create_mind_map({
  "title": "项目计划",
  "topics_json": [{"title": "里程碑 1"}, {"title": "里程碑 2"}]
  # 如果已配置默认绝对输出目录，则不传递 output_path
})

分析现有思维导图

analyze_mind_map({
  "file_path": "output/test_markdown.xmind"
})

⚙️ 路径与配置

• 文档中的示例使用项目相对路径以提高可读性。
• 对于 MCP 输出工具，可通过 MCP 配置环境（configs/mcp_config.json）或命令行参数 --default-output-dir 配置默认绝对输出目录。
• 如果未配置默认输出目录，则在工具调用中传递显式的绝对 output_path/output_filepath；MCP 输出工具不接受相对路径。

🧪 运行测试

python tests/run_all_tests.py
python tests/run_all_tests.py --english
python tests/test_setup.py
python tests/test_core.py

📚 详细文档

• docs/TRAE_MCP_SETUP.md – IDE MCP 配置说明
• docs/UNIVERSAL_CONVERTER_USAGE.md – 独立转换器使用说明
• docs/xmind_ai_mcp_design.md – 架构和设计文档

🎨 支持的格式

• Markdown（.md, .markdown）
• 文本（.txt, .text）
• HTML（.html, .htm）
• Word（.docx）
• Excel（.xlsx）
• CSV（.csv）
• JSON（.json）
• XML（.xml）
• YAML（.yaml, .yml）

🤝 贡献代码

• 分叉（Fork）仓库
• 创建功能分支（git checkout -b feature/your-feature）
• 提交更改（git commit -m "feat: add your feature"）
• 推送分支（git push origin feature/your-feature）
• 打开拉取请求（Pull Request）

🔍 验证与质量

• 已验证 9 种文件格式的转换功能。
• 保持结构完整性。
• 保留内容的准确性。
• 确保符合 XMind 格式要求。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 XMind 团队提供出色的思维导图工具。
• 感谢 Trae IDE 提供强大的开发环境。
• 感谢所有为改进本项目做出贡献的开发者。