Arezzo

Arezzo

Google Docs API オペレーション向けの決定論的コンパイラーです。

batchUpdate リクエストを自分で組み立てて Google ドキュメントを安全に変更することはできません。API は UTF-16 コード単位と、連鎖的に変化するインデックスを使用します。位置 50 に 10 文字を挿入すると、バッチ内のそれ以降のすべてのインデックスが誤ったものになります。計算を一度間違えるだけで、エラーメッセージもなくドキュメントが破損します。

Arezzo は、意図した操作を正しいリクエストシーケンスにコンパイルします。実行したい操作を伝えるだけで、インデックスの計算は Arezzo が処理します。

AI エージェント向け（MCP ツール）

Arezzo は Model Context Protocol を介して 3 つのツールを提供します。

read_document(document_id)
  → Returns the document's structural map: headings with hierarchy,
    named ranges, tables, section boundaries. Call this before editing
    so you know what addresses are available.

edit_document(document_id, operations)
  → Compiles operations into correct batchUpdate requests and executes
    them. Handles UTF-16 arithmetic, cascading index shifts, and
    OT-compatible request ordering. Supported operations: insert/delete/
    replace text, formatting (bold, italic, headings, links), tables,
    lists, images, headers/footers, footnotes, named ranges.

validate_operations(document_id, operations)
  → Compile-only dry run. Returns the compiled requests for inspection
    without executing. Use before edit_document when uncertain.

オペレーションの形式

{
  "type": "insert_text",
  "address": {"heading": "Revenue Analysis"},
  "params": {"text": "New paragraph content.\n"}
}

アドレスモード：

• {"heading": "Section Name"} — 見出しのテキストで指定
• {"named_range": "range_name"} — 名前付き範囲で指定
• {"bookmark": "bookmark_id"} — ブックマーク ID で指定
• {"start": true} — ドキュメントの先頭
• {"end": true} — ドキュメントの末尾
• {"index": 42} — 絶対 UTF-16 インデックス

オペレーションの種類： insert_text、delete_content、replace_all_text、replace_section、 update_text_style、update_paragraph_style、insert_bullet_list、 insert_table、insert_table_row、insert_table_column、 delete_table_row、delete_table_column、insert_image、 create_header、create_footer、create_footnote、 create_named_range、replace_named_range_content、insert_page_break

推奨ワークフロー

read_document → edit_document → (if structural changes) read_document → edit_document

編集前に必ず読み取ってください。構造要素（テーブル、ヘッダー、フッター）を挿入した後は、内部にコンテンツを追加する前に、もう一度読み取って新しい要素のインデックスを取得してください。

インストール

pip install arezzo
arezzo init

arezzo init は Google OAuth の設定手順を案内し、MCP クライアント用のプラットフォーム設定ファイルを書き込みます。

セットアップ

前提条件： Google Docs API を有効にした Google Cloud プロジェクトと、OAuth 2.0 クライアント ID（デスクトップアプリケーションタイプ）が必要です。

arezzo init

ウィザードでは、次の処理が行われます。

1. credentials.json を ~/.config/arezzo/ にコピーします
2. OAuth の同意フローを実行します（ブラウザーが一度開きます）
3. Claude Code、Cursor、VS Code 用の設定ファイルを生成します

Claude Desktop の場合、arezzo init は手動で追加する設定ブロックを表示します。

プラットフォーム設定

arezzo init の実行後、設定ファイルがプロジェクトディレクトリに書き込まれます。

Claude Code / Cursor（.mcp.json）：

{
  "mcpServers": {
    "arezzo": {
      "command": "arezzo"
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "arezzo": {
      "type": "stdio",
      "command": "arezzo"
    }
  }
}

Claude Desktop（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "arezzo": {
      "command": "arezzo"
    }
  }
}

Arezzo が作られた理由

Google Docs の batchUpdate API は、絶対インデックス位置を UTF-16 コード単位で扱います。文字を挿入または削除するたびに、それ以降のすべてのインデックスがずれます。複数の変更を含むバッチでは、各リクエストのインデックスに、同じバッチ内で先行するすべてのリクエストの影響を反映する必要があります。

正しく処理するには、次のことが必要です。

• UTF-16 の長さを計算する（Python の len() では不可です。サロゲートペアの数え方が異なります）
• 同じ種類の変更は逆順に実行する（末尾から先頭に向かって削除する）
• 2 段階でコンパイルする（書式変更より先にコンテンツを変更する）
• 複数ステップのオペレーション全体で、連鎖するオフセットを追跡する

Arezzo はこれらを決定論的に処理します。同じ入力からは常に同じ出力が生成されます。推論も推測もなく、「たいていうまくいく」ということもありません。

アーキテクチャ

semantic operation
    ↓
arezzo.parser.parse_document()    — build heading/range/bookmark indexes
    ↓
arezzo.address.resolve_address()  — semantic reference → document index
    ↓
arezzo.operations.*               — operation → batchUpdate request(s)
    ↓
arezzo.index.sort_requests()      — OT-compatible mutation ordering
    ↓
correct batchUpdate request sequence

エンジンは純粋関数です。compile_operations(doc, operations) → requests。決定論的で、副作用はなく、API 呼び出しもありません。

MCP サーバー（arezzo.server）は、エンジンを Google Docs API の入出力と動作ガイダンス用のフィールド（next_step、present_to_user、document_reality）でラップします。

ライセンス

MIT — Convergent Methods, LLC