NF-DS-1: Spec MCP tool groups (read_page, search_notion, write ops) for public Notion API

[samscarrow]

Notion Work Item: NF-DS-1
URL: https://www.notion.so/54921b1fc41a4cf38aecfbd1e681460a

Objective
Spec + implement 6 MCP tools in cli/mcp_server.py using the public Notion API path:

• read_page
• search_notion
• update_page_properties
• append_page_content
• create_database_row
• (confirm the 6th tool in spec; ensure tool count 27 → 33)

Key context

• Target repo/branch: samscarrow/notion-ai-scraper @ main
• Core work: adapters in cli/block_builder.py (public API blocks ↔ IR ↔ markdown)
• Add NotionAPIClient.search() in cli/notion_api.py

Kill/Stop Condition
Kill if public API block tree cannot reproduce page content with sufficient fidelity for agent consumption.
Stop when all tools are implemented and manually tested; MCP tool count increments from 27 → 33.

[samscarrow]

Lab-to-Factory Handoff

Context

You are implementing a design spec Work Item: NF-DS-1.

Goal: add 6 MCP tools to notion-forge (repo samscarrow/notion-ai-scraper, branch main) to close the gaps vs. the official Notion MCP for agent workflows:

1. Read a page body as markdown
2. Search the workspace
3. Perform essential write operations (update properties, append content, create rows)

This work must use only the public Notion API via existing infrastructure in cli/notion_api.py and cli/block_builder.py. Do not use token_v2 or any internal API.

Inputs (pin these)

• Repo: samscarrow/notion-ai-scraper
• Branch: main
• Key files:
  • cli/mcp_server.py (FastMCP server; add all new tools here)
  • cli/notion_api.py (NotionAPIClient; already has list_block_children, retrieve_page, update_page, create_page, append_block_children, query_database)
  • cli/block_builder.py (IR pipeline Markdown ↔ IR ↔ Notion blocks)
• Auth model: public API only (CFG.notion_token, _get_notion_api_client())
• Kill/Stop condition:
  • KILL if public API block tree cannot reproduce page content with sufficient fidelity for agent consumption (notably nested blocks, synced blocks, databases-in-pages, columns).
  • STOP / PASS when all 6 tools work end-to-end on a representative nested page and tool count goes 27 → 33.

Execution strategy (implementation order)

1. Implement core adapters in cli/block_builder.py:
   • public_blocks_to_ir() (+ rich_text span helpers)
   • ir_to_public_api_blocks()
2. Add a Notion Search API wrapper in cli/notion_api.py:
   • NotionAPIClient.search() method
3. Add MCP tool wrappers in cli/mcp_server.py:
   • read_page
   • search_notion
   • update_page_properties
   • append_page_content
   • create_database_row
   • Plus one additional tool to reach 6 new tools total and increment tool count 27 → 33 (finalize name/behavior during implementation, but ensure it is consistent with the “read/search/write” gap-closure theme).

Detailed requirements

Tool 1: read_page(page_id: str) -> str

Goal: return clean markdown for a page, including headings, lists, code blocks, callouts, quotes, toggles, dividers, inline formatting.

Implementation:

• Normalize page_id via _to_dashed_uuid()
• Retrieve title via client.retrieve_page(page_id) and prepend # {title}
• Fetch child blocks via client.list_block_children(page_id)
• Convert public API blocks → IR → markdown:
  • Add public_blocks_to_ir(blocks, client, depth_cap=3) in block_builder.py
  • Recursively fetch children for blocks with has_children=true
  • Cap recursion depth at 3 and log a warning on truncation
• Unsupported types should render as <!-- notion:{type} -->
• Empty page should return "(empty page)"

Tool 2: search_notion(query: str, filter_type: str = "", limit: int = 10) -> str

Goal: search workspace for pages/databases and return formatted markdown list.

Implementation:

• Add NotionAPIClient.search() in cli/notion_api.py:
  • POST /v1/search with query, page_size (cap at 100), optional filter, optional start_cursor
• In tool wrapper, allow filter_type in ("page", "database") by setting {"property":"object","value":filter_type}
• Format results as:
  • - **Page:** Title — URL (edited YYYY-MM-DD)
  • - **Database:** Title — URL (edited YYYY-MM-DD)
• Handle “no results” cleanly

Tool 3: update_page_properties(page_id: str, properties_json: str) -> str

Goal: update database-row properties.

Implementation:

• Parse JSON string, call client.update_page(page_id, properties)
• Return confirmation listing updated property names
• Provide clear error for invalid JSON

Tool 4: append_page_content(page_id: str, markdown: str) -> str

Goal: append markdown-derived blocks to end of page body.

Implementation:

• markdown -> IR via existing markdown_to_ir() (or equivalent)
• Add ir_to_public_api_blocks(ir_blocks) in block_builder.py to emit public API block dicts
• Call client.append_block_children(page_id, public_api_blocks)
• Return appended block count

Tool 5: create_database_row(database_id: str, properties_json: str) -> str

Goal: create a new row in a database.

Implementation:

• Parse JSON string, call client.create_page({"database_id": database_id}, properties)
• Return created page id and URL

Core adapter work in cli/block_builder.py

Add:

• public_blocks_to_ir()
• ir_to_public_api_blocks()
• _public_rich_text_to_spans()
• _spans_to_public_rich_text()

Must support:

• paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, code, callout, quote, toggle, divider
• text annotations (bold/italic/strikethrough/underline/code), links, and mentions (at least page mentions)

Manual test plan (must do)

1. Read a representative nested page to markdown
2. Search for it via search_notion
3. Update a property via update_page_properties
4. Append markdown via append_page_content
5. Create a database row via create_database_row
6. Validate fidelity for nested blocks, synced blocks, databases-in-pages, columns per kill condition

Output expectations

• Keep code consistent with existing patterns in query_database() in cli/mcp_server.py
• Do not introduce internal API dependencies
• Ensure the tool count increments to 33 once the 6 new tools are added