roam-research-mcp 0.27.0 → 0.30.1

package/README.md

@@ -105,22 +105,154 @@ The server provides powerful tools for interacting with Roam Research:
 
 1. `roam_fetch_page_by_title`: Fetch page content by title.
 2. `roam_create_page`: Create new pages with optional content and headings.
-3. `roam_create_block`: Add new blocks to an existing page or today's daily note.
-4. `roam_import_markdown`: Import nested markdown content under a specific block.
-5. `roam_add_todo`: Add a list of todo items to today's daily page.
-6. `roam_create_outline`: Add a structured outline to an existing page or block.
-7. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
-8. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
-9. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight).
-10. `roam_search_by_text`: Search for blocks containing specific text.
-11. `roam_update_block`: Update a single block identified by its UID.
-12. `roam_update_multiple_blocks`: Efficiently update multiple blocks in a single batch operation.
-13. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
-14. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
-15. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.
-16. `roam_remember`: Add a memory or piece of information to remember.
-17. `roam_recall`: Retrieve all stored memories.
-18. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph beyond the available search tools.
+3. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
+4. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
+5. `roam_create_outline`: Add a structured outline to an existing page or block, with support for `children_view_type`. (Internally uses `roam_process_batch_actions`.)
+6. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
+7. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
+8. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight).
+9. `roam_search_by_text`: Search for blocks containing specific text.
+10. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
+11. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
+12. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.
+13. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
+14. `roam_recall`: Retrieve all stored memories.
+15. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph beyond the available search tools.
+16. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch.
+
+**Deprecated Tools**:
+The following tools have been deprecated as of `v.0.30.0` in favor of the more powerful and flexible `roam_process_batch_actions`:
+
+- `roam_create_block`: Use `roam_process_batch_actions` with the `create-block` action.
+- `roam_update_block`: Use `roam_process_batch_actions` with the `update-block` action.
+- `roam_update_multiple_blocks`: Use `roam_process_batch_actions` with multiple `update-block` actions.
+
+### Important Considerations for Tool Usage
+
+When making changes to your Roam graph, precision in your requests is crucial for achieving desired outcomes.
+
+**Specificity in Requests:**
+Some tools allow for identifying blocks or pages by their text content (e.g., `parent_string`, `title`). While convenient, using **Unique Identifiers (UIDs)** is always preferred for accuracy and reliability. Text-based matching can be prone to errors if there are multiple blocks with similar content or if the content changes. Tools are designed to work best when provided with explicit UIDs where available.
+
+**Example of Specificity:**
+Instead of:
+`"parent_string": "My project notes"`
+
+Prefer:
+`"parent_uid": "((some-unique-uid))"`
+
+**Migrating from Deprecated Tools:**
+The following examples demonstrate how to achieve the functionality of the deprecated tools using `roam_process_batch_actions`.
+
+**1. Replacing `roam_create_block`:**
+
+- **Old (Deprecated):**
+  ```json
+  {
+    "tool_name": "roam_create_block",
+    "arguments": {
+      "content": "New block content",
+      "page_uid": "((page-uid))"
+    }
+  }
+  ```
+- **New (Recommended):**
+  ```json
+  {
+    "tool_name": "roam_process_batch_actions",
+    "arguments": {
+      "actions": [
+        {
+          "action": "create-block",
+          "location": {
+            "parent-uid": "((page-uid))",
+            "order": "last"
+          },
+          "block": {
+            "string": "New block content"
+          }
+        }
+      ]
+    }
+  }
+  ```
+
+**2. Replacing `roam_update_block`:**
+
+- **Old (Deprecated):**
+  ```json
+  {
+    "tool_name": "roam_update_block",
+    "arguments": {
+      "block_uid": "((block-uid))",
+      "content": "Updated block content"
+    }
+  }
+  ```
+- **New (Recommended):**
+  ```json
+  {
+    "tool_name": "roam_process_batch_actions",
+    "arguments": {
+      "actions": [
+        {
+          "action": "update-block",
+          "uid": "((block-uid))",
+          "string": "Updated block content"
+        }
+      ]
+    }
+  }
+  ```
+
+**3. Replacing `roam_update_multiple_blocks`:**
+
+- **Old (Deprecated):**
+  ```json
+  {
+    "tool_name": "roam_update_multiple_blocks",
+    "arguments": {
+      "updates": [
+        {
+          "block_uid": "((block-uid-1))",
+          "content": "Content for block 1"
+        },
+        {
+          "block_uid": "((block-uid-2))",
+          "transform": {
+            "find": "old text",
+            "replace": "new text"
+          }
+        }
+      ]
+    }
+  }
+  ```
+- **New (Recommended):**
+  ```json
+  {
+    "tool_name": "roam_process_batch_actions",
+    "arguments": {
+      "actions": [
+        {
+          "action": "update-block",
+          "uid": "((block-uid-1))",
+          "string": "Content for block 1"
+        },
+        {
+          "action": "update-block",
+          "uid": "((block-uid-2))",
+          "string": "((block-content-with-new-text))"
+          // Note: Transformations (find/replace) must be handled by the client
+          // before sending the 'string' to roam_process_batch_actions.
+        }
+      ]
+    }
+  }
+  ```
+
+**Caveat Regarding Heading Formatting:**
+Please note that while the `roam_process_batch_actions` tool can set block headings (H1, H2, H3), directly **removing** an existing heading (i.e., reverting a heading block to a plain text block) through this tool is not currently supported by the Roam API. The `heading` attribute persists its value once set, and attempting to remove it by setting `heading` to `0`, `null`, or omitting the property will not unset the heading.
 
 ## Setup
 

