Xmindmcp

🚀 🧠 XMind AI MCP – インテリジェントなマインドマッピングツールキット

このツールキットは、複数のフォーマットをXMindに変換し、AIによる分析機能を備え、UVXでデプロイされるMCPサーバーを搭載しています。

📜 変更履歴

• 1.3.1: analyze_mind_map の新しい読み取り構造（data.structure がない）との互換性を修正。

✨ 主な機能

1. 汎用ファイルコンバーター

• 多フォーマット変換: Markdown、Text、HTML、Word、Excel → XMind
• スマート検出: ファイルタイプと構造を自動検出
• バッチ処理: 複数のファイルを一度に変換
• 柔軟な出力: 出力パスと名前をカスタマイズ可能

2. MCPサーバー (UVX)

• UVXのみのデプロイ: 直接の python または pip を使用しない
• IDE統合: TraeとMCPツールとシームレスに連携
• FastMCPとSTDIOモードをサポート

3. AIによる分析

• 構造分析: マインドマップの構造を最適化
• トピック提案: AIによる推奨事項を生成
• 品質指標: 包括的な評価と検証

📁 プロジェクト構造

XmindMcp/
├── configs/                      # MCPサーバーの設定
├── docs/                         # ドキュメントとガイド
├── examples/                     # サンプル入力
├── output/                       # 生成されたXMindファイル
├── tests/                        # テストスイート
├── universal_xmind_converter.py  # スタンドアロンコンバーターCLI
├── 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([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

ローカル開発 (リポジトリのルートで)

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": []
    }
  }
}

📦 スタンドアロン変換 (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"
  # output_filepathを省略すると、サーバーのデフォルトの絶対出力ディレクトリを使用します (設定されている場合)
})

マインドマップを作成する (設定のdefault_output_dirを使用)

create_mind_map({
  "title": "Project Plan",
  "topics_json": [{"title": "Milestone 1"}, {"title": "Milestone 2"}]
  # デフォルトの絶対出力ディレクトリが設定されている場合は、output_pathを渡さないでください
})

既存のマップを分析する

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

⚙️ パスと設定

• ドキュメントの例では、読みやすさのためにプロジェクト相対パスを使用しています。
• MCP出力ツールの場合は、MCP設定環境 (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)
• Text (.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
• このプロジェクトの改善に貢献してくれたすべてのコントリビューター