Lakeboard Converter

Yuque Lakeboard（.lakeboard）と XMind（.xmind）のマインドマップを Markdown または新しい .xmind に変換します。 CLI、ガイド付き TUI、MCP サーバー、ドラッグ＆ドロップ対応の Web UI（convert.ledring.dev）として利用できます。英語 | 简体中文

クイックスタート

convert.ledring.dev を開くと、ブラウザーでファイルを変換できます。

または、グローバルにインストールせずに CLI を使用できます（Node 20.12+ が必要です）。

npx -y lakeboard-converter convert ./map.xmind --format md --out-dir ./out

ファイルを書き込まずに Markdown を標準出力へ出力します。

npx -y lakeboard-converter read ./map.xmind --format md

MCP サーバーを起動します。

npx -y lakeboard-converter mcp

開発

git clone https://github.com/FelixFangX/lakeboard-converter.git
cd lakeboard-converter && npm ci
npm run convert -- ./test-fixtures/test.lakeboard --format md --out-dir ./out

使い方

モード	コマンド
ガイド付き TUI	npm run dev
CLI	npm run convert -- <file> --format md|xmind|both [--markdown-style generic|xmind] [--out-dir DIR] [--output FILE] [--overwrite]
Web UI	npm run dev:web（本番ビルド：npm run build:web）
ライブラリ（ソースから）	import { convertBuffer, convertFile } from './src/index.js'

--overwrite を指定しない限り、既存の出力ファイルは上書きされません。

Web UI

ライブデモ：https://convert.ledring.dev

Web UI はすべてブラウザー内で動作し、ファイルが端末の外部に送信されることはありません。フォントを含むサードパーティへのリクエストなしでセルフホストされています。ローカルで npm run dev:web を実行するか、同梱の Lakeboard と XMind のサンプルをお試しください。

デプロイ（Cloudflare Workers）

環境に CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID を設定した状態で、次を実行します。

npm ci && npm run deploy:web

wrangler.jsonc は dist-web/ を静的アセットとして配信し、シングルページアプリケーションのフォールバックを設定します。

代わりに、プレビュー用ビルドを lakeboard-convert-preview.<subdomain>.workers.dev にデプロイする場合（カスタムドメインはありません）、npm run build:web && npx wrangler@3 deploy --env preview を実行します。

エージェント向け（MCP と --json）

Node 20.12+ が必要です。MCP サーバーは 4 つのツールを提供します。

• convert(path, format?, sheet?, maxNodes?, maxDepth?)：1 つのマインドマップを md（デフォルト）、json（トピックツリー）、または outline（簡潔なインデント付きテキスト）として読み込みます。
• from_markdown(markdown, output?, overwrite?, title?, maxNodes?)：Markdown のアウトラインから XMind ファイルを作成します。
• convert_many(paths, format?, sheet?, maxNodes?, maxTotalNodes?, maxDepth?)：複数のマインドマップを、共通のノード数上限で読み込みます。
• inspect(path, sheet?)：内容を含めずにファイルサイズとトピック数を返します。

convert、convert_many、inspect は読み取り専用です。from_markdown は、指定した出力パスにのみ書き込みます。

MCP サーバーを起動します。

npx -y lakeboard-converter mcp

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "lakeboard-converter": {
      "command": "npx",
      "args": ["-y", "lakeboard-converter", "mcp"]
    }
  }
}

Cursor（.cursor/mcp.json または ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "lakeboard-converter": {
      "command": "npx",
      "args": ["-y", "lakeboard-converter", "mcp"]
    }
  }
}

Codex CLI（~/.codex/config.toml）：

[mcp_servers.lakeboard-converter]
command = "npx"
args = ["-y", "lakeboard-converter", "mcp"]

CLI からファイルを読み込むか、CLI をグローバルにインストールします。

npx -y lakeboard-converter read ./map.xmind --format md
npm i -g lakeboard-converter

