CherryTree MCP Server

CherryTree .ctd(XML) 파일의 읽기와 쓰기를 Claude Code의 네이티브 도구로 노출하는 MCP 서버입니다.

리치 텍스트, 코드박스, 표, 이미지, 앵커, 북마크를 지원합니다. 모든 쓰기 작업은 백업과 디스크의 결과 파일을 비교하는 자동 바이트 단위 감사를 거칩니다.

사용 가능한 도구

읽기

• list_nodes — 트리의 노드 나열(깊이 및 breadcrumb 포함)

• read_node — 노드 내용 읽기(텍스트, 서식, 위젯)

• search_nodes — 모든 노드에서 전체 텍스트 검색

• list_bookmarks — 즐겨찾기로 표시된 노드 나열

쓰기

• create_node — 노드 생성(일반 텍스트 또는 content_xml을 통한 리치 XML)

• create_node_with_codebox — 코드박스가 있는 노드 생성(content_xml을 통한 리치 XML도 가능)

• update_node_content — 내용 교체 또는 추가(일반 텍스트 또는 content_xml을 통한 리치 XML)

• append_codebox_to_node — 기존 노드에 코드박스 또는 리치 XML 추가

• update_node_properties — 이름, 태그, 아이콘, 색상, 읽기 전용 변경

• delete_node — 노드 및 하위 노드 삭제

• move_node — 노드를 다른 부모로 이동

북마크

• add_bookmark — 노드를 즐겨찾기에 추가

• remove_bookmark — 노드를 즐겨찾기에서 제거

Related MCP server: notion-full-mcp

리치 텍스트(content_xml)

쓰기 도구는 CherryTree의 전체 서식을 위해 content_xml을 허용합니다:

<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으로 위치 지정)

위젯은 <rich_text>의 연결된 텍스트에서 문자 수를 기준으로 char_offset 위치에 인라인으로 렌더링됩니다. 각 위젯은 버퍼에서 정확히 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 파싱/쿼리(안전, write-back 없음)

• 쓰기는 raw 문자열 조작을 사용하여 편집되지 않은 노드에서 char_offset을 손상시키는 \r 정규화를 방지합니다(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. virtualenv 생성 및 의존성 설치

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

2. Claude Code에서 MCP 구성

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__<tool_name>으로 자동으로 나타납니다.

환경 변수

요구 사항

• 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를 다시 로드(닫기/열기 또는 노드 전환)해야 UI에 변경 사항이 반영됩니다.

• update_node_content에서 append=False인 쓰기 작업은 노드의 전체 내용(텍스트, 코드박스, 이미지, 표)을 대체합니다.