Arezzo
About
Compile semantic document edits into correct Google Docs batchUpdate requests. UTF-16 arithmetic, cascading index shifts, OT-compatible ordering. MIT licensed.
Details
- Author
- ConvergentMethods
- Downloads
- 316
- Categories
- Knowledge Base, AI, Automation
Jump to
- 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.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
ArezzoCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"arezzo": {
"arezzo": {
"command": "uvx",
"args": [
"arezzo"
]
}
}
}
}McpServers
{
"arezzo": {
"command": "uvx",
"args": [
"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.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
