roam-research-mcp 0.27.0 → 0.30.2

package/README.md

@@ -102,25 +102,112 @@ The server provides powerful tools for interacting with Roam Research:
 - Detailed debug logging
 - Efficient batch operations
 - Hierarchical outline creation
+- Enhanced documentation for Roam Tables in `Roam_Markdown_Cheatsheet.md` for clearer guidance on nesting.
 
-1. `roam_fetch_page_by_title`: Fetch page content by title.
+1. `roam_fetch_page_by_title`: Fetch page content by title. Returns content in the specified format.
 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`. Best for simpler, sequential outlines. For complex nesting (e.g., tables), consider `roam_process_batch_actions`. If `page_title_uid` and `block_text_uid` are both blank, content defaults to the daily page. (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 for advanced data retrieval 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. Provides granular control for complex nesting like tables. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
+
+**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.
+
+---
+
+### Tool Usage Guidelines and Best Practices
+
+**Pre-computation and Context Loading:**
+✅ Before attempting any Roam operations, **it is highly recommended** to load the `Roam Markdown Cheatsheet` resource into your context. This ensures you have immediate access to the correct Roam-flavored Markdown syntax, including details for tables, block references, and other special formatting. Example prompt: "Read the Roam cheatsheet first. Then, … <rest of your instructions>"
+
+**Identifying Pages and Blocks for Manipulation:**
+To ensure accurate operations, always strive to identify target pages and blocks using their Unique Identifiers (UIDs) whenever possible. While some tools accept case-sensitive text titles or content, UIDs provide unambiguous references, reducing the risk of errors due to ambiguity or changes in text.
+
+- **For Pages:** Use `roam_fetch_page_by_title` to retrieve a page's UID if you only have its title. Example: "Read the page titled 'Trip to Las Vegas'"
+- **For Blocks:** If you need to manipulate an existing block, first use search tools like `roam_search_by_text`, `roam_search_for_tag`, or `roam_fetch_page_by_title` (with raw format) to find the block and obtain its UID. If the block exists on a page that has already been read, then a search isn't necessary.
+
+**Case-Sensitivity:**
+Be aware that text-based inputs (e.g., page titles, block content for search) are generally case-sensitive in Roam. Always match the exact casing of the text as it appears in your graph.
+
+**Iterative Refinement and Verification:**
+For complex operations, especially those involving nested structures or multiple changes, it is often beneficial to break down the task into smaller, verifiable steps. After each significant tool call, consider fetching the affected content to verify the changes before proceeding.
+
+**Understanding Tool Nuances:**
+Familiarize yourself with the specific behaviors and limitations of each tool. For instance, `roam_create_outline` is best for sequential outlines, while `roam_process_batch_actions` offers granular control for complex structures like tables. Refer to the individual tool descriptions for detailed usage notes.
+
+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))"`
+
+**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.
+
+---
+
+## Example Prompts
+
+Here are some examples of how to creatively use the Roam tool in an LLM to interact with your Roam graph, particularly leveraging `roam_process_batch_actions` for complex operations.
+
+### Example 1: Creating a Project Outline
+
+This prompt demonstrates creating a new page and populating it with a structured outline using a single `roam_process_batch_actions` call.
+
+```
+"Create a new Roam page titled 'Project Alpha Planning' and add the following outline:
+- Overview
+  - Goals
+  - Scope
+- Team Members
+  - John Doe
+  - Jane Smith
+- Tasks
+  - Task 1
+    - Subtask 1.1
+    - Subtask 1.2
+  - Task 2
+- Deadlines"
+```
+
+### Example 2: Updating Multiple To-Dos and Adding a New One
+
+This example shows how to mark existing to-do items as `DONE` and add a new one, all within a single batch.
+
+```
+"Mark 'Finish report' and 'Review presentation' as done on today's daily page, and add a new todo 'Prepare for meeting'."
+```
+
+### Example 3: Moving and Updating a Block
+
+This demonstrates moving a block from one location to another and simultaneously updating its content.
+
+```
+"Move the block 'Important note about client feedback' (from page 'Meeting Notes 2025-06-30') under the 'Action Items' section on the 'Project Alpha Planning' page, and change its content to 'Client feedback reviewed and incorporated'."
+```
+
+---
 
 ## Setup
 
@@ -201,6 +288,8 @@ Each error response includes:
 - Detailed error message
 - Suggestions for resolution when applicable
 
+---
+
 ## Development
 
 ### Building

package/build/markdown-utils.js

@@ -21,7 +21,7 @@ function convertTableToRoamFormat(text) {
         .replace(/^\||\|$/g, '')
         .split('|')
         .map(cell => cell.trim()));
-    let roamTable = '{{table}}\n';
+    let roamTable = '{{[[table]]}}\n';
     // First row becomes column headers
     const headers = rows[0];
     for (let i = 0; i < headers.length; i++) {
@@ -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

@@ -2,7 +2,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
-import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initializeGraph } from '@roam-research/roam-api-sdk';
 import { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT } from '../config/environment.js';
 import { toolSchemas } from '../tools/schemas.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