Markdown から XMind へ

from_markdown は見出し、入れ子のリスト、番号付きリスト、リンク、末尾の code ラベル、> notes を受け付けます。複数のシートを使用する場合は、# Sheet／## Root セクションを繰り返します。各シート見出しには、ルート見出しをちょうど 1 つ含めてください。最初の見出しまたはリスト項目より前のテキストは、警告とともに無視されます。

ファイルを書き込むには、既存のフォルダー内にある絶対パスの .xmind 出力パスを渡します。フォルダーは作成されず、既存のファイルを上書きするには overwrite: true が必要です。output を指定しない場合、ツールは structuredContent.base64 にファイルを返します。Markdown 入力の上限は 2 MB（UTF-8）です。maxNodes のデフォルトは 2000（1～50000）です。省略されたトピックは truncated と warnings で報告されます。

CLI の build には -o が必要です。指定されたパスは絶対パスに解決され、置き換えを許可するには --overwrite を使用します。

npx -y lakeboard-converter build plan.md -o plan.xmind

バッチとサイズのチェック

convert_many は1～50個の絶対パスを受け付けます。maxNodes はファイルごとに適用され、maxTotalNodes はバッチ全体に適用され、デフォルトは10000（1～200000）です。テキストには変換された内容が含まれ、structuredContent には content を含まないファイルごとのメタデータとエラーが含まれます。ファイルごとのエラーによって MCP 呼び出しが失敗することはありません。CLI の複数ファイル read もファイルごとの結果とエラーを返し、いずれかのファイルで失敗すると終了コード1で終了します。合計の上限を変更するには --max-total-nodes を使用します。

inspect は、内容を含めずにバイト数、ノード数、深さ、シートのメタデータを返します。

npx -y lakeboard-converter read a.xmind b.lakeboard --json
npx -y lakeboard-converter inspect a.xmind --json

ソースから

npm run build
node /abs/path/lakeboard-converter/dist/cli.js mcp
node dist/cli.js read ./test-fixtures/test.lakeboard --format json --json
node dist/cli.js convert ./test-fixtures/test.xmind -f md --out-dir out --json

単一ファイルの CLI 読み取り結果の JSON には、常に schemaVersion: 1、source、format、nodeCount、maxDepth、content が含まれます。--json を指定した場合、エラーは {"error": "..."} を出力し、終了コード1で終了します。コントリビューター向けの情報は AGENTS.md を参照してください。

出力と制限

すべての XMind シートが含まれます。Lakeboard ドキュメントには、ルートにちなんだ名前のシートが1つあります。タイトルのない XMind シートには Sheet N という名前が付けられます。複数のシートがある場合、汎用 Markdown では # <sheet title> の後に ## <root title> とトピックのリストが続きます。シートが1つの場合は # <root title> のままです。第1階層のリスト項目は列0から始まり、それより深い階層の項目は2つずつスペースを増やします。ノートは項目の内容と同じ列に配置されます。リンク付きトピックは、見出しを含めて [Title](url) の形式で直接表記され、タイトル内の角括弧はエスケープされます。汎用 Markdown のラベルは、- Split vendor chunk `P1` `tech-debt` のように、タイトルの後にコードスパンで続きます。アウトラインは - Title [P1, tech-debt] の形式で、複数のシートがある場合は各アウトラインの前にシート見出しが付きます。

XMind インポート用 Markdown では、見出しを使わず、各シートにつきルートのリストを1つ出力し、シート間には空行を挟みます。ラベルは省略されるため、インポート後のトピックタイトルに含まれることはありません。

CLI の read、convert、inspect は --sheet <index|name>（1始まりのインデックス、または大文字と小文字を区別しない完全一致のタイトル）を受け付けます。MCP は sheet を文字列または整数として受け付けます。選択内容は selectedSheet に記録され、該当しない選択が指定された場合は利用可能なシートが一覧表示されます。

