feat: Notion Bridge — Tab layout tools (notion_write_create_tabs)

[Delqhi]

Enhancement Request

Add notion_write_create_tabs tool to the Notion MCP bridge for creating tab blocks in Notion pages.

API Capability

Since Notion API version 2026-03-11, tabs are supported as a block type:

{
  "type": "tab",
  "tab": {
    "children": [
      {
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Tab Label"}}],
          "icon": {"emoji": "📋"},
          "children": [...]
        }
      }
    ]
  }
}

Requirements

• Create tab blocks with multiple tab panels
• Support rich text content in each tab
• Support nested children (paragraphs, headings, etc.)
• Follow Bridged-External pattern (M6)
• Permission: ask (destructive layout change)

Acceptance Criteria

• Tool creates tab blocks via vibe-notion raw API
• Multiple tab panels supported
• Rich text content in each tab panel
• Nested children created within tabs
• Tests pass with go test -race
• CHANGELOG.md + AGENTS.md updated

References

• Notion API: https://developers.notion.com/reference/block#tab
• Notion SDK PR #690 (2026-03-23): TabBlockObjectResponse added
• Related: issue feat: Notion Bridge — Column layout tools (notion_write_create_columns) #493 (column tools)

[Delqhi]

Deep Research: Notion API Tab Blocks

API Capability (Verified)

Since Notion API version 2026-03-11, tabs are fully supported as a block type:

{
  "type": "tab",
  "tab": {
    "children": [
      {
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Tab Label"}}],
          "icon": {"emoji": "📋"},
          "children": [
            {
              "type": "paragraph",
              "paragraph": {
                "rich_text": [{"type": "text", "text": {"content": "Tab content here."}}]
              }
            }
          ]
        }
      }
    ]
  }
}

vibe-notion CLI Support (Verified)

The CLI supports tabs via block append --content (requires API version 2026-03-11):

vibe-notion block append <parent_id> --content '[
  {
    "type": "tab",
    "tab": {
      "children": [
        {
          "type": "paragraph",
          "paragraph": {
            "rich_text": [{"type": "text", "text": {"content": "Übersicht"}}],
            "icon": {"emoji": "📋"},
            "children": [
              {"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Inhalt von Tab 1"}}]}}
            ]
          }
        },
        {
          "type": "paragraph",
          "paragraph": {
            "rich_text": [{"type": "text", "text": {"content": "Details"}}],
            "icon": {"emoji": "🔍"},
            "children": [
              {"type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": "Inhalt von Tab 2"}}]}}
            ]
          }
        }
      ]
    }
  }
]'

Critical Limitations & Gotchas

Gotcha	Detail
Only paragraph children	Only paragraph blocks can be direct children of a tab block. No headings, lists, etc. directly inside.
Paragraph icon restriction	icon on paragraphs is ONLY valid when the paragraph is a direct child of a tab block. Other paragraphs with icon → validation error.
Nested content	The actual tab content lives in children of the paragraph — those children CAN be any block type (paragraphs, headings, lists, etc.).
API version required	Must set Notion-Version: 2026-03-11 header. Older versions return tabs as UnsupportedBlockObjectResponse.
Minimum 2 tabs	A tab container logically needs at least 2 paragraph children to be meaningful (enforced by Notion UI).
Max 100 children	Like all Append block children, max 100 items per request.

SDK Support

PR	Version	What
#675	v5.12.0	API version 2026-03-11 support
#690	v5.13.0+	Tab block types: TabBlockObjectResponse, etc.
#697	latest	Icon support on paragraph blocks (tab items)

Proposed Tool Signature

@mcp.tool()
def notion_write_create_tabs(
    parent_id: str,
    tabs: list[dict],  # [{"label": "Name", "icon": "📋", "blocks": [...]}]
) -> dict[str, Any]:
    """Create a tabbed container with multiple tab panels.
    
    Args:
        parent_id: ID of the parent page or block
        tabs: List of tab definitions with label, optional icon, and content blocks
    """
    tab_children = []
    for tab in tabs:
        # Convert blocks to API format
        content_blocks = []
        for block in tab.get("blocks", []):
            content_blocks.append(convert_block_format(block))
        
        # Tab label paragraph with optional icon
        paragraph = {
            "type": "paragraph",
            "paragraph": {
                "rich_text": [{"type": "text", "text": {"content": tab["label"]}}],
                "children": content_blocks
            }
        }
        
        # Add icon if provided (only valid for tab items)
        if "icon" in tab:
            paragraph["paragraph"]["icon"] = {"emoji": tab["icon"]}
        
        tab_children.append(paragraph)
    
    content = [{
        "type": "tab",
        "tab": {"children": tab_children}
    }]
    
    return _run(["block", "append", parent_id, "--content", json.dumps(content)])

Example Usage

# Create a tabbed container with 2 tabs
notion_write_create_tabs(
    parent_id="93fa71a7-878a-472f-8d52-2564b70baa0d",
    tabs=[
        {
            "label": "Übersicht",
            "icon": "📋",
            "blocks": [
                {"type": "heading_2", "text": "Project Overview"},
                {"type": "paragraph", "text": "This is the overview tab content."}
            ]
        },
        {
            "label": "Details",
            "icon": "🔍",
            "blocks": [
                {"type": "heading_2", "text": "Technical Details"},
                {"type": "paragraph", "text": "This is the details tab content."}
            ]
        }
    ]
)

References

• Notion API: Tab Block
• Notion SDK PR #690 (Tab types)
• Notion SDK PR #697 (Tab item icons)
• API Version 2026-03-11