roam-research-mcp 0.17.0 → 0.18.0

package/README.md

@@ -1,10 +1,11 @@
 # Roam Research MCP Server
 
 [![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)
+[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)
 
-A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface.
+A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. (A WORK-IN-PROGRESS)
 
 <a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://glama.ai/mcp/servers/fzfznyaflu/badge" alt="Roam Research MCP server" /></a>
 
@@ -27,7 +28,7 @@ npm run build
 
 ## Features
 
-The server provides eleven powerful tools for interacting with Roam Research:
+The server provides twelve powerful tools for interacting with Roam Research:
 
 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
@@ -40,6 +41,7 @@ The server provides eleven powerful tools for interacting with Roam Research:
 9. `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
 
 ## Setup
 
@@ -419,6 +421,55 @@ Returns:
 }
 ```
 
+### Search By Date
+
+Search for blocks and pages based on creation or modification dates:
+
+```typescript
+use_mcp_tool roam-research roam_search_by_date {
+  "start_date": "2025-01-01",
+  "end_date": "2025-01-31",
+  "type": "modified",
+  "scope": "blocks",
+  "include_content": true
+}
+```
+
+Features:
+
+- Search by creation date, modification date, or both
+- Filter blocks, pages, or both
+- Optional date range with start and end dates
+- Include or exclude block/page content in results
+- Sort results by timestamp
+- Efficient date-based filtering using Datalog queries
+
+Parameters:
+
+- `start_date`: Start date in ISO format (YYYY-MM-DD) (required)
+- `end_date`: End date in ISO format (YYYY-MM-DD) (optional)
+- `type`: Whether to search by 'created', 'modified', or 'both' (required)
+- `scope`: Whether to search 'blocks', 'pages', or 'both' (required)
+- `include_content`: Whether to include the content of matching blocks/pages (optional, default: true)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "uid": "block-or-page-uid",
+      "type": "block",
+      "time": 1704067200000,
+      "content": "Block or page content",
+      "page_title": "Page title (for blocks)"
+    }
+  ],
+  "message": "Found N matches for the given date range and criteria"
+}
+```
+
 ### Find Pages Modified Today
 
 Find all pages that have been modified since midnight today:

package/build/server/roam-server.js

@@ -18,7 +18,7 @@ export class RoamServer {
         this.toolHandlers = new ToolHandlers(this.graph);
         this.server = new Server({
             name: 'roam-research',
-            version: '0.16.0',
+            version: '0.17.0',
         }, {
             capabilities: {
                 tools: {
@@ -34,7 +34,8 @@ export class RoamServer {
                     roam_search_hierarchy: {},
                     find_pages_modified_today: {},
                     roam_search_by_text: {},
-                    roam_update_block: {}
+                    roam_update_block: {},
+                    roam_search_by_date: {}
                 },
             },
         });
@@ -142,6 +143,13 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
+                    case 'roam_search_by_date': {
+                        const params = request.params.arguments;
+                        const result = await this.toolHandlers.searchByDate(params);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     case 'roam_update_block': {
                         const { block_uid, content, transform_pattern } = request.params.arguments;
                         let result;

package/build/tools/schemas.js

@@ -313,5 +313,38 @@ export const toolSchemas = {
                 { required: ['transform_pattern'] }
             ]
         }
+    },
+    roam_search_by_date: {
+        name: 'roam_search_by_date',
+        description: 'Search for blocks or pages based on creation or modification dates',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                start_date: {
+                    type: 'string',
+                    description: 'Start date in ISO format (YYYY-MM-DD)',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'Optional: End date in ISO format (YYYY-MM-DD)',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['created', 'modified', 'both'],
+                    description: 'Whether to search by creation date, modification date, or both',
+                },
+                scope: {
+                    type: 'string',
+                    enum: ['blocks', 'pages', 'both'],
+                    description: 'Whether to search blocks, pages, or both',
+                },
+                include_content: {
+                    type: 'boolean',
+                    description: 'Whether to include the content of matching blocks/pages',
+                    default: true,
+                }
+            },
+            required: ['start_date', 'type', 'scope']
+        }
     }
 };

package/build/tools/tool-handlers.js

@@ -900,6 +900,59 @@ export class ToolHandlers {
             message: `Found ${matches.length} block(s) containing ${primaryTagFormatted}${nearTagFormatted ? ` near ${nearTagFormatted}` : ''}`
         };
     }
+    async searchByDate(params) {
+        // Convert dates to timestamps
+        const startTimestamp = new Date(`${params.start_date}T00:00:00`).getTime();
+        const endTimestamp = params.end_date ? new Date(`${params.end_date}T23:59:59`).getTime() : undefined;
+        // Define rule for entity type
+        const entityRule = `[
+      [(block? ?e)
+       [?e :block/string]
+       [?e :block/page ?p]
+       [?p :node/title]]
+      [(page? ?e)
+       [?e :node/title]]
+    ]`;
+        // Build query based on cheatsheet pattern
+        const timeAttr = params.type === 'created' ? ':create/time' : ':edit/time';
+        let queryStr = `[:find ?block-uid ?string ?time ?page-title
+                    :in $ ?start-ts ${endTimestamp ? '?end-ts' : ''}
+                    :where
+                    [?b ${timeAttr} ?time]
+                    [(>= ?time ?start-ts)]
+                    ${endTimestamp ? '[(<= ?time ?end-ts)]' : ''}
+                    [?b :block/uid ?block-uid]
+                    [?b :block/string ?string]
+                    [?b :block/page ?p]
+                    [?p :node/title ?page-title]]`;
+        // Execute query
+        const queryParams = endTimestamp ?
+            [startTimestamp, endTimestamp] :
+            [startTimestamp];
+        const results = await q(this.graph, queryStr, queryParams);
+        if (!results || results.length === 0) {
+            return {
+                success: true,
+                matches: [],
+                message: 'No matches found for the given date range and criteria'
+            };
+        }
+        // Process results - now we get [block-uid, string, time, page-title]
+        const matches = results.map(([uid, content, time, pageTitle]) => ({
+            uid,
+            type: 'block',
+            time,
+            ...(params.include_content && { content }),
+            page_title: pageTitle
+        }));
+        // Sort by time
+        const sortedMatches = matches.sort((a, b) => b.time - a.time);
+        return {
+            success: true,
+            matches: sortedMatches,
+            message: `Found ${sortedMatches.length} matches for the given date range and criteria`
+        };
+    }
     async addTodos(todos) {
         if (!Array.isArray(todos) || todos.length === 0) {
             throw new McpError(ErrorCode.InvalidRequest, 'todos must be a non-empty array');

package/package.json

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