lakeboard-converter read /absolute/path/map.xmind --sheet Roadmap --max-nodes 5000 --max-depth 3 --json
lakeboard-converter convert ./map.xmind --sheet 2 --format md

readMindMap(file, format, options) と CLI の read／MCP のデフォルトの maxNodes は2000です。有効な値は1～50000の整数です。maxDepth は省略可能で、0以上の整数を指定します。ルートの深さは0なので、子を持つルートの maxDepth は1になります。制限により、シート全体を先行順でトピックが除外されます。省略されたトピックは truncated と warnings で報告されます。より多くの内容を読むには、制限を増やすかシートを選択してください。ファイル変換にサイズ制限はありません。--json を指定しない CLI の read と MCP のテキスト出力では、警告が > Note: ... として追加されます。

MCP では絶対パスを使用してください。convert の相対パスはサーバーの作業ディレクトリを基準に解決されます。このディレクトリは、ターミナルの作業ディレクトリと異なる場合があります。CLI の read と MCP の convert は、先頭の ~ または ~/（Windows では ~\ も）をホームディレクトリに展開します。相対パスが見つからない場合は、解決後のパスとサーバーの作業ディレクトリが報告されます。

単一ファイルの読み取り JSON と MCP convert の結果

CLI の read --json は schemaVersion: 1 と既存のフィールドを維持し、sheets: [{ index, title, nodeCount, maxDepth }]、省略可能な selectedSheet: { index, title }、truncated、warnings を追加します。件数は、切り捨て前の選択対象の入力内容を表します。maxDepth は常にルートを深さ0として数えます。

format: "json" の場合、content は1つのシートのトピックツリーです。0.4.0以降、複数のシートは { sheets: [{ index, title, root: AgentTopic }] } を生成します。制限は Markdown やアウトラインだけでなく、これらのツリーにも適用されます。

MCP の convert は、Markdown、アウトラインテキスト、または整形済み JSON ツリーを含むプレーンテキストブロックを1つ返します。また、ツールに登録された outputSchema に照らして検証される { schemaVersion, file, source, format, nodeCount, maxDepth, sheets, selectedSheet?, truncated, warnings } を含む structuredContent も返します。テキストは、JSON 文字列化された結果のラッパーではなくなりました。警告は最後の > Note: ... 行として追加されます。エラーの場合は、明確なメッセージとともに isError: true が返されます。このツールは引き続き読み取り専用です。

ヘッドレスモードの Cursor CLI（cursor-agent -p）では --force（および --approve-mcps）が必要です。指定しない場合、ツール呼び出しは拒否されます。

仕組み

.lakeboard ─┐                          ┌─ renderGenericMarkdown → # root + nested list
            ├─ parse → MindMapDocument ─┼─ renderXmindMarkdown  → root list per sheet for XMind import
.xmind ─────┘     (TopicNode tree)      └─ renderXmind          → minimal .xmind package

境界は src/index.ts の convertBuffer / convertFile です。すべての入力形式は 1 つの MindMapDocument に解析されるため、新しい形式の追加に必要なのはパーサー 1 つだけで、レンダラーの変更は不要です。CLI と TUI はこの境界を使用します。Web UI は、フォールバック ID の割り当てを共有するブラウザーコンバーターを使用します。エージェントは src/index.ts からエクスポートされる src/agent.ts の readMindMap、readMindMaps、inspectMindMap、buildMindMap を使用します。明示的な出力パスが指定された場合に書き込みを行うのは buildMindMap だけです。

テキスト、階層、順序、メモ、リンクを保持します。すべての XMind シートを読み込みます。ラベルは汎用 Markdown とアウトラインにインラインで表示されます。スタイル、色、レイアウトは保持されません。XMind 8（レガシー XML）はサポートされていません。

テスト

npm test            # vitest specs at the convert, readMindMap and MCP seams, using test-fixtures/
npm run typecheck

ライセンス

MIT