roam-research-mcp 0.25.7 → 0.30.1

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.25.7",
+  "version": "0.30.1",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -29,13 +29,12 @@
   ],
   "scripts": {
     "build": "tsc && chmod 755 build/index.js",
-    "prepare": "npm run build",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
     "start": "node build/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "0.6.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "@roam-research/roam-api-sdk": "^0.10.0",
     "dotenv": "^16.4.7"
   },