lakeboard-converter

Leia mapas mentais XMind (.xmind) e Yuque Lakeboard (.lakeboard) de arquivos locais como Markdown, uma árvore de tópicos em JSON ou um esboço. Todas as folhas, notas, rótulos e links. Local, somente leitura, stdio via npx.

GitHub

Documentação

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

Converta mapas mentais Yuque Lakeboard (.lakeboard) e XMind (.xmind) em Markdown ou um novo .xmind. Disponível como CLI, TUI guiada, servidor MCP e interface web com arrastar e soltar (convert.ledring.dev). English | 简体中文

Início rápido

Abra convert.ledring.dev para converter um arquivo no seu navegador.

Ou use a CLI sem instalá-la globalmente (requer Node 20.12+):

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

Leia Markdown para a saída padrão sem gravar arquivos:

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

Inicie o servidor MCP somente leitura:

npx -y lakeboard-converter mcp

Desenvolvimento

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]`
Interface web	`npm run dev:web` (build de produção: `npm run build:web`)
Biblioteca (a partir do código-fonte)	`import { convertBuffer, convertFile } from './src/index.js'`

Arquivos de saída existentes nunca são sobrescritos, a menos que você passe --overwrite.

Interface web

Demonstração ao vivo: https://convert.ledring.dev

A interface web roda inteiramente no seu navegador: os arquivos nunca saem da sua máquina. Ela é auto-hospedada, sem requisições de terceiros, incluindo fontes. Execute npm run dev:web localmente ou experimente as amostras incluídas de Lakeboard e XMind.

Implantação (Cloudflare Workers)

Com CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_ID definidos no seu ambiente:

npm ci && npm run deploy:web

wrangler.jsonc serve dist-web/ como ativos estáticos com fallback de aplicação de página única.

Para implantar um build de pré-visualização em lakeboard-convert-preview.<subdomain>.workers.dev (que não tem domínio personalizado), execute npm run build:web && npx wrangler@3 deploy --env preview.

Para agentes (MCP e `--json`)

Os agentes recebem uma ferramenta somente leitura, convert(path, format, sheet?, maxNodes?, maxDepth?), onde format é md, json (árvore de tópicos) ou outline (texto indentado compacto). Requer Node 20.12+.

Inicie o 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 ou ~/.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"]

Leia um arquivo pela CLI ou instale a CLI globalmente:

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

A partir do código-fonte

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

Todo resultado JSON de leitura da CLI tem schemaVersion: 1, source, format, nodeCount, maxDepth e content. Erros com --json imprimem {"error": "..."} e saem com código 1. Veja AGENTS.md para contribuidores.

Saída e limites na versão 0.4.0

Todas as planilhas XMind são incluídas. Um documento Lakeboard tem uma planilha nomeada a partir da sua raiz. Planilhas XMind sem título usam Sheet N. Com várias planilhas, o Markdown genérico usa # <sheet title> seguido por ## <root title> e a lista de tópicos. Uma única planilha mantém # <root title>. Itens de lista de primeiro nível começam na coluna 0; itens mais profundos usam dois espaços adicionais. Notas se alinham com a coluna de conteúdo do item. Tópicos vinculados usam [Title](url) diretamente, incluindo cabeçalhos, com colchetes nos títulos escapados. Rótulos do Markdown genérico seguem o título como spans de código, como - Split vendor chunk `P1` `tech-debt` . Outlines use - Title [P1, tech-debt] e um cabeçalho de planilha antes de cada esboço quando há várias planilhas.

O Markdown de importação XMind usa uma lista raiz por planilha separada por uma linha em branco, sem cabeçalhos. Ele omite rótulos para que não se tornem parte dos títulos de tópicos importados.

Ambos os comandos da CLI aceitam --sheet <index|name> (índice baseado em 1 ou título exato sem diferenciar maiúsculas/minúsculas). O MCP aceita sheet como string ou inteiro. A seleção é registrada em selectedSheet; seleções desconhecidas listam as planilhas disponíveis.

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) e CLI read / MCP usam como padrão maxNodes: 2000; valores válidos são inteiros de 1 a 50000. O opcional maxDepth é um inteiro não negativo. A raiz é a profundidade 0, então uma raiz com filhos apenas tem maxDepth: 1. Os limites podam tópicos em pré-ordem entre planilhas. truncated e warnings relatam tópicos omitidos. Aumente os limites ou selecione uma planilha para ler mais. A conversão de arquivos não tem limite de tamanho. Leitura da CLI sem --json e texto MCP anexam avisos como > Note: ....

Use caminhos absolutos para MCP: caminhos relativos são resolvidos em relação ao diretório de trabalho do servidor, que pode diferir do seu terminal. Leitura da CLI e MCP expandem ~ ou ~/ iniciais usando o diretório inicial. Caminhos relativos ausentes relatam o caminho resolvido e o diretório de trabalho do servidor.

Formato JSON e resultados MCP

CLI read --json mantém schemaVersion: 1 e os campos existentes, adicionando sheets: [{ index, title, nodeCount, maxDepth }], opcional selectedSheet: { index, title }, truncated e warnings. As contagens descrevem a entrada selecionada antes da truncagem; maxDepth sempre conta a raiz como profundidade 0.

Para format: "json", content é uma árvore de tópicos para uma planilha. A partir da versão 0.4.0, várias planilhas produzem { sheets: [{ index, title, root: AgentTopic }] }. Os limites se aplicam a essas árvores, bem como a Markdown e esboços.

O MCP retorna um bloco de texto simples contendo Markdown, texto de esboço ou árvores JSON formatadas. Ele também retorna structuredContent com { schemaVersion, file, source, format, nodeCount, maxDepth, sheets, selectedSheet?, truncated, warnings }, validado contra o outputSchema registrado da ferramenta. O texto não é mais um envelope de resultado serializado em JSON. Avisos são anexados como uma linha final > Note: .... Erros usam isError: true com uma mensagem clara; a ferramenta permanece somente leitura.

Cursor CLI em modo headless (cursor-agent -p) precisa de --force (mais --approve-mcps) ou a chamada da ferramenta é rejeitada.

Como funciona

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

A costura é convertBuffer / convertFile em src/index.ts. Cada formato de entrada é analisado em um MindMapDocument, então um novo formato precisa de um analisador e nenhuma mudança no renderizador. A CLI e a TUI usam essa costura. A interface web usa seu conversor de navegador com alocação de ID de fallback compartilhada; agentes usam readMindMap em src/agent.ts, que nunca grava arquivos.

Mantém texto, hierarquia, ordem, notas e links. Todas as planilhas XMind são lidas. Rótulos aparecem inline no Markdown genérico e esboços. Descarta estilos, cores e layout. XMind 8 (XML legado) não é suportado.

Testes

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

Licença

MIT