notion-mcp-server

Instructions

Implementation Reference

• src/tools/batchMixedOperations.ts:6-68 (handler)

  The primary handler function for the batch_mixed_operations tool. It processes an array of mixed operations (append, update, delete) on Notion blocks, executes them sequentially using the Notion API, collects results, and returns a formatted response.

  export const batchMixedOperations = async (
    params: BatchMixedOperationsParams
  ): Promise<CallToolResult> => {
    try {
      const results = [];
      const operationCounts = {
        append: 0,
        update: 0,
        delete: 0,
      };
  
      for (const op of params.operations) {
        let response;
  
        switch (op.operation) {
          case "append":
            response = await notion.blocks.children.append({
              block_id: op.blockId,
              children: op.children,
            });
            operationCounts.append++;
            break;
  
          case "update":
            response = await notion.blocks.update({
              block_id: op.blockId,
              ...op.data,
            });
            operationCounts.update++;
            break;
  
          case "delete":
            response = await notion.blocks.delete({
              block_id: op.blockId,
            });
            operationCounts.delete++;
            break;
        }
  
        results.push({
          operation: op.operation,
          blockId: op.blockId,
          success: true,
          response,
        });
      }
  
      return {
        content: [
          {
            type: "text",
            text: `Successfully performed ${params.operations.length} operations (${operationCounts.append} append, ${operationCounts.update} update, ${operationCounts.delete} delete)`,
          },
          {
            type: "text",
            text: JSON.stringify(results, null, 2),
          },
        ],
      };
    } catch (error) {
      return handleNotionError(error);
    }
  };

• src/schema/blocks.ts:225-250 (schema)

  Zod schema defining the input parameters for batch_mixed_operations: an array of discriminated union operations supporting append (with blockId and children), update (with blockId and data), or delete (with blockId).

  export const BATCH_MIXED_OPERATIONS_SCHEMA = {
    operations: z
      .array(
        z.discriminatedUnion("operation", [
          z.object({
            operation: z.literal("append"),
            blockId: z
              .string()
              .describe("The ID of the block to append children to"),
            children: z
              .array(TEXT_BLOCK_REQUEST_SCHEMA)
              .describe("Array of blocks to append as children"),
          }),
          z.object({
            operation: z.literal("update"),
            blockId: z.string().describe("The ID of the block to update"),
            data: TEXT_BLOCK_REQUEST_SCHEMA.describe("The block data to update"),
          }),
          z.object({
            operation: z.literal("delete"),
            blockId: z.string().describe("The ID of the block to delete/archive"),
          }),
        ])
      )
      .describe("Array of mixed operations to perform in a single batch"),
  };

• src/tools/blocks.ts:34-35 (registration)

  Registration/dispatch logic within the 'notion_blocks' tool handler (registerBlocksOperationTool). Routes requests with action 'batch_mixed_operations' to the batchMixedOperations handler function.

  case "batch_mixed_operations":
    return batchMixedOperations(params.payload.params);

• src/schema/blocks.ts:312-319 (schema)

  Inclusion of batch_mixed_operations as an action in the overarching BLOCKS_OPERATION_SCHEMA for the 'notion_blocks' MCP tool.

  z.object({
    action: z
      .literal("batch_mixed_operations")
      .describe(
        "Use this action to perform batch mixed operations on blocks."
      ),
    params: z.object(BATCH_MIXED_OPERATIONS_SCHEMA),
  }),

• src/tools/index.ts:22-28 (registration)

  MCP tool registration for 'notion_blocks', which encompasses batch_mixed_operations as one of its dispatched actions via BLOCKS_OPERATION_SCHEMA and registerBlocksOperationTool.

  // Register combined blocks operation tool
  server.tool(
    "notion_blocks",
    "Perform various block operations (retrieve, update, delete, append children, batch operations)",
    BLOCKS_OPERATION_SCHEMA,
    registerBlocksOperationTool
  );