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 提供強大的開發環境。
• 感謝所有為改進本項目做出貢獻的開發者。