Xmind 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.人工智能驱动的分析

• 结构分析：优化思维导图结构
• 主题建议：人工智能生成的建议
• 质量指标：综合评估和验证

📁 项目结构

XmindMcp/
├── configs/                      # MCP server config
├── docs/                         # Documentation and guides
├── examples/                     # Sample inputs
├── output/                       # Generated XMind files
├── tests/                        # Test suite
├── universal_xmind_converter.py  # Standalone converter CLI
├── xmind_core_engine.py          # Core engine
├── xmind_mcp_server.py           # MCP server (FastMCP / STDIO)
├── xmind_mcp/                    # Package entry (`xmind-mcp`)
│   ├── __init__.py
│   └── __main__.py
└── configs/mcp_config.json       # MCP server configuration (env only)

🔄 架构概述

graph TD
    User([User]) -->|CLI| Converter[universal_xmind_converter.py]
    User -->|MCP| MCP[xmind_mcp_server.py]
    User -->|Tests| TestRunner[tests/run_all_tests.py]

    MCP -->|Tools| Core[xmind_core_engine.py]
    Core -->|Convert| Converter
    Core -->|Validate| Validator[validate_xmind_structure.py]
    Core -->|AI| AIExt[xmind_ai_extensions.py]

    Converter -->|Read| Examples[examples/]
    Converter -->|Write| 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

本地开发（以repo根目录）

uvx --from . xmind-mcp --mode fastmcp
# Fallback (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 installed",
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

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

📦 独立转换（CLI）

单个文件

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"
  # omit output_filepath to use the server's default absolute output directory (if configured)
})

创建思维导图（在配置中使用default_output_dir）

create_mind_map({
  "title": "Project Plan",
  "topics_json": [{"title": "Milestone 1"}, {"title": "Milestone 2"}]
  # do not pass output_path if a default absolute output directory is configured
})

分析现有地图

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

⚙️ 路径和配置

• 文档中的示例使用项目相对路径来提高可读性。
• 对于MCP输出工具，通过MCP config env配置默认的绝对输出目录(configs/mcp_config.json)或CLI --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)

🤝 贡献

• 分叉存储库
• 创建要素分支(git checkout -b feature/your-feature)
• 承诺(git commit -m "feat: add your feature")
• 推(git push origin feature/your-feature)
• 打开拉取请求

🔍 验证和质量

• 9种文件格式已验证可转换
• 保持结构完整性
• 内容保真度得以保留
• 确保符合XMind格式

📝 许可证

MIT许可证——见 LICENSE 了解详情。

🙏 致谢

• XMind团队提供优秀的思维导图工具
• Trae IDE用于强大的开发环境
• 所有帮助改进此项目的贡献者