CherryTree MCP Server

Servidor MCP que expone lectura y escritura de archivos CherryTree .ctd (XML) como herramientas nativas de Claude Code.

Soporta rich text, codeboxes, tablas, imágenes, anclas y bookmarks. Todas las escrituras pasan por una auditoría automática byte a byte que compara el backup con el archivo resultante en el disco.

Herramientas disponibles

Lectura

• list_nodes — listar nodos del árbol (con profundidad y breadcrumb)

• read_node — leer contenido de un nodo (texto, formato, widgets)

• search_nodes — búsqueda full-text en todos los nodos

• list_bookmarks — listar nodos marcados como favoritos

Escritura

• create_node — crear nodo (texto plano o XML enriquecido vía content_xml)

• create_node_with_codebox — crear nodo con codebox (o XML enriquecido vía content_xml)

• update_node_content — reemplazar o añadir (texto plano o XML enriquecido vía content_xml)

• append_codebox_to_node — añadir codebox o XML enriquecido a un nodo existente

• update_node_properties — modificar nombre, tags, icono, color, readonly

• delete_node — eliminar nodo e hijos

• move_node — mover nodo a otro padre

Bookmarks

• add_bookmark — añadir nodo a los favoritos

• remove_bookmark — eliminar nodo de los favoritos

Related MCP server: notion-full-mcp

Rich Text (content_xml)

Las herramientas de escritura aceptan content_xml para el formato completo de 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 soportados en <rich_text>

Widgets (posicionados por char_offset)

Los widgets se renderizan inline en la posición char_offset (recuento de caracteres en el texto concatenado de los <rich_text>). Cada widget ocupa exactamente 1 carácter en el 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"/>

Arquitectura

• Lecturas usan lxml para parsing/consultas XML (seguro, sin write-back)

• Escrituras usan manipulación de string raw para evitar la normalización de \r que corrompe char_offset en nodos no editados (bug de lxml/ET al serializar)

• Backup .ctd.bak creado automáticamente antes de cada escritura

• Auditoría byte a byte después de cada escritura: lee el backup y el archivo nuevo del disco, compara prefijo/sufijo, identifica el nodo modificado, cuenta el total de nodos, valida XML

Formato de auditoría

Toda operación de escritura devuelve un informe 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

Si cualquier byte fuera de la región objetivo difiere entre el backup y el disco, el informe muestra CORRUPTED! e INTEGRITY FAILURE.

Instalación

1. Crear virtualenv e instalar dependencias

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

2. Configurar el MCP en 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 Claude Code

Las herramientas aparecen automáticamente como mcp__cherrytree__<tool_name>.

Variables de entorno

Requisitos

• Python >= 3.11

• CherryTree v1.x (formato .ctd XML, no .ctb SQLite)

• Dependencias: mcp[cli]>=1.0.0, lxml>=5.0.0

Limitaciones

• Solo formato .ctd (XML). Los archivos .ctb (SQLite) no son compatibles.

• CherryTree debe recargarse (cerrar/abrir o cambiar de nodo) después de ediciones vía MCP para reflejar los cambios en la UI.

• Las operaciones de escritura con append=False en update_node_content reemplazan todo el contenido del nodo (texto, codeboxes, imágenes, tablas).