CherryTree MCP Server

CherryTree .ctd（XML）ファイルの読み書きをClaude Codeのネイティブツールとして公開するMCPサーバー。

リッチテキスト、コードボックス、テーブル、画像、アンカー、ブックマークをサポートします。すべての書き込みは、バックアップとディスク上の結果ファイルを比較する自動バイト単位監査を通過します。

利用可能なツール

読み取り

• list_nodes — ツリーのノードを一覧表示（深さとパンくずリスト付き）

• read_node — ノードのコンテンツを読み取り（テキスト、書式、ウィジェット）

• search_nodes — 全ノードの全文検索

• list_bookmarks — お気に入りとしてマークされたノードを一覧表示

書き込み

• create_node — ノードを作成（プレーンテキストまたはcontent_xml経由のリッチXML）

• create_node_with_codebox — コードボックス付きノードを作成（またはcontent_xml経由のリッチXML）

• update_node_content — 置換またはappend（プレーンテキストまたはcontent_xml経由のリッチXML）

• append_codebox_to_node — 既存ノードにコードボックスまたはリッチXMLを追加

• update_node_properties — 名前、タグ、アイコン、色、readonlyを変更

• 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で配置）

ウィジェットは、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のパース/クエリを行います（安全、書き戻しなし）

• 書き込みは、未編集ノードの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経由の編集後、UIに変更を反映するにはCherryTreeを再読み込み（閉じる/開く、またはノードを切り替える）する必要があります。

• update_node_contentでappend=Falseの書き込み操作は、ノードの全コンテンツ（テキスト、コードボックス、画像、テーブル）を置き換えます。