CherryTree MCP Server

MCP-сервер, который предоставляет чтение и запись файлов CherryTree .ctd (XML) как нативные инструменты Claude Code.

Поддерживает форматированный текст, codeboxes, таблицы, изображения, якоря и закладки. Все записи проходят автоматическую побайтовую проверку, сравнивающую резервную копию с итоговым файлом на диске.

Доступные инструменты

Чтение

• list_nodes — список узлов дерева (с глубиной и хлебными крошками)

• read_node — чтение содержимого узла (текст, форматирование, виджеты)

• search_nodes — полнотекстовый поиск по всем узлам

• list_bookmarks — список узлов, отмеченных как избранные

Запись

• create_node — создание узла (обычный текст или XML с форматированием через content_xml)

• create_node_with_codebox — создание узла с codebox (или XML с форматированием через content_xml)

• update_node_content — замена или добавление (обычный текст или XML с форматированием через content_xml)

• append_codebox_to_node — добавление codebox или XML с форматированием в существующий узел

• update_node_properties — изменение имени, тегов, значка, цвета, только для чтения

• delete_node — удаление узла и его потомков

• move_node — перемещение узла к другому родителю

Закладки

• add_bookmark — добавить узел в избранное

• remove_bookmark — удалить узел из избранного

Related MCP server: notion-full-mcp

форматированный текст (content_xml)

Инструменты записи принимают content_xml для полного форматирования 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>

Поддерживаемые атрибуты в <rich_text>

Виджеты (позиционируются через char_offset)

Виджеты отображаются внутри строки в позиции char_offset (счётчик символов в объединённом тексте <rich_text>). Каждый виджет занимает ровно 1 символ в буфере.

<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"/>

Архитектура

• Чтение использует lxml для парсинга/запросов XML (безопасно, без обратной записи)

• Запись использует манипуляции с сырыми строками, чтобы избежать нормализации \r, которая портит char_offset в неотредактированных узлах (баг lxml/ET при сериализации)

• Резервная копия .ctd.bak создаётся автоматически перед каждой записью

• Проверка побайтовая после каждой записи: читает резервную копию и новый файл с диска, сравнивает префикс/суффикс, определяет изменённый узел, считает общее количество узлов, проверяет XML

Формат проверки

Каждая операция записи возвращает отчёт вида:

[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

Если какой-либо байт за пределами целевой области отличается между резервной копией и диском, отчёт показывает CORRUPTED! и INTEGRITY FAILURE.

Установка

1. Создать виртуальное окружение и установить зависимости

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

2. Настроить MCP в 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. Перезапустить Claude Code

Инструменты появятся автоматически как mcp__cherrytree__<имя_инструмента>.

Переменные окружения

Требования

• Python >= 3.11

• CherryTree v1.x (формат .ctd XML, не .ctb SQLite)

• Зависимости: mcp[cli]>=1.0.0, lxml>=5.0.0

Ограничения

• Поддерживается только формат .ctd (XML). Файлы .ctb (SQLite) не поддерживаются.

• После редактирования через MCP CherryTree необходимо перезагрузить (закрыть/открыть или переключить узел), чтобы изменения отобразились в интерфейсе.

• Операции записи с append=False в update_node_content заменяют всё содержимое узла (текст, codebox'ы, изображения, таблицы).