notion-mcp-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yaroslav Boiko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+# Notion MCP Server
+
+![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue)
+![Model Context Protocol](https://img.shields.io/badge/MCP-Enabled-purple)
+
+**Notion MCP Server** is a Model Context Protocol (MCP) server template for integrating with Notion's API. This boilerplate provides a starting point for building AI assistants that can interact with Notion.
+
+## 📑 Table of Contents
+
+- [Getting Started & Integration](#-getting-started--integration)
+  - [Setup Process](#setup-process)
+  - [Cursor Integration](#cursor-integration)
+  - [Claude Desktop Integration](#claude-desktop-integration)
+- [Features](#-features)
+- [Documentation](#-documentation)
+  - [Available Tools](#available-tools)
+  - [Available Resources](#available-resources)
+- [Development](#-development)
+- [Technical Details](#-technical-details)
+- [Troubleshooting](#-troubleshooting)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+## 🚀 Getting Started & Integration
+
+### Setup Process
+
+1. **Obtain a Notion API Key**
+   - Create an integration at [Notion Developers](https://www.notion.so/my-integrations)
+   - Copy your API key
+   
+2. **Enable Integration for Your Pages**
+   - Select an existing page or create a new one in Notion
+   - Click the "..." menu in the top right corner
+   - Go to "Connections" 
+   - Find and enable your integration from the list
+   
+   ![Notion Page Connection](page_connection.png)
+
+3. **Choose Your Integration Method**
+   - Follow one of the integration options below based on your preferred MCP client
+
+4. **Ask Your AI Assistant to Interact with Notion**
+   - "Create a new page with today's tasks"
+   - "Update my meeting notes in Notion"
+   - "Add bullet points to my meeting notes page"
+
+### Cursor Integration
+
+#### Method 1: Using mcp.json
+
+1. Create or edit the `.cursor/mcp.json` file in your project directory:
+
+```json
+{
+  "mcpServers": {
+    "notion-mcp-server": {
+      "command": "env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx",
+      "args": ["-y", "notion-mcp-server"]
+    }
+  }
+}
+```
+
+2. Replace `YOUR_KEY` and `YOUR_PAGE_ID` with your actual Notion API key and page ID
+3. Restart Cursor to apply the changes
+
+#### Method 2: Manual Mode
+
+1. Open Cursor and go to Settings
+2. Navigate to the "MCP" or "Model Context Protocol" section
+3. Click "Add Server" or equivalent
+4. Enter the following command in the appropriate field:
+
+```
+env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx -y notion-mcp-server
+```
+
+5. Replace `YOUR_KEY` and `YOUR_PAGE_ID` with your actual Notion API key and page ID
+6. Save the settings and restart Cursor if necessary
+
+### Claude Desktop Integration
+
+1. Create or edit the `mcp.json` file in your configuration directory:
+
+```json
+{
+  "mcpServers": {
+    "notion-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "notion-mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "YOUR_KEY",
+        "NOTION_PAGE_ID": "YOUR_PAGE_ID"
+      }
+    }
+  }
+}
+```
+
+2. Replace `YOUR_KEY` and `YOUR_PAGE_ID` with your actual Notion API key and page ID
+3. Restart Claude Desktop to apply the changes
+
+## 🌟 Features
+
+- **📝 Notion Integration** - Interact with Notion databases, pages, and blocks
+- **🔌 Universal MCP Compatibility** - Works with all MCP clients including Cursor, Claude Desktop, Cline, and Zed
+- **🔍 Data Retrieval** - Fetch information from Notion pages, blocks, and databases
+- **✏️ Content Creation** - Create and update Notion pages and blocks
+- **📊 Block Management** - Append, update, and delete blocks within Notion pages
+- **🔄 Batch Operations** - Perform multiple operations in a single request
+- **🗑️ Archive & Restore** - Archive and restore Notion pages
+- **🔎 Search Functionality** - Search Notion pages and databases by title
+
+## 📚 Documentation
+
+### Available Tools
+
+The server provides the following tools for interacting with Notion:
+
+#### Page Operations
+
+##### `create_page`
+Create a new page in Notion with specified content
+
+##### `archive_page`
+Archive (move to trash) a Notion page by ID
+
+##### `restore_page`
+Restore a previously archived Notion page by ID
+
+##### `search_pages`
+Search for pages and databases in Notion by title
+
+#### Block Operations
+
+##### `retrieve_block`
+Retrieve a block from Notion by ID
+
+##### `retrieve_block_children`
+Retrieve the children of a block from Notion
+
+##### `append_block_children`
+Append child blocks to a parent block in Notion
+
+##### `update_block`
+Update a block's content in Notion
+
+##### `delete_block`
+Delete (move to trash) a block in Notion
+
+#### Batch Operations
+
+##### `batch_append_block_children`
+Append children to multiple blocks in a single operation
+
+##### `batch_update_blocks`
+Update multiple blocks in a single operation
+
+##### `batch_delete_blocks`
+Delete multiple blocks in a single operation
+
+##### `batch_mixed_operations`
+Perform a mix of append, update, and delete operations in a single request
+
+### Available Resources
+
+The server currently does not expose any resources, focusing instead on tool-based operations.
+
+## 🛠 Development
+
+1. **Clone the Repository**
+   ```
+   git clone https://github.com/awkoy/notion-mcp-server.git
+   cd notion-mcp-server
+   ```
+
+2. **Install Dependencies**
+   ```
+   npm install
+   ```
+
+3. **Set Up Environment Variables**
+   - Create a `.env` file with:
+     ```
+     NOTION_TOKEN=your_notion_api_key
+     NOTION_PAGE_ID=your_notion_page_id
+     ```
+
+4. **Build the Project**
+   ```
+   npm run build
+   ```
+
+5. **Run the Inspector**
+   ```
+   npm run inspector
+   ```
+
+## 🔧 Technical Details
+
+- Built using TypeScript and the MCP SDK (version 1.7.0+)
+- Uses the official Notion API client (@notionhq/client v2.3.0+)
+- Follows the Model Context Protocol specification
+- Implements tools for CRUD operations on Notion pages and blocks
+- Supports efficient batch operations for performance optimization
+- Validates input/output with Zod schemas
+
+## ❓ Troubleshooting
+
+- **Common Issues**
+  - **Authentication Errors**: Ensure your Notion token has the correct permissions and integration is enabled for your pages/databases
+  - **Page Access Issues**: Make sure your integration has been added to the pages you're attempting to access
+  - **Rate Limiting**: Notion API has rate limits - use batch operations to optimize requests
+
+- **Getting Help**
+  - Create an issue on the [GitHub repository](https://github.com/awkoy/notion-mcp-server/issues)
+  - Check the [Notion API documentation](https://developers.notion.com/reference/intro)
+  - Visit the MCP community channels for assistance
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+

package/build/config/index.js

@@ -0,0 +1,5 @@
+// Configuration
+export const CONFIG = {
+    serverName: "notion-mcp-server",
+    serverVersion: "0.0.1",
+};

package/build/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { startServer } from "./server/index.js";
+import { registerAllTools } from "./tools/index.js";
+registerAllTools();
+async function main() {
+    try {
+        await startServer();
+    }
+    catch (error) {
+        console.error("Unhandled server error:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Unhandled server error:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/build/resources/imageList.js

@@ -0,0 +1,62 @@
+import { server } from "../server/index.js";
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { replicate } from "../services/replicate.js";
+import { urlToBase64 } from "../utils/image.js";
+import { CONFIG } from "../config/index.js";
+export const registerImageListResource = () => {
+    const list = async () => {
+        try {
+            const predictions = [];
+            for await (const page of replicate.paginate(replicate.predictions.list)) {
+                predictions.push(...page);
+            }
+            return {
+                resources: predictions
+                    .filter((prediction) => prediction.output?.length &&
+                    prediction.model === CONFIG.imageModelId)
+                    .map((prediction) => ({
+                    uri: `images://${prediction.id}`,
+                    name: `Image ${prediction.id}`,
+                    mimeType: "application/json",
+                    description: `Generated image by ${prediction.model} with id ${prediction.id}`,
+                })),
+                nextCursor: undefined,
+            };
+        }
+        catch (error) {
+            console.error("Error listing predictions:", error);
+            return {
+                resources: [],
+                nextCursor: undefined,
+            };
+        }
+    };
+    server.resource("images", new ResourceTemplate("images://{id}", {
+        list,
+    }), async (uri, { id }) => {
+        const prediction = await replicate.predictions.get(id);
+        if (!prediction.output?.length) {
+            return {
+                contents: [
+                    {
+                        name: "Not Found!",
+                        uri: uri.href,
+                        text: `Data has been removed by Replicate automatically after an hour, by default. You have to save your own copies before it is removed.`,
+                        mimeType: "text/plain",
+                    },
+                ],
+            };
+        }
+        const imageBase64 = await urlToBase64(prediction.output[0]);
+        return {
+            contents: [
+                {
+                    name: "image",
+                    uri: uri.href,
+                    blob: imageBase64,
+                    mimeType: "image/png",
+                },
+            ],
+        };
+    });
+};

package/build/resources/index.js

@@ -0,0 +1 @@
+export const registerAllResources = () => { };

package/build/resources/predictionList.js

@@ -0,0 +1,43 @@
+import { server } from "../server/index.js";
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { replicate } from "../services/replicate.js";
+export const registerPreditionListResource = () => {
+    const list = async () => {
+        try {
+            const predictions = [];
+            for await (const page of replicate.paginate(replicate.predictions.list)) {
+                predictions.push(...page);
+            }
+            return {
+                resources: predictions.map((prediction) => ({
+                    uri: `predictions://${prediction.id}`,
+                    name: `Prediction ${prediction.id}`,
+                    mimeType: "application/json",
+                })),
+                nextCursor: undefined,
+            };
+        }
+        catch (error) {
+            console.error("Error listing predictions:", error);
+            return {
+                resources: [],
+                nextCursor: undefined,
+            };
+        }
+    };
+    server.resource("predictions", new ResourceTemplate("predictions://{id}", {
+        list,
+    }), async (uri, { id }) => {
+        const prediction = await replicate.predictions.get(id);
+        return {
+            contents: [
+                {
+                    name: "prediction",
+                    uri: uri.href,
+                    text: JSON.stringify(prediction),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+};

package/build/resources/svgList.js

@@ -0,0 +1,69 @@
+// import { server } from "../server/index.js";
+// import {
+//   ListResourcesCallback,
+//   ResourceTemplate,
+// } from "@modelcontextprotocol/sdk/server/mcp.js";
+// import { replicate } from "../services/notion.js";
+// import { urlToSvg } from "../utils/image.js";
+// import { Prediction } from "replicate";
+// import { CONFIG } from "../config/index.js";
+export {};
+// export const registerSvgListResource = () => {
+//   const list: ListResourcesCallback = async () => {
+//     try {
+//       const predictions: Prediction[] = [];
+//       for await (const page of replicate.paginate(replicate.predictions.list)) {
+//         predictions.push(...page);
+//       }
+//       return {
+//         resources: predictions
+//           .filter((prediction) => prediction.model === CONFIG.svgModelId)
+//           .map((prediction) => ({
+//             uri: `svglist://${prediction.id}`,
+//             name: `SVG ${prediction.id}`,
+//             mimeType: "application/json",
+//             description: `Generated image by ${prediction.model} with id ${prediction.id}`,
+//           })),
+//         nextCursor: undefined,
+//       };
+//     } catch (error) {
+//       console.error("Error listing predictions:", error);
+//       return {
+//         resources: [],
+//         nextCursor: undefined,
+//       };
+//     }
+//   };
+//   server.resource(
+//     "svglist",
+//     new ResourceTemplate("svglist://{id}", {
+//       list,
+//     }),
+//     async (uri, { id }) => {
+//       const prediction = await replicate.predictions.get(id as string);
+//       if (!prediction.output) {
+//         return {
+//           contents: [
+//             {
+//               name: "Not Found!",
+//               uri: uri.href,
+//               text: `Data has been removed by Replicate automatically after an hour, by default. You have to save your own copies before it is removed.`,
+//               mimeType: "text/plain",
+//             },
+//           ],
+//         };
+//       }
+//       const svg = await urlToSvg(prediction.output);
+//       return {
+//         contents: [
+//           {
+//             name: "svglist",
+//             uri: uri.href,
+//             text: svg,
+//             mimeType: "image/svg+xml",
+//           },
+//         ],
+//       };
+//     }
+//   );
+// };

package/build/schema/annotations.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { COLOR_SCHEMA } from "./color.js";
+export const ANNOTATIONS_SCHEMA = z
+    .object({
+    bold: z.boolean().optional().describe("Whether text is bold"),
+    italic: z.boolean().optional().describe("Whether text is italic"),
+    strikethrough: z
+        .boolean()
+        .optional()
+        .describe("Whether text has strikethrough"),
+    underline: z.boolean().optional().describe("Whether text is underlined"),
+    code: z.boolean().optional().describe("Whether text is code formatted"),
+    color: COLOR_SCHEMA.optional().describe("Color of the text"),
+})
+    .describe("Text formatting annotations");

package/build/schema/blocks.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { COLOR_SCHEMA } from "./color.js";
+import { ICON_SCHEMA } from "./icon.js";
+import { RICH_TEXT_ITEM_REQUEST_SCHEMA } from "./rich-text.js";
+import { preprocessJson } from "./preprocess.js";
+import { LANGUAGE_SCHEMA } from "./lang.js";
+import { FILE_SCHEMA } from "./file.js";
+export const BASE_BLOCK_REQUEST_SCHEMA = z.object({
+    type: z.string().describe("Type of block"),
+    object: z.literal("block").optional().describe("Object type identifier"),
+    created_time: z
+        .string()
+        .optional()
+        .describe("ISO timestamp of block creation"),
+    last_edited_time: z
+        .string()
+        .optional()
+        .describe("ISO timestamp of last edit"),
+    has_children: z
+        .boolean()
+        .optional()
+        .describe("Whether block has child blocks"),
+    archived: z.boolean().optional().describe("Whether block is archived"),
+});
+export const TEXT_BLOCK_BASE_REQUEST_SCHEMA = z.object({
+    rich_text: z
+        .array(RICH_TEXT_ITEM_REQUEST_SCHEMA)
+        .describe("Array of rich text content"),
+    color: COLOR_SCHEMA.optional().describe("Color of the block"),
+});
+export const PARAGRAPH_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("paragraph").describe("Paragraph block type"),
+    paragraph: TEXT_BLOCK_BASE_REQUEST_SCHEMA.describe("Paragraph block content"),
+});
+export const HEADING1_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("heading_1").describe("Heading 1 block type"),
+    heading_1: TEXT_BLOCK_BASE_REQUEST_SCHEMA.extend({
+        is_toggleable: z
+            .boolean()
+            .optional()
+            .describe("Whether heading can be toggled"),
+    }).describe("Heading 1 block content"),
+});
+export const HEADING2_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("heading_2").describe("Heading 2 block type"),
+    heading_2: TEXT_BLOCK_BASE_REQUEST_SCHEMA.extend({
+        is_toggleable: z
+            .boolean()
+            .optional()
+            .describe("Whether heading can be toggled"),
+    }).describe("Heading 2 block content"),
+});
+export const HEADING3_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("heading_3").describe("Heading 3 block type"),
+    heading_3: TEXT_BLOCK_BASE_REQUEST_SCHEMA.extend({
+        is_toggleable: z
+            .boolean()
+            .optional()
+            .describe("Whether heading can be toggled"),
+    }).describe("Heading 3 block content"),
+});
+export const QUOTE_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("quote").describe("Quote block type"),
+    quote: TEXT_BLOCK_BASE_REQUEST_SCHEMA.describe("Quote block content"),
+});
+export const CALLOUT_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("callout").describe("Callout block type"),
+    callout: TEXT_BLOCK_BASE_REQUEST_SCHEMA.extend({
+        icon: ICON_SCHEMA.optional().describe("Icon for the callout"),
+    }).describe("Callout block content"),
+});
+export const TOGGLE_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("toggle").describe("Toggle block type"),
+    toggle: TEXT_BLOCK_BASE_REQUEST_SCHEMA.describe("Toggle block content"),
+});
+export const BULLETED_LIST_ITEM_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z
+        .literal("bulleted_list_item")
+        .describe("Bulleted list item block type"),
+    bulleted_list_item: TEXT_BLOCK_BASE_REQUEST_SCHEMA.describe("Bulleted list item block content"),
+});
+export const NUMBERED_LIST_ITEM_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z
+        .literal("numbered_list_item")
+        .describe("Numbered list item block type"),
+    numbered_list_item: TEXT_BLOCK_BASE_REQUEST_SCHEMA.describe("Numbered list item block content"),
+});
+export const TO_DO_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("to_do").describe("To-do block type"),
+    to_do: TEXT_BLOCK_BASE_REQUEST_SCHEMA.extend({
+        checked: z.boolean().optional().describe("Whether the to-do is checked"),
+    }).describe("To-do block content"),
+});
+export const CODE_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("code").describe("Code block type"),
+    code: TEXT_BLOCK_BASE_REQUEST_SCHEMA.extend({
+        language: LANGUAGE_SCHEMA,
+    }).describe("Code block content"),
+});
+export const DIVIDER_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("divider").describe("Divider block type"),
+    divider: z.object({}).describe("Divider block content"),
+});
+export const IMAGE_BLOCK_REQUEST_SCHEMA = BASE_BLOCK_REQUEST_SCHEMA.extend({
+    type: z.literal("image").describe("Image block type"),
+    image: z
+        .object({
+        ...FILE_SCHEMA.shape,
+        caption: z
+            .array(RICH_TEXT_ITEM_REQUEST_SCHEMA)
+            .optional()
+            .describe("Image caption"),
+    })
+        .describe("Image block content"),
+});
+export const TEXT_BLOCK_REQUEST_SCHEMA = z.preprocess(preprocessJson, z
+    .discriminatedUnion("type", [
+    PARAGRAPH_BLOCK_REQUEST_SCHEMA,
+    HEADING1_BLOCK_REQUEST_SCHEMA,
+    HEADING2_BLOCK_REQUEST_SCHEMA,
+    HEADING3_BLOCK_REQUEST_SCHEMA,
+    QUOTE_BLOCK_REQUEST_SCHEMA,
+    CALLOUT_BLOCK_REQUEST_SCHEMA,
+    TOGGLE_BLOCK_REQUEST_SCHEMA,
+    BULLETED_LIST_ITEM_BLOCK_REQUEST_SCHEMA,
+    NUMBERED_LIST_ITEM_BLOCK_REQUEST_SCHEMA,
+    TO_DO_BLOCK_REQUEST_SCHEMA,
+    CODE_BLOCK_REQUEST_SCHEMA,
+    DIVIDER_BLOCK_REQUEST_SCHEMA,
+    IMAGE_BLOCK_REQUEST_SCHEMA,
+])
+    .describe("Union of all possible text block request types"));
+export const APPEND_BLOCK_CHILDREN_SCHEMA = {
+    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"),
+};
+export const RETRIEVE_BLOCK_SCHEMA = {
+    blockId: z.string().describe("The ID of the block to retrieve"),
+};
+export const RETRIEVE_BLOCK_CHILDREN_SCHEMA = {
+    blockId: z.string().describe("The ID of the block to retrieve children for"),
+    start_cursor: z.string().optional().describe("Cursor for pagination"),
+    page_size: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Number of results to return (1-100)"),
+};
+export const UPDATE_BLOCK_SCHEMA = {
+    blockId: z.string().describe("The ID of the block to update"),
+    data: TEXT_BLOCK_REQUEST_SCHEMA.describe("The block data to update"),
+};
+export const DELETE_BLOCK_SCHEMA = {
+    blockId: z.string().describe("The ID of the block to delete/archive"),
+};
+// Batch operation schemas for multiple blocks
+export const BATCH_APPEND_BLOCK_CHILDREN_SCHEMA = {
+    operations: z
+        .array(z.object({
+        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"),
+    }))
+        .describe("Array of append operations to perform in a single batch"),
+};
+export const BATCH_UPDATE_BLOCKS_SCHEMA = {
+    operations: z
+        .array(z.object({
+        blockId: z.string().describe("The ID of the block to update"),
+        data: TEXT_BLOCK_REQUEST_SCHEMA.describe("The block data to update"),
+    }))
+        .describe("Array of update operations to perform in a single batch"),
+};
+export const BATCH_DELETE_BLOCKS_SCHEMA = {
+    blockIds: z
+        .array(z.string().describe("The ID of a block to delete/archive"))
+        .describe("Array of block IDs to delete in a single batch"),
+};
+// Schema for multi-operation batches (mixed operations)
+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"),
+};