@@ -19,6 +20,7 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 const serverVersion = packageJson.version;
 export class RoamServer {
     constructor() {
+        console.log('RoamServer: Constructor started.');
         try {
             this.graph = initializeGraph({
                 token: API_TOKEN,
@@ -40,6 +42,7 @@ export class RoamServer {
         if (Object.keys(toolSchemas).length === 0) {
             throw new McpError(ErrorCode.InternalError, 'No tool schemas defined in src/tools/schemas.ts');
         }
+        console.log('RoamServer: Constructor finished.');
     }
     // Refactored to accept a Server instance
     setupRequestHandlers(mcpServer) {
@@ -47,6 +50,32 @@ export class RoamServer {
         mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: Object.values(toolSchemas),
         }));
+        // List available resources
+        mcpServer.setRequestHandler(ListResourcesRequestSchema, async () => {
+            const resources = [
+                {
+                    name: 'Roam Markdown Cheatsheet',
+                    uri: 'roam-markdown-cheatsheet.md',
+                    type: 'text', // Changed from ResourceType.Text to string literal 'text'
+                    description: 'A cheatsheet for Roam-flavored Markdown syntax.',
+                },
+            ];
+            return { resources };
+        });
+        // Access resource
+        mcpServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            if (request.params.uri === 'roam-markdown-cheatsheet.md') {
+                const cheatsheetPath = join(__dirname, '../../Roam_Markdown_Cheatsheet.md');
+                try {
+                    const content = readFileSync(cheatsheetPath, 'utf8');
+                    return { contents: [{ type: 'text', text: content, uri: request.params.uri }] };
+                }
+                catch (error) {
+                    throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`); // Changed to InternalError
+                }
+            }
+            throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`); // Changed to InternalError
+        });
         // Handle tool calls
         mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
@@ -72,13 +101,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 +175,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 +182,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) }],
                         };
@@ -215,7 +210,9 @@ export class RoamServer {
         });
     }
     async run() {
+        console.log('RoamServer: run() method started.');
         try {
+            console.log('RoamServer: Attempting to create stdioMcpServer...');
             const stdioMcpServer = new Server({
                 name: 'roam-research',
                 version: serverVersion,
@@ -224,11 +221,17 @@ export class RoamServer {
                     tools: {
                         ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
                     },
+                    resources: {
+                        'roam-markdown-cheatsheet.md': {}
+                    }
                 },
             });
+            console.log('RoamServer: stdioMcpServer created. Setting up request handlers...');
             this.setupRequestHandlers(stdioMcpServer);
+            console.log('RoamServer: stdioMcpServer handlers setup complete. Connecting transport...');
             const stdioTransport = new StdioServerTransport();
             await stdioMcpServer.connect(stdioTransport);
+            console.log('RoamServer: stdioTransport connected. Attempting to create httpMcpServer...');
             const httpMcpServer = new Server({
                 name: 'roam-research-http', // A distinct name for the HTTP server
                 version: serverVersion,
@@ -237,13 +240,19 @@ export class RoamServer {
                     tools: {
                         ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
                     },
+                    resources: {
+                        'roam-markdown-cheatsheet.md': {}
+                    }
                 },
             });
+            console.log('RoamServer: httpMcpServer created. Setting up request handlers...');
             this.setupRequestHandlers(httpMcpServer);
+            console.log('RoamServer: httpMcpServer handlers setup complete. Connecting transport...');
             const httpStreamTransport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: () => Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
             });
             await httpMcpServer.connect(httpStreamTransport);
+            console.log('RoamServer: httpStreamTransport connected.');
             const httpServer = createServer(async (req, res) => {
                 try {
                     await httpStreamTransport.handleRequest(req, res);
@@ -256,8 +265,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 +328,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

@@ -2,7 +2,7 @@
 export const toolSchemas = {
     roam_add_todo: {
         name: 'roam_add_todo',
-        description: 'Add a list of todo items as individual blocks to today\'s daily page in Roam. Each item becomes its own actionable block with todo status.\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).',
+        description: 'Add a list of todo items as individual blocks to today\'s daily page in Roam. Each item becomes its own actionable block with todo status.\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).\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -20,7 +20,7 @@ export const toolSchemas = {
     },
     roam_fetch_page_by_title: {
         name: 'roam_fetch_page_by_title',
-        description: 'Fetch page by title, defaults to raw JSON string.',
+        description: 'Fetch page by title. Returns content in the specified format.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -40,7 +40,7 @@ export const toolSchemas = {
     },
     roam_create_page: {
         name: 'roam_create_page',
-        description: 'Create new standalone page in Roam with optional content using explicit nesting levels and headings (H1-H3). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.',
+        description: 'Create new standalone page in Roam with optional content using explicit nesting levels and headings (H1-H3). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -78,47 +78,19 @@ 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',
+        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\nBest for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider `roam_process_batch_actions` instead.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             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 (or the default daily page if page_title_uid is also blank).'
                 },
                 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']
@@ -152,7 +129,7 @@ export const toolSchemas = {
     },
     roam_import_markdown: {
         name: 'roam_import_markdown',
-        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.',
+        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -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.',
@@ -435,7 +324,7 @@ export const toolSchemas = {
     },
     roam_remember: {
         name: 'roam_remember',
-        description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories. \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).',
+        description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories. \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).\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -475,7 +364,7 @@ export const toolSchemas = {
     },
     roam_datomic_query: {
         name: 'roam_datomic_query',
-        description: 'Execute a custom Datomic query on the Roam graph beyond the available search tools. This provides direct access to Roam\'s query engine for advanced data retrieval. Note: Roam graph is case-sensitive.\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
+        description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. Note: Roam graph is case-sensitive.\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -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. Note: Roam-flavored markdown, including block embedding with `((UID))` syntax, is supported within the `string` property for `create-block` and `update-block` actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like `roam_fetch_page_by_title` or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, `roam_create_outline` is often more suitable.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        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.2",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -34,7 +34,7 @@
     "start": "node build/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.13.2",
     "@roam-research/roam-api-sdk": "^0.10.0",
     "dotenv": "^16.4.7"
   },