Arezzo
@ConvergentMethods
Compile semantic document edits into correct Google Docs batchUpdate requests. UTF-16 arithmetic, cascading index shifts, OT-compatible ordering. MIT licensed.
Overview
What is Arezzo?
Arezzo is an MCP server that compiles semantic editing operations into correct Google Docs API batchUpdate request sequences — deterministically. It solves the problem of manual UTF-16 offset calculation for AI agents editing documents, handling complex Unicode like emoji and CJK characters.
How to use Arezzo?
Install with pip install arezzo, then run arezzo init to walk through Google OAuth setup and write platform config files. Use the three MCP tools: read_document, edit_document, and validate_operations.
Key features of Arezzo
- Deterministic compilation of semantic edits to API requests.
- UTF-16 index arithmetic with proper surrogate pair handling.
- Address resolution by heading, named range, or bookmark.
- Two-phase compilation for OT-compatible sequencing.
- 23 operation types including text, formatting, tables, and images.
- Zero configuration beyond Google OAuth setup.
Use cases of Arezzo
- AI agents editing Google Docs without manual offset calculation.
- Inserting and formatting text at headings, named ranges, or bookmarks.
- Previewing exact API calls before execution with
validate_operations. - Editing documents containing emoji, CJK supplementary characters, and other non-BMP Unicode.
FAQ from Arezzo
What problem does Arezzo solve?
AI agents editing Google Docs via the batchUpdate API must calculate UTF-16 code unit offsets for every mutation. A single miscalculation silently corrupts the document. Arezzo compiles semantic operations into correct request sequences deterministically, eliminating offset errors.
What tools does Arezzo provide?
Three MCP tools: read_document (structural map of the document), edit_document (compile and execute up to 23 operation types), and validate_operations (dry-run compilation to inspect exact API calls before execution).
How do I set up Arezzo?
Install with pip install arezzo and then run arezzo init to walk through Google OAuth setup. No other configuration is required beyond OAuth.
Does Arezzo handle emoji and non-BMP characters?
Yes. Arezzo performs proper UTF-16 surrogate pair handling for emoji, CJK supplementary characters, and all non-BMP Unicode.
What is the compilation process?
Arezzo uses two-phase compilation: content mutations (insert, delete, replace) are processed in reverse index order first, then format mutations are applied. This produces OT-compatible request sequencing.