package/build/markdown-utils.js

@@ -284,7 +284,8 @@ function convertToRoamActions(nodes, parentUid, order = 'last') {
                 block: {
                     uid: block.uid,
                     string: block.content,
-                    ...(block.heading_level && { heading: block.heading_level })
+                    ...(block.heading_level && { heading: block.heading_level }),
+                    ...(block.children_view_type && { 'children-view-type': block.children_view_type })
                 }
             };
             actions.push(action);

package/build/server/roam-server.js

@@ -11,6 +11,7 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
+import { findAvailablePort } from '../utils/net.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read package.json to get the version
@@ -72,13 +73,6 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'roam_create_block': {
-                        const { content, page_uid, title, heading } = request.params.arguments;
-                        const result = await this.toolHandlers.createBlock(content, page_uid, title, heading);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
-                    }
                     case 'roam_import_markdown': {
                         const { content, page_uid, page_title, parent_uid, parent_string, order = 'first' } = request.params.arguments;
                         const result = await this.toolHandlers.importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order);
@@ -153,27 +147,6 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'roam_update_block': {
-                        const { block_uid, content, transform_pattern } = request.params.arguments;
-                        // Validate that either content or transform_pattern is provided, but not both or neither
-                        if ((!content && !transform_pattern) || (content && transform_pattern)) {
-                            throw new McpError(ErrorCode.InvalidRequest, 'Either content or transform_pattern must be provided, but not both or neither');
-                        }
-                        let result;
-                        if (content) {
-                            result = await this.toolHandlers.updateBlock(block_uid, content);
-                        }
-                        else {
-                            // We know transform_pattern exists due to validation above
-                            result = await this.toolHandlers.updateBlock(block_uid, undefined, (currentContent) => {
-                                const regex = new RegExp(transform_pattern.find, transform_pattern.global !== false ? 'g' : '');
-                                return currentContent.replace(regex, transform_pattern.replace);
-                            });
-                        }
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
-                    }
                     case 'roam_recall': {
                         const { sort_by = 'newest', filter_tag } = request.params.arguments;
                         const result = await this.toolHandlers.recall(sort_by, filter_tag);
@@ -181,22 +154,16 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'roam_update_multiple_blocks': {
-                        const { updates } = request.params.arguments;
-                        // Validate that for each update, either content or transform is provided, but not both or neither
-                        for (const update of updates) {
-                            if ((!update.content && !update.transform) || (update.content && update.transform)) {
-                                throw new McpError(ErrorCode.InvalidRequest, 'For each update, either content or transform must be provided, but not both or neither');
-                            }
-                        }
-                        const result = await this.toolHandlers.updateBlocks(updates);
+                    case 'roam_datomic_query': {
+                        const { query, inputs } = request.params.arguments;
+                        const result = await this.toolHandlers.executeDatomicQuery({ query, inputs });
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'roam_datomic_query': {
-                        const { query, inputs } = request.params.arguments;
-                        const result = await this.toolHandlers.executeDatomicQuery({ query, inputs });
+                    case 'roam_process_batch_actions': {
+                        const { actions } = request.params.arguments;
+                        const result = await this.toolHandlers.processBatch(actions);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
@@ -256,8 +223,9 @@ export class RoamServer {
                     }
                 }
             });
-            httpServer.listen(parseInt(HTTP_STREAM_PORT), () => {
-                // console.log(`MCP Roam Research server running HTTP Stream on port ${HTTP_STREAM_PORT}`);
+            const availableHttpPort = await findAvailablePort(parseInt(HTTP_STREAM_PORT));
+            httpServer.listen(availableHttpPort, () => {
+                // console.log(`MCP Roam Research server running HTTP Stream on port ${availableHttpPort}`);
             });
             // SSE Server setup
             const sseMcpServer = new Server({
@@ -318,8 +286,9 @@ export class RoamServer {
                     }
                 }
             });
-            sseHttpServer.listen(parseInt(SSE_PORT), () => {
-                // console.log(`MCP Roam Research server running SSE on port ${SSE_PORT}`);
+            const availableSsePort = await findAvailablePort(parseInt(SSE_PORT));
+            sseHttpServer.listen(availableSsePort, () => {
+                // console.log(`MCP Roam Research server running SSE on port ${availableSsePort}`);
             });
         }
         catch (error) {

package/build/tools/operations/batch.js

@@ -0,0 +1,37 @@
+import { batchActions as roamBatchActions } from '@roam-research/roam-api-sdk';
+export class BatchOperations {
+    constructor(graph) {
+        this.graph = graph;
+    }
+    async processBatch(actions) {
+        const batchActions = actions.map(action => {
+            const { action: actionType, ...rest } = action;
+            const roamAction = { action: actionType };
+            if (rest.location) {
+                roamAction.location = {
+                    'parent-uid': rest.location['parent-uid'],
+                    order: rest.location.order,
+                };
+            }
+            const block = {};
+            if (rest.string)
+                block.string = rest.string;
+            if (rest.uid)
+                block.uid = rest.uid;
+            if (rest.open !== undefined)
+                block.open = rest.open;
+            if (rest.heading !== undefined && rest.heading !== null && rest.heading !== 0) {
+                block.heading = rest.heading;
+            }
+            if (rest['text-align'])
+                block['text-align'] = rest['text-align'];
+            if (rest['children-view-type'])
+                block['children-view-type'] = rest['children-view-type'];
+            if (Object.keys(block).length > 0) {
+                roamAction.block = block;
+            }
+            return roamAction;
+        });
+        return await roamBatchActions(this.graph, { actions: batchActions });
+    }
+}

package/build/tools/operations/memory.js

@@ -1,4 +1,4 @@
-import { q, createBlock, createPage } from '@roam-research/roam-api-sdk';
+import { q, createPage, batchActions } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { resolveRefs } from '../helpers/refs.js';
@@ -49,18 +49,27 @@ export class MemoryOperations {
         }).join(' ') || '';
         // Create block with memory, memories tag, and optional categories
         const blockContent = `${memoriesTag} ${memory} ${categoryTags}`.trim();
-        try {
-            await createBlock(this.graph, {
+        const actions = [{
                 action: 'create-block',
                 location: {
-                    "parent-uid": pageUid,
-                    "order": "last"
+                    'parent-uid': pageUid,
+                    order: 'last'
                 },
-                block: { string: blockContent }
+                block: {
+                    string: blockContent
+                }
+            }];
+        try {
+            const result = await batchActions(this.graph, {
+                action: 'batch-actions',
+                actions
             });
+            if (!result) {
+                throw new McpError(ErrorCode.InternalError, 'Failed to create memory block via batch action');
+            }
         }
         catch (error) {
-            throw new McpError(ErrorCode.InternalError, 'Failed to create memory block');
+            throw new McpError(ErrorCode.InternalError, `Failed to create memory block: ${error instanceof Error ? error.message : String(error)}`);
         }
         return { success: true };
     }

package/build/tools/operations/outline.js

@@ -1,4 +1,4 @@
-import { q, createPage, createBlock, batchActions } from '@roam-research/roam-api-sdk';
+import { q, createPage, batchActions } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { capitalizeWords } from '../helpers/text.js';
@@ -138,15 +138,21 @@ export class OutlineOperations {
                 }
                 for (let retry = 0; retry < maxRetries; retry++) {
                     console.log(`Attempt ${retry + 1}/${maxRetries} to create block "${content}" under "${parentUid}"`);
-                    // Create block
-                    const success = await createBlock(this.graph, {
-                        action: 'create-block',
-                        location: {
-                            'parent-uid': parentUid,
-                            order: 'last'
-                        },
-                        block: { string: content }
+                    // Create block using batchActions
+                    const batchResult = await batchActions(this.graph, {
+                        action: 'batch-actions',
+                        actions: [{
+                                action: 'create-block',
+                                location: {
+                                    'parent-uid': parentUid,
+                                    order: 'last'
+                                },
+                                block: { string: content }
+                            }]
                     });
+                    if (!batchResult) {
+                        throw new McpError(ErrorCode.InternalError, `Failed to create block "${content}" via batch action`);
+                    }
                     // Wait with exponential backoff
                     const delay = initialDelay * Math.pow(2, retry);
                     await new Promise(resolve => setTimeout(resolve, delay));
@@ -232,7 +238,13 @@ export class OutlineOperations {
             // Convert to Roam markdown format
             const convertedContent = convertToRoamMarkdown(markdownContent);
             // Parse markdown into hierarchical structure
-            const nodes = parseMarkdown(convertedContent);
+            // We pass the original OutlineItem properties (heading, children_view_type)
+            // along with the parsed content to the nodes.
+            const nodes = parseMarkdown(convertedContent).map((node, index) => ({
+                ...node,
+                ...(validOutline[index].heading && { heading_level: validOutline[index].heading }),
+                ...(validOutline[index].children_view_type && { children_view_type: validOutline[index].children_view_type })
+            }));
             // Convert nodes to batch actions
             const actions = convertToRoamActions(nodes, targetParentUid, 'first');
             if (actions.length === 0) {
@@ -350,19 +362,26 @@ export class OutlineOperations {
             };
         }
         else {
-            // Create a simple block for non-nested content
-            try {
-                await createBlock(this.graph, {
+            // Create a simple block for non-nested content using batchActions
+            const actions = [{
                     action: 'create-block',
                     location: {
                         "parent-uid": targetParentUid,
                         order
                     },
                     block: { string: content }
+                }];
+            try {
+                const result = await batchActions(this.graph, {
+                    action: 'batch-actions',
+                    actions
                 });
+                if (!result) {
+                    throw new McpError(ErrorCode.InternalError, 'Failed to create content block via batch action');
+                }
             }
             catch (error) {
-                throw new McpError(ErrorCode.InternalError, 'Failed to create content block');
+                throw new McpError(ErrorCode.InternalError, `Failed to create content block: ${error instanceof Error ? error.message : String(error)}`);
             }
             return {
                 success: true,

package/build/tools/operations/todos.js

@@ -1,4 +1,4 @@
-import { q, createBlock, createPage, batchActions } from '@roam-research/roam-api-sdk';
+import { q, createPage, batchActions } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 export class TodoOperations {
@@ -37,44 +37,23 @@ export class TodoOperations {
                 throw new Error('Failed to create today\'s page');
             }
         }
-        // If more than 10 todos, use batch actions
         const todo_tag = "{{TODO}}";
-        if (todos.length > 10) {
-            const actions = todos.map((todo, index) => ({
-                action: 'create-block',
-                location: {
-                    'parent-uid': targetPageUid,
-                    order: index
-                },
-                block: {
-                    string: `${todo_tag} ${todo}`
-                }
-            }));
-            const result = await batchActions(this.graph, {
-                action: 'batch-actions',
-                actions
-            });
-            if (!result) {
-                throw new Error('Failed to create todo blocks');
-            }
-        }
-        else {
-            // Create todos sequentially
-            for (const todo of todos) {
-                try {
-                    await createBlock(this.graph, {
-                        action: 'create-block',
-                        location: {
-                            "parent-uid": targetPageUid,
-                            "order": "last"
-                        },
-                        block: { string: `${todo_tag} ${todo}` }
-                    });
-                }
-                catch (error) {
-                    throw new Error('Failed to create todo block');
-                }
+        const actions = todos.map((todo, index) => ({
+            action: 'create-block',
+            location: {
+                'parent-uid': targetPageUid,
+                order: index
+            },
+            block: {
+                string: `${todo_tag} ${todo}`
             }
+        }));
+        const result = await batchActions(this.graph, {
+            action: 'batch-actions',
+            actions
+        });
+        if (!result) {
+            throw new Error('Failed to create todo blocks');
         }
         return { success: true };
     }

package/build/tools/schemas.js

@@ -78,34 +78,6 @@ export const toolSchemas = {
             required: ['title'],
         },
     },
-    roam_create_block: {
-        name: 'roam_create_block',
-        description: 'Add new block to an existing Roam page. If no page specified, adds to today\'s daily note. Best for capturing immediate thoughts, additions to discussions, or content that doesn\'t warrant its own page. Can specify page by title or UID.\nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                content: {
-                    type: 'string',
-                    description: 'Content of the block',
-                },
-                page_uid: {
-                    type: 'string',
-                    description: 'Optional: UID of the page to add block to',
-                },
-                title: {
-                    type: 'string',
-                    description: 'Optional: Title of the page to add block to (defaults to today\'s date if neither page_uid nor title provided)',
-                },
-                heading: {
-                    type: 'integer',
-                    description: 'Optional: Heading formatting for this block (1-3)',
-                    minimum: 1,
-                    maximum: 3
-                }
-            },
-            required: ['content'],
-        },
-    },
     roam_create_outline: {
         name: 'roam_create_outline',
         description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. Best for:\n- Adding supplementary structured content to existing pages\n- Creating temporary or working outlines (meeting notes, brainstorms)\n- Organizing thoughts or research under a specific topic\n- Breaking down subtopics or components of a larger concept',
@@ -114,11 +86,11 @@ export const toolSchemas = {
             properties: {
                 page_title_uid: {
                     type: 'string',
-                    description: 'Title (or UID if known) of the page. Leave blank to use the default daily page'
+                    description: 'Title or UID of the page (UID is preferred for accuracy). Leave blank to use the default daily page.'
                 },
                 block_text_uid: {
                     type: 'string',
-                    description: 'A relevant title heading for the outline (or UID, if known) of the block under which outline content will be nested. If blank, content will be nested directly under the page. This can be either the text content of the block or its UID.'
+                    description: 'The text content or UID of the block to nest the outline under (UID is preferred for accuracy). If blank, content is nested directly under the page.'
                 },
                 outline: {
                     type: 'array',
@@ -141,6 +113,11 @@ export const toolSchemas = {
                                 description: 'Optional: Heading formatting for this block (1-3)',
                                 minimum: 1,
                                 maximum: 3
+                            },
+                            children_view_type: {
+                                type: 'string',
+                                description: 'Optional: The view type for children of this block ("bullet", "document", or "numbered")',
+                                enum: ["bullet", "document", "numbered"]
                             }
                         },
                         required: ['text', 'level']
@@ -162,19 +139,19 @@ export const toolSchemas = {
                 },
                 page_uid: {
                     type: 'string',
-                    description: 'Optional: UID of the page containing the parent block'
+                    description: 'Optional: UID of the page containing the parent block (preferred for accuracy).'
                 },
                 page_title: {
                     type: 'string',
-                    description: 'Optional: Title of the page containing the parent block (ignored if page_uid provided)'
+                    description: 'Optional: Title of the page containing the parent block (used if page_uid is not provided).'
                 },
                 parent_uid: {
                     type: 'string',
-                    description: 'Optional: UID of the parent block to add content under'
+                    description: 'Optional: UID of the parent block to add content under (preferred for accuracy).'
                 },
                 parent_string: {
                     type: 'string',
-                    description: 'Optional: Exact string content of the parent block to add content under (must provide either page_uid (preferred) or page_title)'
+                    description: 'Optional: Exact string content of the parent block to add content under (used if parent_uid is not provided; requires page_uid or page_title).'
                 },
                 order: {
                     type: 'string',
@@ -198,7 +175,7 @@ export const toolSchemas = {
                 },
                 page_title_uid: {
                     type: 'string',
-                    description: 'Optional: Title or UID of the page to search in. Defaults to today\'s daily page if not provided',
+                    description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy). Defaults to today\'s daily page if not provided.',
                 },
                 near_tag: {
                     type: 'string',
@@ -221,7 +198,7 @@ export const toolSchemas = {
                 },
                 page_title_uid: {
                     type: 'string',
-                    description: 'Optional: Title or UID of the page to search in. If not provided, searches across all pages'
+                    description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy). If not provided, searches across all pages.'
                 },
                 include: {
                     type: 'string',
@@ -247,7 +224,7 @@ export const toolSchemas = {
                 },
                 page_title_uid: {
                     type: 'string',
-                    description: 'Optional: Title or UID of the page to search in. If not provided, searches across all pages'
+                    description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy). If not provided, searches across all pages.'
                 }
             }
         }
@@ -268,7 +245,7 @@ export const toolSchemas = {
                 },
                 page_title_uid: {
                     type: 'string',
-                    description: 'Optional: Title or UID of the page to search in'
+                    description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy).'
                 },
                 max_depth: {
                     type: 'integer',
@@ -306,100 +283,12 @@ export const toolSchemas = {
                 },
                 page_title_uid: {
                     type: 'string',
-                    description: 'Optional: Title or UID of the page to search in. If not provided, searches across all pages'
+                    description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy). If not provided, searches across all pages.'
                 }
             },
             required: ['text']
         }
     },
-    roam_update_block: {
-        name: 'roam_update_block',
-        description: 'Update a single block identified by its UID. Use this for individual block updates when you need to either replace the entire content or apply a transform pattern to modify specific parts of the content.\nNOTE Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                block_uid: {
-                    type: 'string',
-                    description: 'UID of the block to update'
-                },
-                content: {
-                    type: 'string',
-                    description: 'New content for the block. If not provided, transform_pattern will be used.'
-                },
-                transform_pattern: {
-                    type: 'object',
-                    description: 'Pattern to transform the current content. Used if content is not provided.',
-                    properties: {
-                        find: {
-                            type: 'string',
-                            description: 'Text or regex pattern to find'
-                        },
-                        replace: {
-                            type: 'string',
-                            description: 'Text to replace with'
-                        },
-                        global: {
-                            type: 'boolean',
-                            description: 'Whether to replace all occurrences',
-                            default: true
-                        }
-                    },
-                    required: ['find', 'replace']
-                }
-            },
-            required: ['block_uid']
-            // Note: Validation for either content or transform_pattern is handled in the server code
-        }
-    },
-    roam_update_multiple_blocks: {
-        name: 'roam_update_multiple_blocks',
-        description: 'Efficiently update multiple blocks in a single batch operation. Use this when you need to update several blocks at once to avoid making multiple separate API calls. Each block in the batch can independently either have its content replaced or transformed using a pattern.\nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                updates: {
-                    type: 'array',
-                    description: 'Array of block updates to perform',
-                    items: {
-                        type: 'object',
-                        properties: {
-                            block_uid: {
-                                type: 'string',
-                                description: 'UID of the block to update'
-                            },
-                            content: {
-                                type: 'string',
-                                description: 'New content for the block. If not provided, transform will be used.'
-                            },
-                            transform: {
-                                type: 'object',
-                                description: 'Pattern to transform the current content. Used if content is not provided.',
-                                properties: {
-                                    find: {
-                                        type: 'string',
-                                        description: 'Text or regex pattern to find'
-                                    },
-                                    replace: {
-                                        type: 'string',
-                                        description: 'Text to replace with'
-                                    },
-                                    global: {
-                                        type: 'boolean',
-                                        description: 'Whether to replace all occurrences',
-                                        default: true
-                                    }
-                                },
-                                required: ['find', 'replace']
-                            }
-                        },
-                        required: ['block_uid']
-                        // Note: Validation for either content or transform is handled in the server code
-                    }
-                }
-            },
-            required: ['updates']
-        }
-    },
     roam_search_by_date: {
         name: 'roam_search_by_date',
         description: 'Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.',
@@ -493,5 +382,71 @@ export const toolSchemas = {
             },
             required: ['query']
         }
+    },
+    roam_process_batch_actions: {
+        name: 'roam_process_batch_actions',
+        description: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order. For creating nested blocks, you can use a temporary client-side UID in a parent block and refer to it in a child block within the same batch. For actions on existing blocks, a valid block UID is required.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                actions: {
+                    type: 'array',
+                    description: 'An array of action objects to execute in order.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            "action": {
+                                type: 'string',
+                                description: 'The specific action to perform.',
+                                enum: ['create-block', 'update-block', 'move-block', 'delete-block']
+                            },
+                            "uid": {
+                                type: 'string',
+                                description: 'The UID of the block to target for "update-block", "move-block", or "delete-block" actions.'
+                            },
+                            "string": {
+                                type: 'string',
+                                description: 'The content for the block, used in "create-block" and "update-block" actions.'
+                            },
+                            "open": {
+                                type: "boolean",
+                                description: "Optional: Sets the open/closed state of a block, used in 'update-block' or 'create-block'. Defaults to true."
+                            },
+                            "heading": {
+                                type: "integer",
+                                description: "Optional: The heading level (1, 2, or 3) for 'create-block' or 'update-block'.",
+                                enum: [1, 2, 3]
+                            },
+                            "text-align": {
+                                type: "string",
+                                description: "Optional: The text alignment for 'create-block' or 'update-block'.",
+                                enum: ["left", "center", "right", "justify"]
+                            },
+                            "children-view-type": {
+                                type: "string",
+                                description: "Optional: The view type for children of the block, for 'create-block' or 'update-block'.",
+                                enum: ["bullet", "document", "numbered"]
+                            },
+                            "location": {
+                                type: 'object',
+                                description: 'Specifies where to place a block, used in "create-block" and "move-block" actions.',
+                                properties: {
+                                    "parent-uid": {
+                                        type: 'string',
+                                        description: 'The UID of the parent block or page.'
+                                    },
+                                    "order": {
+                                        type: ['number', 'string'],
+                                        description: 'The position of the block under its parent (0 for top, "last" for bottom).'
+                                    }
+                                }
+                            }
+                        },
+                        required: ['action']
+                    }
+                }
+            },
+            required: ['actions']
+        }
     }
 };

