Better Notion MCP

Instructions

Implementation Reference

• src/tools/composite/comments.ts:21-86 (handler)

  The main handler function commentsManage that executes the tool logic for listing comments on a page or creating new comments/replies.

  export async function commentsManage(notion: Client, input: CommentsManageInput): Promise<any> {
    return withErrorHandling(async () => {
      switch (input.action) {
        case 'list': {
          if (!input.page_id) {
            throw new Error('page_id required for list action')
          }
  
          const comments = await autoPaginate(async (cursor) => {
            return await (notion.comments as any).list({
              block_id: input.page_id,
              start_cursor: cursor
            })
          })
  
          return {
            page_id: input.page_id,
            total_comments: comments.length,
            comments: comments.map((comment: any) => ({
              id: comment.id,
              created_time: comment.created_time,
              created_by: comment.created_by,
              discussion_id: comment.discussion_id,
              text: RichText.extractPlainText(comment.rich_text),
              parent: comment.parent
            }))
          }
        }
  
        case 'create': {
          if (!input.content) {
            throw new Error('content required for create action')
          }
  
          // Either page_id or discussion_id must be provided
          if (!input.page_id && !input.discussion_id) {
            throw new Error('Either page_id or discussion_id is required for create action')
          }
  
          const createParams: any = {
            rich_text: [RichText.text(input.content)]
          }
  
          // Add parent or discussion_id based on input
          if (input.discussion_id) {
            createParams.discussion_id = input.discussion_id
          } else {
            createParams.parent = {
              page_id: input.page_id
            }
          }
  
          const comment = await (notion.comments as any).create(createParams)
  
          return {
            comment_id: comment.id,
            discussion_id: comment.discussion_id,
            created: true
          }
        }
  
        default:
          throw new Error(`Unsupported action: ${input.action}`)
      }
    })()
  }

• src/tools/composite/comments.ts:11-16 (schema)

  TypeScript interface defining the input schema for the comments tool.

  export interface CommentsManageInput {
    page_id?: string
    discussion_id?: string
    action: 'list' | 'create'
    content?: string // For create action
  }

• src/tools/registry.ts:190-203 (registration)

  MCP tool registration including name, description, and inputSchema for the 'comments' tool.

  {
    name: 'comments',
    description: 'Comments: list, create. Use page_id for new discussion, discussion_id for replies.',
    inputSchema: {
      type: 'object',
      properties: {
        page_id: { type: 'string', description: 'Page ID' },
        discussion_id: { type: 'string', description: 'Discussion ID (for replies)' },
        action: { type: 'string', enum: ['list', 'create'], description: 'Action to perform' },
        content: { type: 'string', description: 'Comment content (for create)' }
      },
      required: ['action']
    }
  },

• src/tools/registry.ts:311-312 (registration)

  Dispatch case in the tool call handler that invokes the commentsManage function.

  case 'comments':
    result = await commentsManage(notion, args as any)

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

  Import statement for the comments handler function.

  import { commentsManage } from './composite/comments.js'