Notion MCP Server

Implementation Reference

• src/lib/mcp-server.ts:736-779 (handler)

  MCP tool handler for 'list-comments': calls NotionService.listComments, handles pagination and errors, returns JSON-formatted results.

  async ({ page_id, block_id, start_cursor, page_size }) => {
    try {
      if (!page_id && !block_id) {
        return {
          content: [
            {
              type: "text",
              text: "Error: Either page_id or block_id must be provided",
            },
          ],
          isError: true,
        };
      }
  
      const result = await this.notionService.listComments({
        page_id,
        block_id,
        start_cursor,
        page_size,
      });
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      console.error("Error in list-comments tool:", error);
      return {
        content: [
          {
            type: "text",
            text: `Error: Failed to list comments - ${
              (error as Error).message
            }`,
          },
        ],
        isError: true,
      };
    }
  }

• src/lib/mcp-server.ts:719-735 (schema)

  Zod input schema defining parameters for the list-comments tool: page_id or block_id (optional), pagination options.

  {
    page_id: z
      .string()
      .optional()
      .describe("The ID of the page to get comments from"),
    block_id: z
      .string()
      .optional()
      .describe("The ID of the block to get comments from"),
    start_cursor: z.string().optional().describe("Pagination cursor"),
    page_size: z
      .number()
      .min(1)
      .max(100)
      .optional()
      .describe("Number of results to return (max 100)"),
  },

• src/lib/mcp-server.ts:717-780 (registration)

  Registration of the 'list-comments' tool on the MCP server within registerCommentTools().

  this.server.tool(
    "list-comments",
    {
      page_id: z
        .string()
        .optional()
        .describe("The ID of the page to get comments from"),
      block_id: z
        .string()
        .optional()
        .describe("The ID of the block to get comments from"),
      start_cursor: z.string().optional().describe("Pagination cursor"),
      page_size: z
        .number()
        .min(1)
        .max(100)
        .optional()
        .describe("Number of results to return (max 100)"),
    },
    async ({ page_id, block_id, start_cursor, page_size }) => {
      try {
        if (!page_id && !block_id) {
          return {
            content: [
              {
                type: "text",
                text: "Error: Either page_id or block_id must be provided",
              },
            ],
            isError: true,
          };
        }
  
        const result = await this.notionService.listComments({
          page_id,
          block_id,
          start_cursor,
          page_size,
        });
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (error) {
        console.error("Error in list-comments tool:", error);
        return {
          content: [
            {
              type: "text",
              text: `Error: Failed to list comments - ${
                (error as Error).message
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/lib/notion.ts:327-348 (helper)

  NotionService.listComments: core logic maps page_id/block_id to block_id and calls Notion SDK client.comments.list with pagination.

  async listComments(params: CommentQuery) {
    try {
      if (!params.page_id && !params.block_id) {
        throw new NotionAPIError(
          "Either page_id or block_id must be provided",
          "INVALID_REQUEST_PARAMETERS"
        );
      }
  
      // According to the Notion API docs, we should use block_id for both pages and blocks
      // Pages are technically blocks in Notion's data model
      const blockId = params.block_id || params.page_id;
  
      return await this.client.comments.list({
        block_id: blockId!, // Non-null assertion since we've checked above
        start_cursor: params.start_cursor,
        page_size: params.page_size,
      });
    } catch (error) {
      this.handleError(error);
    }
  }

• src/types/notion.ts:78-85 (schema)

  TypeScript type and Zod schema for CommentQuery parameters used in NotionService.listComments.

  export const CommentQuerySchema = z.object({
    block_id: z.string().optional(),
    page_id: z.string().optional(),
    start_cursor: z.string().optional(),
    page_size: z.number().min(1).max(100).optional(),
  });
  
  export type CommentQuery = z.infer<typeof CommentQuerySchema>;