package/build/tools/tool-handlers.js

@@ -4,6 +4,7 @@ import { SearchOperations } from './operations/search/index.js';
 import { MemoryOperations } from './operations/memory.js';
 import { TodoOperations } from './operations/todos.js';
 import { OutlineOperations } from './operations/outline.js';
+import { BatchOperations } from './operations/batch.js';
 import { DatomicSearchHandlerImpl } from './operations/search/handlers.js';
 export class ToolHandlers {
     constructor(graph) {
@@ -14,6 +15,7 @@ export class ToolHandlers {
         this.memoryOps = new MemoryOperations(graph);
         this.todoOps = new TodoOperations(graph);
         this.outlineOps = new OutlineOperations(graph);
+        this.batchOps = new BatchOperations(graph);
     }
     // Page Operations
     async findPagesModifiedToday(max_num_pages = 50) {
@@ -26,15 +28,6 @@ export class ToolHandlers {
         return this.pageOps.fetchPageByTitle(title, format);
     }
     // Block Operations
-    async createBlock(content, page_uid, title, heading) {
-        return this.blockOps.createBlock(content, page_uid, title, heading);
-    }
-    async updateBlock(block_uid, content, transform) {
-        return this.blockOps.updateBlock(block_uid, content, transform);
-    }
-    async updateBlocks(updates) {
-        return this.blockOps.updateBlocks(updates);
-    }
     // Search Operations
     async searchByStatus(status, page_title_uid, include, exclude) {
         return this.searchOps.searchByStatus(status, page_title_uid, include, exclude);
@@ -77,4 +70,8 @@ export class ToolHandlers {
     async importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order = 'first') {
         return this.outlineOps.importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order);
     }
+    // Batch Operations
+    async processBatch(actions) {
+        return this.batchOps.processBatch(actions);
+    }
 }

package/build/utils/net.js

@@ -0,0 +1,38 @@
+import { createServer } from 'node:net';
+/**
+ * Checks if a given port is currently in use.
+ * @param port The port to check.
+ * @returns A promise that resolves to true if the port is in use, and false otherwise.
+ */
+export function isPortInUse(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                resolve(true);
+            }
+            else {
+                // Handle other errors if necessary, but for this check, we assume other errors mean the port is available.
+                resolve(false);
+            }
+        });
+        server.once('listening', () => {
+            server.close();
+            resolve(false);
+        });
+        server.listen(port);
+    });
+}
+/**
+ * Finds an available port, starting from a given port and incrementing by a specified amount.
+ * @param startPort The port to start checking from.
+ * @param incrementBy The amount to increment the port by if it's in use. Defaults to 2.
+ * @returns A promise that resolves to an available port number.
+ */
+export async function findAvailablePort(startPort, incrementBy = 2) {
+    let port = startPort;
+    while (await isPortInUse(port)) {
+        port += incrementBy;
+    }
+    return port;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.27.0",
+  "version": "0.30.1",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {