feat: Notion Bridge — In-place block editing (notion_write_update_block)

[Delqhi]

Enhancement Request

Add notion_write_update_block tool to the Notion MCP bridge for editing existing blocks in-place.

API Capability

The Notion API supports PATCH /v1/blocks/{block_id} for updating block content:

• Paragraphs: Update rich_text
• Headings: Update rich_text, color, is_toggleable
• Code blocks: Update rich_text, language, caption
• To-Do: Update checked, rich_text
• Callouts: Update rich_text, icon, color

Plus: PATCH /v1/pages/{page_id}/markdown for Markdown-based updates with search-and-replace.

Requirements

• Update block content without recreating
• Support rich text formatting
• Support block-specific properties (checked, color, language)
• Follow Bridged-External pattern (M6)
• Permission: ask (destructive edit)

Acceptance Criteria

• Tool updates existing blocks via vibe-notion raw API
• Rich text formatting preserved
• Block-specific properties updated
• Markdown update option available
• Tests pass with go test -race
• CHANGELOG.md + AGENTS.md updated

References

• Notion API: https://developers.notion.com/reference/update-a-block
• Notion API: https://developers.notion.com/reference/update-page-content
• Related: issue feat: Notion Bridge — Column layout tools (notion_write_create_columns) #493 (columns), issue feat: Notion Bridge — Tab layout tools (notion_write_create_tabs) #494 (tabs)

[Delqhi]

Deep Research: Notion API Block Editing

API Capability (Verified)

The Notion API supports PATCH /v1/blocks/{block_id} for updating block content:

curl https://api.notion.com/v1/blocks/{block_id} \
  -H 'Authorization: Bearer $NOTION_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Notion-Version: 2021-05-13' \
  -X PATCH \
  --data '{
    "paragraph": {
      "rich_text": [
        {
          "type": "text",
          "text": { "content": "Updated paragraph content" }
        }
      ]
    }
  }'

vibe-notion CLI Support (Verified)

The CLI already supports block updates via block update --content:

vibe-notion block update <block_id> --content '{
  "paragraph": {
    "rich_text": [{"type": "text", "text": {"content": "Neuer Inhalt"}}]
  }
}'

Supported Block Types & Properties

Block Type	Updatable Properties
paragraph	rich_text, color
heading_1	rich_text, color, is_toggleable
heading_2	rich_text, color, is_toggleable
heading_3	rich_text, color, is_toggleable
bulleted_list_item	rich_text, color
numbered_list_item	rich_text, color
to_do	rich_text, checked, color
toggle	rich_text, color
quote	rich_text, color
callout	rich_text, icon, color
equation	expression (LaTeX)
embed	url
image	external.url, caption
video	external.url, caption
pdf	external.url, caption
table	has_column_header, has_row_header
table_row	cells
column	width_ratio
synced_block	synced_from.block_id
template	rich_text
page	properties
archived (all types)	boolean — soft-delete

Unsupported block types (cannot update via PATCH): child_page, child_database, link_preview, link_to_page, unsupported (forms, buttons, drive), table_of_contents, breadcrumb, divider, file, bookmark.

Critical Limitations & Gotchas

Gotcha	Details
Full replacement, not merge	Updating rich_text replaces ALL segments — you must send the complete formatted text
No partial rich text edit	Can't modify one word's formatting without resending all 100 segments
100 rich text limit	Max 100 items per block's rich_text array
Markdown endpoint requires 2026-03-11	Must set Notion-Version: 2026-03-11 header
Content range selection is fuzzy	Ellipsis format "start...end" — Notion matches text spans, not exact positions

New Markdown Endpoint (API 2026-03-11)

# Search-and-replace
curl -X PATCH 'https://api.notion.com/v1/pages/{page_id}/markdown' \
  -H 'Notion-Version: 2026-03-11' \
  --data '{
    "type": "update_content",
    "update_content": {
      "content_updates": [
        {
          "old_str": "Draft proposal",
          "new_str": "Draft proposal (due Friday)"
        }
      ]
    },
    "allow_deleting_content": false
  }'

Proposed Tool Signature

@mcp.tool()
def notion_write_update_block(
    block_id: str,
    block_type: str,
    content: str | list[dict],  # Rich text content
    checked: bool | None = None,  # For to_do blocks
    color: str | None = None,  # For colored blocks
    icon: dict | None = None,  # For callout blocks
    expression: str | None = None,  # For equation blocks
    url: str | None = None,  # For embed/image/video/pdf blocks
) -> dict[str, Any]:
    """Update an existing block's content in-place.
    
    Args:
        block_id: ID of the block to update
        block_type: Type of block (paragraph, heading_1, heading_2, etc.)
        content: New content (string for simple text, list for rich text)
        checked: For to_do blocks, whether checked
        color: For colored blocks (default, gray, brown, orange, yellow, green, blue, purple, pink, red)
        icon: For callout blocks (e.g., {"emoji": "⚠️"})
        expression: For equation blocks (LaTeX)
        url: For embed/image/video/pdf blocks
    """
    # Build update payload
    update = {}
    
    if block_type in ["paragraph", "heading_1", "heading_2", "heading_3",
                      "bulleted_list_item", "numbered_list_item", "to_do",
                      "toggle", "quote", "callout"]:
        # Rich text blocks
        if isinstance(content, str):
            rich_text = [{"type": "text", "text": {"content": content}}]
        else:
            rich_text = content
        
        block_data = {"rich_text": rich_text}
        if color:
            block_data["color"] = color
        if icon and block_type == "callout":
            block_data["icon"] = icon
        if checked is not None and block_type == "to_do":
            block_data["checked"] = checked
        
        update[block_type] = block_data
    
    elif block_type == "equation":
        update["equation"] = {"expression": expression}
    
    elif block_type in ["embed", "image", "video", "pdf"]:
        update[block_type] = {"external": {"url": url}}
    
    elif block_type == "column":
        update["column"] = {"width_ratio": float(content)}
    
    else:
        return {"ok": False, "error": f"Unsupported block type: {block_type}"}
    
    return _run(["block", "update", block_id, "--content", json.dumps(update)])

Example Usage

# Update a paragraph
notion_write_update_block(
    block_id="abc123",
    block_type="paragraph",
    content="This is the updated paragraph content."
)

# Update a to-do (check it off)
notion_write_update_block(
    block_id="def456",
    block_type="to_do",
    content="Buy groceries",
    checked=True
)

# Update a callout with icon
notion_write_update_block(
    block_id="ghi789",
    block_type="callout",
    content="Important warning",
    icon={"emoji": "⚠️"},
    color="red"
)

# Update an equation
notion_write_update_block(
    block_id="jkl012",
    block_type="equation",
    expression="E = mc^2"
)

# Update column width
notion_write_update_block(
    block_id="mno345",
    block_type="column",
    content="0.75"  # 75% width
)

References

• Notion API: Update a Block
• Notion API: Update Page Content
• Rich Text Objects