roam-research-mcp 0.24.1 → 0.24.2

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.2',
         }, {
             capabilities: {
                 tools: {
@@ -33,7 +33,7 @@ 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: {},
@@ -136,7 +136,7 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'find_pages_modified_today': {
+                    case 'roam_find_pages_modified_today': {
                         const result = await this.toolHandlers.findPagesModifiedToday();
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -173,7 +173,8 @@ 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) }],
                         };

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/pages.js

@@ -8,7 +8,7 @@ export class PageOperations {
     constructor(graph) {
         this.graph = graph;
     }
-    async findPagesModifiedToday() {
+    async findPagesModifiedToday(num_pages = 10) {
         // 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 ${num_pages}`, [startOfDay.getTime(), ancestorRule]);
             if (!results || results.length === 0) {
                 return {
                     success: true,

package/build/tools/schemas.js

@@ -243,13 +243,19 @@ 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: {
+                num_pages: {
+                    type: 'integer',
+                    description: 'Number of result pages to retrieve (default: 10)',
+                    default: 10
+                },
+            },
+            required: ['num_pages']
         }
     },
     roam_search_by_text: {
@@ -399,13 +405,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 +426,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(num_pages = 10) {
+        return this.pageOps.findPagesModifiedToday(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.2",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {