Arezzo

Arezzo is an MCP server that compiles semantic editing operations into correct Google Docs API batchUpdate request sequences — deterministically.

The problem: AI agents editing Google Docs via the batchUpdate API must calculate UTF-16 code unit offsets for every mutation. Insert 10 characters at position 50, and every subsequent index in the batch is wrong. A single miscalculation silently corrupts the document with no error message.

What Arezzo does:

• Deterministic Compiler — Semantic intent → correct batchUpdate requests. Same inputs, same output, every time. Zero reasoning in the compilation path.
• UTF-16 Index Arithmetic — Proper surrogate pair handling for emoji, CJK supplementary characters, and all non-BMP Unicode.
• Address Resolution — Target locations by heading name, named range, bookmark, document start/end, or absolute index. No manual offset calculation.
• Two-Phase Compilation — Content mutations in reverse index order, then format mutations. OT-compatible request sequencing.

3 MCP tools:

• read_document(document_id) — Structural map: headings, named ranges, tables, bookmarks, section boundaries. Call before editing.
• edit_document(document_id, operations) — Compile + execute. 23 operation types: text, formatting, tables, lists, images, headers/footers, footnotes, named ranges.
• validate_operations(document_id, operations) — Dry-run compilation. Inspect the exact API calls before they execute.

Zero configuration beyond OAuth: pip install arezzo && arezzo init walks through Google OAuth setup and writes platform config files.

Named for Guido d'Arezzo (~991-1033), the monk who standardized music notation. MIT licensed.