CherryTree MCP Server

MCP server que expõe leitura e escrita de arquivos CherryTree .ctd (XML) como ferramentas nativas do Claude Code.

Suporta rich text, codeboxes, tabelas, imagens, âncoras e bookmarks. Todas as escritas passam por auditoria byte-a-byte automática comparando o backup com o arquivo resultante no disco.

Tools disponíveis

Leitura

• list_nodes — listar nodes da árvore (com profundidade e breadcrumb)
• read_node — ler conteúdo de um node (texto, formatação, widgets)
• search_nodes — busca full-text em todos os nodes
• list_bookmarks — listar nodes marcados como favoritos

Escrita

• create_node — criar node (texto plano ou XML rico via content_xml)
• create_node_with_codebox — criar node com codebox (ou XML rico via content_xml)
• update_node_content — substituir ou append (texto plano ou XML rico via content_xml)
• append_codebox_to_node — adicionar codebox ou XML rico a node existente
• update_node_properties — alterar nome, tags, ícone, cor, readonly
• delete_node — deletar node e filhos
• move_node — mover node para outro pai

Bookmarks

• add_bookmark — adicionar node aos favoritos
• remove_bookmark — remover node dos favoritos

Rich Text (content_xml)

Os tools de escrita aceitam content_xml para formatação completa do CherryTree:

<rich_text scale="h1" foreground="#00000000ffff" weight="heavy">Título</rich_text>
<rich_text>
Texto normal com </rich_text>
<rich_text weight="heavy">negrito</rich_text>
<rich_text> e </rich_text>
<rich_text style="italic">itálico</rich_text>
<rich_text foreground="#e66100" weight="heavy"> e laranja bold</rich_text>
<rich_text link="node 42">link interno</rich_text>

Atributos suportados em <rich_text>

Atributo	Valores	Exemplo
weight	heavy	bold
foreground	#RRRRGGGGBBBB (48-bit GTK)	#00000000ffff (azul)
background	#RRRRGGGGBBBB	highlight
style	italic	itálico
underline	single	sublinhado
strikethrough	true	riscado
scale	h1-h6, small, sup, sub	headings
family	monospace	monoespaçado
justification	left, center, right, fill	alinhamento
link	webs URL, node UID, file BASE64, fold BASE64	links
indent	1-3	indentação

Widgets (posicionados por char_offset)

Widgets são renderizados inline na posição char_offset (contagem de chars no texto concatenado dos <rich_text>). Cada widget ocupa exatamente 1 caractere no buffer.

<codebox char_offset="42" justification="left" frame_width="700"
         frame_height="200" width_in_pixels="1"
         syntax_highlighting="python3" highlight_brackets="1"
         show_line_numbers="0">print("hello")</codebox>

<table char_offset="100" col_min="40" col_max="400"
       col_widths="200,200" is_light="0">
  <row><cell>valor1</cell><cell>valor2</cell></row>
  <row><cell>header1</cell><cell>header2</cell></row>
</table>

<encoded_png char_offset="50" anchor="nome_ancora"/>

Arquitetura

• Leituras usam lxml para parsing/queries XML (seguro, sem write-back)
• Escritas usam manipulação de string raw para evitar normalização de \r que corrompe char_offset em nodes não editados (bug do lxml/ET ao serializar)
• Backup com timestamp criado automaticamente antes de cada escrita em .cherrytree-backups/ (mantém os últimos 10)
• Auditoria byte-a-byte após cada escrita: lê backup e arquivo novo do disco, compara prefixo/sufixo, identifica node alterado, conta total de nodes, valida XML

Backups

Toda operação de escrita cria um backup antes de modificar o arquivo:

Documents/.cherrytree-backups/
  Anotações_20260821_000345.ctd
  Anotações_20260821_000639.ctd
  Anotações_20260821_001800.ctd
  ...

• Formato: {nome}_{YYYYMMDD_HHMMSS}.ctd
• Retenção: últimos 10 backups (mais antigos são removidos automaticamente)
• Localização: subpasta .cherrytree-backups/ no mesmo diretório do arquivo .ctd

Para restaurar manualmente:

cp "Documents/.cherrytree-backups/Anotações_20260821_000345.ctd" "Documents/Anotações.ctd"

Formato de auditoria

Toda operação de escrita retorna um relatório como:

[AUDIT] readback 45,120,109 bytes: OK
  delta: +252 bytes (45,119,857 -> 45,120,109)
  change region: bak[45,119,844:45,119,844] -> disk[45,119,844:45,120,096]
  prefix (45,119,844 bytes): OK
  suffix (13 bytes): OK
  nodes: 5304 (backup) -> 5305 (disco) [+1]
  node adicionado: 6481 "Nome do Node" (alvo)
  integridade: OK
  XML parse: OK

Se qualquer byte fora da região alvo diferir entre backup e disco, o relatório exibe CORRUPTED! e INTEGRITY FAILURE.

Todas as write tools retornam o relatório de auditoria na resposta. Em caso de falha no XML parse, o backup é restaurado automaticamente:

  XML parse: FAILED — <detalhes do erro>
  ROLLBACK: backup restaurado automaticamente

Instalação

1. Criar virtualenv e instalar dependências

cd ~/cherrytree-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

2. Configurar o MCP no Claude Code

claude mcp add cherrytree -s user \
  -e CHERRYTREE_FILE="/caminho/para/seu/arquivo.ctd" \
  -- /caminho/para/cherrytree-mcp/.venv/bin/python \
     /caminho/para/cherrytree-mcp/server.py

3. Reiniciar o Claude Code

As tools aparecem automaticamente como mcp__cherrytree__<tool_name>.

Variáveis de ambiente

Variável	Descrição
CHERRYTREE_FILE	Caminho absoluto para o arquivo .ctd do CherryTree

Requisitos

• Python >= 3.11
• CherryTree v1.x (formato .ctd XML, não .ctb SQLite)
• Dependências: mcp[cli]>=1.0.0, lxml>=5.0.0

Limitações

• Apenas formato .ctd (XML). Arquivos .ctb (SQLite) não são suportados.
• O CherryTree precisa ser recarregado (fechar/abrir ou trocar de node) após edições via MCP para refletir as mudanças na UI.
• Operações de escrita com append=False em update_node_content substituem todo o conteúdo do node (texto, codeboxes, imagens, tabelas).