notion_retrieve_comments
Retrieve unresolved comments from Notion pages or blocks to track feedback and discussions. Supports JSON for data processing or Markdown for readability.
Instructions
Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| block_id | Yes | The ID of the block or page whose comments you want to retrieve.It should be a 32-character string (excluding hyphens) formatted as 8-4-4-4-12 with hyphens (-). | |
| start_cursor | No | If supplied, returns a page of results starting after the cursor. | |
| page_size | No | Number of comments to retrieve (max 100). | |
| format | No | Specify the response format. 'json' returns the original data structure, 'markdown' returns a more readable format. Use 'markdown' when the user only needs to read the page and isn't planning to write or modify it. Use 'json' when the user needs to read the page with the intention of writing to or modifying it. | markdown |
Implementation Reference
- src/client/index.ts:271-290 (handler)The core handler function in NotionClientWrapper that makes the Notion API GET request to retrieve comments for the specified block_id, with optional pagination.async retrieveComments( block_id: string, start_cursor?: string, page_size?: number ): Promise<ListResponse> { const params = new URLSearchParams(); params.append("block_id", block_id); if (start_cursor) params.append("start_cursor", start_cursor); if (page_size) params.append("page_size", page_size.toString()); const response = await fetch( `${this.baseUrl}/comments?${params.toString()}`, { method: "GET", headers: this.headers, } ); return response.json(); }
- src/types/schemas.ts:398-424 (schema)Defines the MCP Tool object with name, description, and inputSchema (JSON Schema) for the notion_retrieve_comments tool.export const retrieveCommentsTool: Tool = { name: "notion_retrieve_comments", description: "Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have 'read comment' capabilities.", inputSchema: { type: "object", properties: { block_id: { type: "string", description: "The ID of the block or page whose comments you want to retrieve." + commonIdDescription, }, start_cursor: { type: "string", description: "If supplied, returns a page of results starting after the cursor.", }, page_size: { type: "number", description: "Number of comments to retrieve (max 100).", }, format: formatParameter, }, required: ["block_id"], }, };
- src/server/index.ts:237-249 (registration)Switch case in CallToolRequest handler that validates arguments and delegates to the notionClient.retrieveComments method.case "notion_retrieve_comments": { const args = request.params .arguments as unknown as args.RetrieveCommentsArgs; if (!args.block_id) { throw new Error("Missing required argument: block_id"); } response = await notionClient.retrieveComments( args.block_id, args.start_cursor, args.page_size ); break; }
- src/server/index.ts:302-326 (registration)Registers the tool in the ListTools response by including retrieveCommentsTool in the allTools array.server.setRequestHandler(ListToolsRequestSchema, async () => { const allTools = [ schemas.appendBlockChildrenTool, schemas.retrieveBlockTool, schemas.retrieveBlockChildrenTool, schemas.deleteBlockTool, schemas.updateBlockTool, schemas.retrievePageTool, schemas.updatePagePropertiesTool, schemas.listAllUsersTool, schemas.retrieveUserTool, schemas.retrieveBotUserTool, schemas.createDatabaseTool, schemas.queryDatabaseTool, schemas.retrieveDatabaseTool, schemas.updateDatabaseTool, schemas.createDatabaseItemTool, schemas.createCommentTool, schemas.retrieveCommentsTool, schemas.searchTool, ]; return { tools: filterTools(allTools, enabledToolsSet), }; });
- src/types/args.ts:120-125 (schema)TypeScript interface defining the expected arguments for the tool, used for type casting in the server handler.export interface RetrieveCommentsArgs { block_id: string; start_cursor?: string; page_size?: number; format?: "json" | "markdown"; }