content_convert

Instructions

Implementation Reference

• src/tools/composite/content.ts:17-80 (handler)

  Main handler function for the content_convert tool. Converts between Markdown and Notion block JSON. Supports two directions: markdown-to-blocks (accepts a markdown string) and blocks-to-markdown (accepts a JSON array of Notion blocks or a JSON string). Delegates to markdownToBlocks() and blocksToMarkdown() from helpers/markdown.ts.

  export async function contentConvert(input: ContentConvertInput): Promise<any> {
    return withErrorHandling(async () => {
      switch (input.direction) {
        case 'markdown-to-blocks': {
          if (typeof input.content !== 'string') {
            throw new NotionMCPError(
              'Content must be a string for markdown-to-blocks',
              'VALIDATION_ERROR',
              'Provide a string content'
            )
          }
          const blocks = markdownToBlocks(input.content)
          return {
            direction: input.direction,
            block_count: blocks.length,
            blocks
          }
        }
  
        case 'blocks-to-markdown': {
          let content = input.content
          // Parse JSON string if needed
          if (typeof content === 'string') {
            try {
              content = JSON.parse(content)
            } catch {
              throw new NotionMCPError(
                'Content must be a valid JSON array or array object for blocks-to-markdown',
                'VALIDATION_ERROR',
                'Provide a valid JSON array or object'
              )
            }
          }
          if (!Array.isArray(content)) {
            throw new NotionMCPError(
              'Content must be an array for blocks-to-markdown',
              'VALIDATION_ERROR',
              'Provide an array content'
            )
          }
          if (!content.every((b) => typeof b === 'object' && b !== null)) {
            throw new NotionMCPError(
              'Content must be an array of objects for blocks-to-markdown',
              'VALIDATION_ERROR',
              'Provide an array of block objects'
            )
          }
          const markdown = blocksToMarkdown(content as any)
          return {
            direction: input.direction,
            char_count: markdown.length,
            markdown
          }
        }
  
        default:
          throw new NotionMCPError(
            `Unsupported direction: ${input.direction}`,
            'VALIDATION_ERROR',
            'Provide a valid direction'
          )
      }
    })()
  }

• src/tools/composite/content.ts:9-12 (schema)

  Input type definition for the content_convert tool. Defines ContentConvertInput interface with direction enum ('markdown-to-blocks' | 'blocks-to-markdown') and content (string | any[]).

  export interface ContentConvertInput {
    direction: 'markdown-to-blocks' | 'blocks-to-markdown'
    content: string | any[]
  }

• src/tools/registry.ts:306-329 (registration)

  Tool schema registration in the TOOLS array. Defines name 'content_convert', description, annotations, and inputSchema (direction enum + content string).

  {
    name: 'content_convert',
    description:
      'Convert between markdown and Notion block JSON. Directions: markdown-to-blocks (input: markdown string), blocks-to-markdown (input: JSON array of Notion blocks or JSON string). Most tools (pages, blocks) handle markdown automatically -- use this only for preview/validation. Supported markdown: headings, lists, to-do, code blocks, blockquotes, dividers, callouts (> [!NOTE]), toggles (<details>), tables, images, bookmarks, embeds, equations ($$), columns (:::columns), [toc], [breadcrumb]. Inline: **bold**, *italic*, `code`, ~~strike~~, [link](url).',
    annotations: {
      title: 'Content Convert',
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false
    },
    inputSchema: {
      type: 'object',
      properties: {
        direction: {
          type: 'string',
          enum: ['markdown-to-blocks', 'blocks-to-markdown'],
          description: 'Conversion direction'
        },
        content: { type: 'string', description: 'Content to convert (string or array/JSON string)' }
      },
      required: ['direction', 'content']
    }
  },

• src/tools/registry.ts:540-541 (registration)

  Handler dispatch in the CallToolRequestSchema switch statement. Routes 'content_convert' to the contentConvert() function (no notion client needed, unlike most tools).

  case 'content_convert':
    result = await contentConvert(args as any)

• src/tools/helpers/markdown.ts:444-455 (helper)

  blocksToMarkdown() - converts Notion block array to markdown string. Used by the blocks-to-markdown direction. Also markdownToBlocks() at line 246-249 converts markdown string to Notion block array for the reverse direction.

  export function blocksToMarkdown(blocks: NotionBlock[]): string {
    const lines: string[] = []
  
    for (const block of blocks) {
      const handler = BLOCK_HANDLERS[block.type]
      if (handler) {
        handler(block, lines)
      }
    }
  
    return lines.join('\n')
  }