Notion MCP Server

Implementation Reference

• src/lib/mcp-server.ts:377-406 (handler)

  The main handler function for the 'append-blocks' tool. It parses the JSON string of child blocks and delegates to NotionService.appendBlockChildren to perform the append operation, then formats the result or error for the MCP response.

    async ({ block_id, children }) => {
      try {
        const result = await this.notionService.appendBlockChildren({
          block_id,
          children: JSON.parse(children),
        });
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (error) {
        console.error("Error in append-blocks tool:", error);
        return {
          content: [
            {
              type: "text",
              text: `Error: Failed to append blocks - ${
                (error as Error).message
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/lib/mcp-server.ts:373-376 (schema)

  Zod input schema for the 'append-blocks' tool, defining block_id as string and children as JSON string.

  {
    block_id: z.string().describe("The ID of the block to append to"),
    children: z.string().describe("JSON string of blocks to append"),
  },

• src/lib/mcp-server.ts:371-407 (registration)

  Registration of the 'append-blocks' tool using this.server.tool(), including name, schema, and handler function.

  this.server.tool(
    "append-blocks",
    {
      block_id: z.string().describe("The ID of the block to append to"),
      children: z.string().describe("JSON string of blocks to append"),
    },
    async ({ block_id, children }) => {
      try {
        const result = await this.notionService.appendBlockChildren({
          block_id,
          children: JSON.parse(children),
        });
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      } catch (error) {
        console.error("Error in append-blocks tool:", error);
        return {
          content: [
            {
              type: "text",
              text: `Error: Failed to append blocks - ${
                (error as Error).message
              }`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/lib/notion.ts:212-221 (helper)

  NotionService helper method that implements the core logic by calling the Notion SDK's blocks.children.append API.

  async appendBlockChildren(params: BlockChildren) {
    try {
      return await this.client.blocks.children.append({
        block_id: params.block_id,
        children: params.children,
      });
    } catch (error) {
      this.handleError(error);
    }
  }

• src/types/notion.ts:50-55 (schema)

  TypeScript type and Zod schema for BlockChildren parameters used in NotionService.appendBlockChildren.

  export const BlockChildrenSchema = z.object({
    block_id: z.string(),
    children: z.array(z.any()),
  });
  
  export type BlockChildren = z.infer<typeof BlockChildrenSchema>;