roam-research-mcp 0.24.1 → 0.24.5

package/README.md

@@ -30,6 +30,16 @@ npm run build
 
 The server provides powerful tools for interacting with Roam Research:
 
+- Environment variable handling with .env support
+- Comprehensive input validation
+- Case-insensitive page title matching
+- Recursive block reference resolution
+- Markdown parsing and conversion
+- Daily page integration
+- Detailed debug logging
+- Efficient batch operations
+- Hierarchical outline creation
+
 1. `roam_fetch_page_by_title`: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep
 2. `roam_create_page`: Create new pages with optional content
 3. `roam_create_block`: Create new blocks in a page (defaults to today's daily page)
@@ -38,7 +48,7 @@ The server provides powerful tools for interacting with Roam Research:
 6. `roam_create_outline`: Create hierarchical outlines with proper nesting and structure
 7. `roam_search_block_refs`: Search for block references within pages or across the graph
 8. `roam_search_hierarchy`: Navigate and search through block parent-child relationships
-9. `find_pages_modified_today`: Find all pages that have been modified since midnight today
+9. `roam_find_pages_modified_today`: Find all pages that have been modified since midnight today
 10. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page
 11. `roam_update_block`: Update block content with direct text or pattern-based transformations
 12. `roam_search_by_date`: Search for blocks and pages based on creation or modification dates
@@ -545,7 +555,7 @@ Returns:
 Find all pages that have been modified since midnight today:
 
 ```typescript
-use_mcp_tool roam-research find_pages_modified_today {}
+use_mcp_tool roam-research roam_find_pages_modified_today {}
 ```
 
 Features:
@@ -717,25 +727,39 @@ Each error response includes:
 
 ## Development
 
-The server is built with TypeScript and includes:
+### Building
 
-- Environment variable handling with .env support
-- Comprehensive input validation
-- Case-insensitive page title matching
-- Recursive block reference resolution
-- Markdown parsing and conversion
-- Daily page integration
-- Detailed debug logging
-- Efficient batch operations
-- Hierarchical outline creation
+To build the server:
+
+```bash
+npm install
+npm run build
+```
+
+This will:
+
+1. Install all required dependencies
+2. Compile TypeScript to JavaScript
+3. Make the output file executable
+
+You can also use `npm run watch` during development to automatically recompile when files change.
+
+### Testing with MCP Inspector
+
+The MCP Inspector is a tool that helps test and debug MCP servers. To test the server:
+
+```bash
+# Inspect with npx:
+npx @modelcontextprotocol/inspector node build/index.js
+```
 
-To modify or extend the server:
+This will:
 
-1. Clone the repository
-2. Install dependencies with `npm install`
-3. Make changes to the source files
-4. Build with `npm run build`
-5. Test locally by configuring environment variables
+1. Start the server in inspector mode
+2. Provide an interactive interface to:
+   - List available tools and resources
+   - Execute tools with custom parameters
+   - View tool responses and error handling
 
 ## License
 

package/build/server/roam-server.js

@@ -17,7 +17,7 @@ export class RoamServer {
         this.toolHandlers = new ToolHandlers(this.graph);
         this.server = new Server({
             name: 'roam-research',
-            version: '0.17.0',
+            version: '0.24.5',
         }, {
             capabilities: {
                 tools: {
@@ -33,10 +33,10 @@ export class RoamServer {
                     roam_search_by_status: {},
                     roam_search_block_refs: {},
                     roam_search_hierarchy: {},
-                    find_pages_modified_today: {},
+                    roam_find_pages_modified_today: {},
                     roam_search_by_text: {},
                     roam_update_block: {},
-                    roam_update_blocks: {},
+                    roam_update_multiple_blocks: {},
                     roam_search_by_date: {},
                     roam_datomic_query: {}
                 },
@@ -136,8 +136,9 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'find_pages_modified_today': {
-                        const result = await this.toolHandlers.findPagesModifiedToday();
+                    case 'roam_find_pages_modified_today': {
+                        const { max_num_pages } = request.params.arguments;
+                        const result = await this.toolHandlers.findPagesModifiedToday(max_num_pages || 50);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
@@ -173,12 +174,13 @@ export class RoamServer {
                         };
                     }
                     case 'roam_recall': {
-                        const result = await this.toolHandlers.recall();
+                        const { sort_by = 'newest', filter_tag } = request.params.arguments;
+                        const result = await this.toolHandlers.recall(sort_by, filter_tag);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'roam_update_blocks': {
+                    case 'roam_update_multiple_blocks': {
                         const { updates } = request.params.arguments;
                         const result = await this.toolHandlers.updateBlocks(updates);
                         return {

package/build/tools/operations/memory.js

@@ -66,7 +66,7 @@ export class MemoryOperations {
         }
         return { success: true };
     }
-    async recall() {
+    async recall(sort_by = 'newest', filter_tag) {
         // Get memories tag from environment
         var memoriesTag = process.env.MEMORIES_TAG;
         if (!memoriesTag) {
@@ -76,27 +76,73 @@ export class MemoryOperations {
         const tagText = memoriesTag
             .replace(/^#/, '') // Remove leading #
             .replace(/^\[\[/, '').replace(/\]\]$/, ''); // Remove [[ and ]]
-        // Get results from tag search
-        const tagResults = await this.searchOps.searchForTag(tagText);
-        // Get blocks from the memories page
-        const pageQuery = `[:find ?string
-                       :in $ ?title
-                       :where [?p :node/title ?title]
-                              [?b :block/page ?p]
-                              [?b :block/string ?string]]`;
-        const pageResults = await q(this.graph, pageQuery, [tagText]);
-        // Combine both sets of results and remove the memories tag
-        const allMemories = [
-            ...tagResults.matches.map((match) => match.content),
-            ...pageResults.map(([content]) => content)
-        ].map(content => content.replace(`${memoriesTag} `, ''));
-        // Resolve any block references in the combined memories
-        const resolvedMemories = await Promise.all(allMemories.map(async (content) => resolveRefs(this.graph, content)));
-        // Remove duplicates
-        const uniqueMemories = [...new Set(resolvedMemories)];
-        return {
-            success: true,
-            memories: uniqueMemories
-        };
+        try {
+            // Get page blocks using query to access actual block content
+            const ancestorRule = `[
+        [ (ancestor ?b ?a)
+          [?a :block/children ?b] ]
+        [ (ancestor ?b ?a)
+          [?parent :block/children ?b]
+          (ancestor ?parent ?a) ]
+      ]`;
+            // Query to find all blocks on the page
+            const pageQuery = `[:find ?string ?time
+                         :in $ % ?title
+                         :where 
+                         [?page :node/title ?title]
+                         [?block :block/string ?string]
+                         [?block :create/time ?time]
+                         (ancestor ?block ?page)]`;
+            // Execute query
+            const pageResults = await q(this.graph, pageQuery, [ancestorRule, tagText]);
+            // Process page blocks with sorting
+            let pageMemories = pageResults
+                .sort(([_, aTime], [__, bTime]) => sort_by === 'newest' ? bTime - aTime : aTime - bTime)
+                .map(([content]) => content);
+            // Get tagged blocks from across the graph
+            const tagResults = await this.searchOps.searchForTag(tagText);
+            // Process tagged blocks with sorting
+            let taggedMemories = tagResults.matches
+                .sort((a, b) => {
+                const aTime = a.block_uid ? parseInt(a.block_uid.split('-')[0], 16) : 0;
+                const bTime = b.block_uid ? parseInt(b.block_uid.split('-')[0], 16) : 0;
+                return sort_by === 'newest' ? bTime - aTime : aTime - bTime;
+            })
+                .map(match => match.content);
+            // Resolve any block references in both sets
+            const resolvedPageMemories = await Promise.all(pageMemories.map(async (content) => resolveRefs(this.graph, content)));
+            const resolvedTaggedMemories = await Promise.all(taggedMemories.map(async (content) => resolveRefs(this.graph, content)));
+            // Combine both sets and remove duplicates while preserving order
+            let uniqueMemories = [
+                ...resolvedPageMemories,
+                ...resolvedTaggedMemories
+            ].filter((memory, index, self) => self.indexOf(memory) === index);
+            // Format filter tag with exact Roam tag syntax
+            const filterTagFormatted = filter_tag ?
+                (filter_tag.includes(' ') ? `#[[${filter_tag}]]` : `#${filter_tag}`) : null;
+            // Filter by exact tag match if provided
+            if (filterTagFormatted) {
+                uniqueMemories = uniqueMemories.filter(memory => memory.includes(filterTagFormatted));
+            }
+            // Format memories tag for removal and clean up memories tag
+            const memoriesTagFormatted = tagText.includes(' ') || tagText.includes('/') ? `#[[${tagText}]]` : `#${tagText}`;
+            uniqueMemories = uniqueMemories.map(memory => memory.replace(memoriesTagFormatted, '').trim());
+            // return {
+            //   success: true,
+            //   memories: [
+            //     `memoriesTag = ${memoriesTag}`,
+            //     `filter_tag = ${filter_tag}`,
+            //     `filterTagFormatted = ${filterTagFormatted}`,
+            //     `memoriesTagFormatted = ${memoriesTagFormatted}`,
+            //   ]
+            // }
+            return {
+                success: true,
+                memories: uniqueMemories
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to recall memories: ${error.message}`);
+        }
     }
 }

package/build/tools/operations/outline.js

@@ -159,6 +159,10 @@ export class OutlineOperations {
                 return createAndVerifyBlock(content, parentUid, maxRetries, initialDelay, true);
             }
         };
+        // Helper function to check if string is a valid Roam UID (9 characters)
+        const isValidUid = (str) => {
+            return typeof str === 'string' && str.length === 9;
+        };
         // Get or create the parent block
         let targetParentUid;
         if (!block_text_uid) {
@@ -166,12 +170,28 @@ export class OutlineOperations {
         }
         else {
             try {
-                // Create header block and get its UID
-                targetParentUid = await createAndVerifyBlock(block_text_uid, targetPageUid);
+                if (isValidUid(block_text_uid)) {
+                    // First try to find block by UID
+                    const uidQuery = `[:find ?uid
+                           :where [?e :block/uid "${block_text_uid}"]
+                                  [?e :block/uid ?uid]]`;
+                    const uidResult = await q(this.graph, uidQuery, []);
+                    if (uidResult && uidResult.length > 0) {
+                        // Use existing block if found
+                        targetParentUid = uidResult[0][0];
+                    }
+                    else {
+                        throw new McpError(ErrorCode.InvalidRequest, `Block with UID "${block_text_uid}" not found`);
+                    }
+                }
+                else {
+                    // Create header block and get its UID if not a valid UID
+                    targetParentUid = await createAndVerifyBlock(block_text_uid, targetPageUid);
+                }
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                throw new McpError(ErrorCode.InternalError, `Failed to create header block "${block_text_uid}": ${errorMessage}`);
+                throw new McpError(ErrorCode.InternalError, `Failed to ${isValidUid(block_text_uid) ? 'find' : 'create'} block "${block_text_uid}": ${errorMessage}`);
             }
         }
         // Initialize result variable

package/build/tools/operations/pages.js

@@ -8,7 +8,7 @@ export class PageOperations {
     constructor(graph) {
         this.graph = graph;
     }
-    async findPagesModifiedToday() {
+    async findPagesModifiedToday(max_num_pages = 50) {
         // Define ancestor rule for traversing block hierarchy
         const ancestorRule = `[
       [ (ancestor ?b ?a)
@@ -28,7 +28,8 @@ export class PageOperations {
           [?page :node/title ?title]
           (ancestor ?block ?page)
           [?block :edit/time ?time]
-          [(> ?time ?start_of_day)]]`, [startOfDay.getTime(), ancestorRule]);
+          [(> ?time ?start_of_day)]]
+          :limit ${max_num_pages}`, [startOfDay.getTime(), ancestorRule]);
             if (!results || results.length === 0) {
                 return {
                     success: true,

package/build/tools/schemas.js

@@ -20,13 +20,13 @@ export const toolSchemas = {
     },
     roam_fetch_page_by_title: {
         name: 'roam_fetch_page_by_title',
-        description: 'Retrieve complete page contents by exact title, including all nested blocks and resolved block references. Use for reading and analyzing existing Roam pages.',
+        description: 'Retrieve complete page contents by exact title, including all nested blocks and resolved block references. Use for accessing daily pages, reading and analyzing existing Roam pages.',
         inputSchema: {
             type: 'object',
             properties: {
                 title: {
                     type: 'string',
-                    description: 'Title of the page to fetch and read',
+                    description: 'Title of the page. For date pages, use ordinal date formats such as January 2nd, 2025',
                 },
             },
             required: ['title'],
@@ -243,13 +243,18 @@ export const toolSchemas = {
             ]
         }
     },
-    find_pages_modified_today: {
-        name: 'find_pages_modified_today',
-        description: 'Find all pages that have been modified today (since midnight).',
+    roam_find_pages_modified_today: {
+        name: 'roam_find_pages_modified_today',
+        description: 'Find pages that have been modified today (since midnight), with limit.',
         inputSchema: {
             type: 'object',
-            properties: {},
-            required: []
+            properties: {
+                max_num_pages: {
+                    type: 'integer',
+                    description: 'Max number of pages to retrieve (default: 50)',
+                    default: 50
+                },
+            }
         }
     },
     roam_search_by_text: {
@@ -272,7 +277,7 @@ export const toolSchemas = {
     },
     roam_update_block: {
         name: 'roam_update_block',
-        description: 'Update the content of an existing block identified by its UID. Can either provide new content directly or use a transform pattern to modify existing content.\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: '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 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: {
@@ -312,9 +317,9 @@ export const toolSchemas = {
             ]
         }
     },
-    roam_update_blocks: {
-        name: 'roam_update_blocks',
-        description: 'Update multiple blocks in a single batch operation. Each update can provide either new content directly or a transform 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).',
+    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: {
@@ -366,7 +371,7 @@ export const toolSchemas = {
     },
     roam_search_by_date: {
         name: 'roam_search_by_date',
-        description: 'Search for blocks or pages based on creation or modification dates',
+        description: 'Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -399,13 +404,13 @@ export const toolSchemas = {
     },
     roam_remember: {
         name: 'roam_remember',
-        description: 'Add a memory or piece of information to remember, stored on the daily page with #[[LLM/Memories]] 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).',
         inputSchema: {
             type: 'object',
             properties: {
                 memory: {
                     type: 'string',
-                    description: 'The memory or information to remember'
+                    description: 'The memory detail or information to remember'
                 },
                 categories: {
                     type: 'array',
@@ -420,11 +425,21 @@ export const toolSchemas = {
     },
     roam_recall: {
         name: 'roam_recall',
-        description: 'Retrieve all stored memories by searching for blocks tagged with MEMORIES_TAG and content from the page with the same name. Returns a combined, deduplicated list of memories.',
+        description: 'Retrieve all stored memories on page titled MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories. Optionally filter blcoks with a specified tag and sort by creation date.',
         inputSchema: {
             type: 'object',
-            properties: {},
-            required: []
+            properties: {
+                sort_by: {
+                    type: 'string',
+                    description: 'Sort order for memories based on creation date',
+                    enum: ['newest', 'oldest'],
+                    default: 'newest'
+                },
+                filter_tag: {
+                    type: 'string',
+                    description: 'Include only memories with a specific filter tag. For single word tags use format "tag", for multi-word tags use format "tag word" (without brackets)'
+                }
+            }
         }
     },
     roam_datomic_query: {

package/build/tools/tool-handlers.js

@@ -23,8 +23,8 @@ export class ToolHandlers {
         this.outlineOps = new OutlineOperations(graph);
     }
     // Page Operations
-    async findPagesModifiedToday() {
-        return this.pageOps.findPagesModifiedToday();
+    async findPagesModifiedToday(max_num_pages = 50) {
+        return this.pageOps.findPagesModifiedToday(max_num_pages);
     }
     async createPage(title, content) {
         return this.pageOps.createPage(title, content);
@@ -70,8 +70,8 @@ export class ToolHandlers {
     async remember(memory, categories) {
         return this.memoryOps.remember(memory, categories);
     }
-    async recall() {
-        return this.memoryOps.recall();
+    async recall(sort_by = 'newest', filter_tag) {
+        return this.memoryOps.recall(sort_by, filter_tag);
     }
     // Todo Operations
     async addTodos(todos) {

package/package.json

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