Better Notion MCP

Instructions

Implementation Reference

• src/tools/composite/blocks.ts:21-142 (handler)

  Primary handler function implementing block operations: get, retrieve children as markdown, append markdown as blocks, update text blocks with markdown, delete blocks.
  export async function blocks(notion: Client, input: BlocksInput): Promise<any> { return withErrorHandling(async () => { if (!input.block_id) { throw new NotionMCPError('block_id required', 'VALIDATION_ERROR', 'Provide block_id') } switch (input.action) { case 'get': { const block: any = await notion.blocks.retrieve({ block_id: input.block_id }) return { action: 'get', block_id: block.id, type: block.type, has_children: block.has_children, archived: block.archived, block } } case 'children': { const blocksList = await autoPaginate((cursor) => notion.blocks.children.list({ block_id: input.block_id, start_cursor: cursor, page_size: 100 }) ) const markdown = blocksToMarkdown(blocksList as any) return { action: 'children', block_id: input.block_id, total_children: blocksList.length, markdown, blocks: blocksList } } case 'append': { if (!input.content) { throw new NotionMCPError('content required for append', 'VALIDATION_ERROR', 'Provide markdown content') } const blocksList = markdownToBlocks(input.content) await notion.blocks.children.append({ block_id: input.block_id, children: blocksList as any }) return { action: 'append', block_id: input.block_id, appended_count: blocksList.length } } case 'update': { if (!input.content) { throw new NotionMCPError('content required for update', 'VALIDATION_ERROR', 'Provide markdown content') } const block: any = await notion.blocks.retrieve({ block_id: input.block_id }) const blockType = block.type const newBlocks = markdownToBlocks(input.content) if (newBlocks.length === 0) { throw new NotionMCPError('Content must produce at least one block', 'VALIDATION_ERROR', 'Invalid markdown') } const newContent = newBlocks[0] const updatePayload: any = {} // Build update based on block type if ( [ 'paragraph', 'heading_1', 'heading_2', 'heading_3', 'bulleted_list_item', 'numbered_list_item', 'quote' ].includes(blockType) ) { updatePayload[blockType] = { rich_text: (newContent as any)[blockType]?.rich_text || [] } } else { throw new NotionMCPError( `Block type '${blockType}' cannot be updated`, 'VALIDATION_ERROR', 'Only text blocks can be updated' ) } await notion.blocks.update({ block_id: input.block_id, ...updatePayload } as any) return { action: 'update', block_id: input.block_id, type: blockType, updated: true } } case 'delete': { await notion.blocks.delete({ block_id: input.block_id }) return { action: 'delete', block_id: input.block_id, deleted: true } } default: throw new NotionMCPError( `Unknown action: ${input.action}`, 'VALIDATION_ERROR', 'Supported actions: get, children, append, update, delete' ) } })() }
• src/tools/registry.ts:125-142 (schema)

  Input schema for the 'blocks' tool defining actions, required block_id, and optional markdown content.
  { name: 'blocks', description: 'Block-level content: get, children, append, update, delete. Page IDs are valid block IDs. Use for precise edits.', inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['get', 'children', 'append', 'update', 'delete'], description: 'Action to perform' }, block_id: { type: 'string', description: 'Block ID' }, content: { type: 'string', description: 'Markdown content (for append/update)' } }, required: ['action', 'block_id'] } },
• src/tools/registry.ts:302-304 (registration)

  Registration of the 'blocks' tool handler in the main CallToolRequestSchema switch statement.
  case 'blocks': result = await blocks(notion, args as any) break
• src/tools/composite/blocks.ts:11-15 (schema)

  TypeScript interface defining the input parameters for the blocks handler.
  export interface BlocksInput { action: 'get' | 'children' | 'append' | 'update' | 'delete' block_id: string content?: string // Markdown format }
• src/tools/composite/blocks.ts:8-10 (helper)

  Imports of helper functions used in blocks handler: markdown conversion and pagination.
  import { blocksToMarkdown, markdownToBlocks } from '../helpers/markdown.js' import { autoPaginate } from '../helpers/pagination.js'