lakeboard-converter

Lee mapas mentales XMind (.xmind) y Yuque Lakeboard (.lakeboard) desde archivos locales como Markdown, un árbol de temas JSON o un esquema. Todas las hojas, notas, etiquetas y enlaces. Local, de solo lectura, stdio vía npx.

GitHub

Documentación

lakeboard-converter — Mind maps to Markdown your agents can read.

Convierte mapas mentales de Yuque Lakeboard (.lakeboard) y XMind (.xmind) a Markdown o un nuevo .xmind. Se presenta como CLI, TUI guiada, servidor MCP e interfaz web de arrastrar y soltar (convert.ledring.dev). English | 简体中文

Inicio rápido

Abre convert.ledring.dev para convertir un archivo en tu navegador.

O usa la CLI sin instalarla globalmente (requiere Node 20.12+):

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

Lee Markdown a la salida estándar sin escribir archivos:

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

Inicia el servidor MCP de solo lectura:

npx -y lakeboard-converter mcp

Desarrollo

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

Uso

Modo	Comando
TUI guiada	`npm run dev`
CLI	`npm run convert -- <file> --format md\|xmind\|both [--markdown-style generic\|xmind] [--out-dir DIR] [--output FILE] [--overwrite]`
Interfaz web	`npm run dev:web` (compilación de producción: `npm run build:web`)
Biblioteca (desde el código fuente)	`import { convertBuffer, convertFile } from './src/index.js'`

Los archivos de salida existentes nunca se sobrescriben a menos que pases --overwrite.

Interfaz web

Demo en vivo: https://convert.ledring.dev

La interfaz web se ejecuta completamente en tu navegador: los archivos nunca salen de tu máquina. Está autoalojada sin solicitudes de terceros, incluidas las fuentes. Ejecuta npm run dev:web localmente, o prueba las muestras incluidas de Lakeboard y XMind.

Despliegue (Cloudflare Workers)

Con CLOUDFLARE_API_TOKEN y CLOUDFLARE_ACCOUNT_ID configurados en tu entorno:

npm ci && npm run deploy:web

wrangler.jsonc sirve dist-web/ como activos estáticos con respaldo de aplicación de una sola página.

Para desplegar una compilación de vista previa en lakeboard-convert-preview.<subdomain>.workers.dev en su lugar (no tiene dominio personalizado), ejecuta npm run build:web && npx wrangler@3 deploy --env preview.

Para agentes (MCP y `--json`)

Los agentes obtienen una herramienta de solo lectura, convert(path, format, sheet?, maxNodes?, maxDepth?), donde format es md, json (árbol de temas) o outline (texto indentado compacto). Requiere Node 20.12+.

Inicia el servidor 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 o ~/.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"]

Lee un archivo desde la CLI, o instala la CLI globalmente:

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

Desde el código fuente

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

Cada resultado JSON de lectura de la CLI tiene schemaVersion: 1, source, format, nodeCount, maxDepth y content. Los errores con --json imprimen {"error": "..."} y salen con código 1. Consulta AGENTS.md para colaboradores.

Salida y límites en 0.4.0

Todas las hojas de XMind están incluidas. Un documento de Lakeboard tiene una hoja nombrada según su raíz. Las hojas de XMind sin título usan Sheet N. Con varias hojas, el Markdown genérico usa # <sheet title> seguido de ## <root title> y la lista de temas. Una sola hoja mantiene # <root title>. Los elementos de lista de primer nivel comienzan en la columna 0; los elementos más profundos usan dos espacios adicionales. Las notas se alinean con la columna de contenido del elemento. Los temas vinculados usan [Title](url) directamente, incluidos los encabezados, con corchetes en los títulos escapados. Las etiquetas de Markdown genérico siguen al título como tramos de código, como - Split vendor chunk `P1` `tech-debt` . Outlines use - Título [P1, tech-debt] y un encabezado de hoja antes de cada esquema cuando hay varias hojas.

El Markdown importado de XMind usa una lista raíz por hoja separada por una línea en blanco, sin encabezados. Omite etiquetas para que no se conviertan en parte de los títulos de temas importados.

Ambos comandos de la CLI aceptan --sheet <index|name> (índice basado en 1 o título exacto sin distinguir mayúsculas). MCP acepta sheet como cadena o entero. La selección se registra en selectedSheet; las selecciones desconocidas listan las hojas disponibles.

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) y CLI read / MCP por defecto a maxNodes: 2000; los valores válidos son enteros de 1 a 50000. El maxDepth opcional es un entero no negativo. La raíz es profundidad 0, por lo que una raíz con hijos solo tiene maxDepth: 1. Los límites podan temas en orden previo entre hojas. truncated y warnings informan temas omitidos. Aumenta los límites o selecciona una hoja para leer más. La conversión de archivos no tiene límite de tamaño. La lectura de CLI sin --json y el texto de MCP agregan advertencias como > Note: ....

Usa rutas absolutas para MCP: las rutas relativas se resuelven contra el directorio de trabajo del servidor, que puede diferir del de tu terminal. La lectura de CLI y MCP expanden ~ o ~/ iniciales usando el directorio de inicio. Las rutas relativas faltantes informan la ruta resuelta y el directorio de trabajo del servidor.

Formato JSON y resultados de MCP

CLI read --json mantiene schemaVersion: 1 y los campos existentes, agregando sheets: [{ index, title, nodeCount, maxDepth }], selectedSheet: { index, title } opcional, truncated y warnings. Los conteos describen la entrada seleccionada antes del truncamiento; maxDepth siempre cuenta la raíz como profundidad 0.

Para format: "json", content es un árbol de temas para una hoja. A partir de 0.4.0, varias hojas producen { sheets: [{ index, title, root: AgentTopic }] }. Los límites se aplican a estos árboles así como a Markdown y esquemas.

MCP devuelve un bloque de texto plano que contiene Markdown, texto de esquema o árboles JSON con formato bonito. También devuelve structuredContent con { schemaVersion, file, source, format, nodeCount, maxDepth, sheets, selectedSheet?, truncated, warnings }, validado contra el outputSchema registrado de la herramienta. El texto ya no es un sobre de resultados serializado como JSON. Las advertencias se agregan como una línea final de > Note: .... Los errores usan isError: true con un mensaje claro; la herramienta permanece de solo lectura.

Cursor CLI en modo sin cabeza (cursor-agent -p) necesita --force (más --approve-mcps) o la llamada a la herramienta es rechazada.

Cómo funciona

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

La costura es convertBuffer / convertFile en src/index.ts. Cada formato de entrada se analiza en un MindMapDocument, por lo que un nuevo formato necesita un analizador y ningún cambio de renderizador. La CLI y la TUI usan esa costura. La interfaz web usa su convertidor de navegador con asignación de ID de respaldo compartida; los agentes usan readMindMap en src/agent.ts, que nunca escribe archivos.

Mantiene texto, jerarquía, orden, notas y enlaces. Todas las hojas de XMind se leen. Las etiquetas aparecen en línea en Markdown genérico y esquemas. Descarta estilo, color y diseño. XMind 8 (XML heredado) no es compatible.

Pruebas

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

Licencia

MIT