roam-research-mcp 0.14.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 eight 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
@@ -37,6 +38,10 @@ The server provides eight 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
+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
 
@@ -322,6 +327,175 @@ Returns:
 }
 ```
 
+### Search By Text
+
+Search for blocks containing specific text across all pages or within a specific page:
+
+```typescript
+use_mcp_tool roam-research roam_search_by_text {
+  "text": "search text",
+  "page_title_uid": "optional-page-title-or-uid",
+  "case_sensitive": false
+}
+```
+
+Features:
+
+- Search for any text across all blocks in the graph
+- Optional page-scoped search
+- Case-sensitive or case-insensitive search
+- Returns block content with page context
+- Efficient text matching using Datalog queries
+
+Parameters:
+
+- `text`: The text to search for (required)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+- `case_sensitive`: Whether to perform a case-sensitive search (optional, default: false)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "matching-block-uid",
+      "content": "Block content containing search text",
+      "page_title": "Page containing block"
+    }
+  ],
+  "message": "Found N block(s) containing \"search text\""
+}
+```
+
+### Update Block Content
+
+Update a block's content using either direct text replacement or pattern-based transformations:
+
+```typescript
+use_mcp_tool roam-research roam_update_block {
+  "block_uid": "target-block-uid",
+  "content": "New block content"
+}
+```
+
+Or use pattern-based transformation:
+
+```typescript
+use_mcp_tool roam-research roam_update_block {
+  "block_uid": "target-block-uid",
+  "transform_pattern": {
+    "find": "\\bPython\\b",
+    "replace": "[[Python]]",
+    "global": true
+  }
+}
+```
+
+Features:
+
+- Two update modes:
+  - Direct content replacement
+  - Pattern-based transformation using regex
+- Verify block existence before updating
+- Return updated content in response
+- Support for global or single-match replacements
+- Preserve block relationships and metadata
+
+Parameters:
+
+- `block_uid`: UID of the block to update (required)
+- `content`: New content for the block (if using direct replacement)
+- `transform_pattern`: Pattern for transforming existing content:
+  - `find`: Text or regex pattern to find
+  - `replace`: Text to replace with
+  - `global`: Whether to replace all occurrences (default: true)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "content": "Updated block content"
+}
+```
+
+### 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:
+
+```typescript
+use_mcp_tool roam-research find_pages_modified_today {}
+```
+
+Features:
+
+- Tracks all modifications made to pages since midnight
+- Detects changes at any level in the block hierarchy
+- Returns unique list of modified page titles
+- Includes count of modified pages
+- No parameters required
+
+Returns:
+
+```json
+{
+  "success": true,
+  "pages": ["Page 1", "Page 2"],
+  "message": "Found 2 page(s) modified today"
+}
+```
+
 ### Search Block Hierarchy
 
 Navigate and search through block parent-child relationships:

package/build/markdown-utils.js

@@ -41,25 +41,134 @@ function convertAllTables(text) {
         return '\n' + convertTableToRoamFormat(match) + '\n';
     });
 }
+/**
+ * Parse markdown heading syntax (e.g. "### Heading") and return the heading level (1-3) and content.
+ * Heading level is determined by the number of # characters (e.g. # = h1, ## = h2, ### = h3).
+ * Returns heading_level: 0 for non-heading content.
+ */
+function parseMarkdownHeadingLevel(text) {
+    const match = text.match(/^(#{1,3})\s+(.+)$/);
+    if (match) {
+        return {
+            heading_level: match[1].length, // Number of # characters determines heading level
+            content: match[2].trim()
+        };
+    }
+    return {
+        heading_level: 0, // Not a heading
+        content: text.trim()
+    };
+}
 function convertToRoamMarkdown(text) {
-    // First handle double asterisks/underscores (bold)
+    // Handle double asterisks/underscores (bold)
     text = text.replace(/\*\*(.+?)\*\*/g, '**$1**'); // Preserve double asterisks
-    // Then handle single asterisks/underscores (italic)
+    // Handle single asterisks/underscores (italic)
     text = text.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '__$1__'); // Single asterisk to double underscore
     text = text.replace(/(?<!_)_(?!_)(.+?)(?<!_)_(?!_)/g, '__$1__'); // Single underscore to double underscore
     // Handle highlights
     text = text.replace(/==(.+?)==/g, '^^$1^^');
+    // Convert tasks
+    text = text.replace(/- \[ \]/g, '- {{[[TODO]]}}');
+    text = text.replace(/- \[x\]/g, '- {{[[DONE]]}}');
     // Convert tables
     text = convertAllTables(text);
     return text;
 }
 function parseMarkdown(markdown) {
+    // Convert markdown syntax first
+    markdown = convertToRoamMarkdown(markdown);
     const lines = markdown.split('\n');
     const rootNodes = [];
     const stack = [];
+    let inCodeBlock = false;
+    let codeBlockContent = '';
+    let codeBlockIndentation = 0;
+    let codeBlockParentLevel = 0;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         const trimmedLine = line.trimEnd();
+        // Handle code blocks
+        if (trimmedLine.match(/^(\s*)```/)) {
+            if (!inCodeBlock) {
+                // Start of code block
+                inCodeBlock = true;
+                // Store the opening backticks without indentation
+                codeBlockContent = trimmedLine.trimStart() + '\n';
+                codeBlockIndentation = line.match(/^\s*/)?.[0].length ?? 0;
+                // Save current parent level
+                codeBlockParentLevel = stack.length;
+            }
+            else {
+                // End of code block
+                inCodeBlock = false;
+                // Add closing backticks without indentation
+                codeBlockContent += trimmedLine.trimStart();
+                // Process the code block content to fix indentation
+                const lines = codeBlockContent.split('\n');
+                // Find the first non-empty code line to determine base indentation
+                let baseIndentation = '';
+                let codeStartIndex = -1;
+                for (let i = 1; i < lines.length - 1; i++) {
+                    const line = lines[i];
+                    if (line.trim().length > 0) {
+                        const indentMatch = line.match(/^[\t ]*/);
+                        if (indentMatch) {
+                            baseIndentation = indentMatch[0];
+                            codeStartIndex = i;
+                            break;
+                        }
+                    }
+                }
+                // Process lines maintaining relative indentation from the first code line
+                const processedLines = lines.map((line, index) => {
+                    // Keep backticks as is
+                    if (index === 0 || index === lines.length - 1)
+                        return line.trimStart();
+                    // Empty lines should be completely trimmed
+                    if (line.trim().length === 0)
+                        return '';
+                    // For code lines, remove only the base indentation
+                    if (line.startsWith(baseIndentation)) {
+                        return line.slice(baseIndentation.length);
+                    }
+                    // If line has less indentation than base, trim all leading whitespace
+                    return line.trimStart();
+                });
+                // Create node for the entire code block
+                const level = Math.floor(codeBlockIndentation / 2);
+                const node = {
+                    content: processedLines.join('\n'),
+                    level,
+                    children: []
+                };
+                // Restore to code block's parent level
+                while (stack.length > codeBlockParentLevel) {
+                    stack.pop();
+                }
+                if (level === 0) {
+                    rootNodes.push(node);
+                    stack[0] = node;
+                }
+                else {
+                    while (stack.length > level) {
+                        stack.pop();
+                    }
+                    if (stack[level - 1]) {
+                        stack[level - 1].children.push(node);
+                    }
+                    else {
+                        rootNodes.push(node);
+                    }
+                    stack[level] = node;
+                }
+                codeBlockContent = '';
+            }
+            continue;
+        }
+        if (inCodeBlock) {
+            codeBlockContent += line + '\n';
+            continue;
+        }
         // Skip truly empty lines (no spaces)
         if (trimmedLine === '') {
             continue;
@@ -67,52 +176,54 @@ function parseMarkdown(markdown) {
         // Calculate indentation level (2 spaces = 1 level)
         const indentation = line.match(/^\s*/)?.[0].length ?? 0;
         let level = Math.floor(indentation / 2);
-        // Extract content after bullet point or heading
-        let content = trimmedLine;
-        content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
-        if (trimmedLine.startsWith('#') || trimmedLine.includes('{{table}}') || (trimmedLine.startsWith('**') && trimmedLine.endsWith('**'))) {
-            // Remove bullet point if it precedes a table marker
-            // content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
-            level = 0;
-            // Reset stack but keep heading/table as parent
-            stack.length = 1; // Keep only the heading/table
+        // First check for headings
+        const { heading_level, content: headingContent } = parseMarkdownHeadingLevel(trimmedLine);
+        // Then handle bullet points if not a heading
+        let content;
+        if (heading_level > 0) {
+            content = headingContent; // Use clean heading content without # marks
+            level = 0; // Headings start at root level
+            stack.length = 1; // Reset stack but keep heading as parent
+            // Create heading node
+            const node = {
+                content,
+                level,
+                heading_level, // Store heading level in node
+                children: []
+            };
+            rootNodes.push(node);
+            stack[0] = node;
+            continue; // Skip to next line
         }
-        else if (stack[0]?.content.startsWith('#') || stack[0]?.content.includes('{{table}}') || (stack[0]?.content.startsWith('**') && stack[0]?.content.endsWith('**'))) {
-            // If previous node was a heading or table marker or wrapped in double-asterisks, increase level by 1
-            level = Math.max(level, 1);
-            // Remove bullet point
-            // content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
+        // Handle non-heading content
+        const bulletMatch = trimmedLine.match(/^(\s*)[-*+]\s+/);
+        if (bulletMatch) {
+            // For bullet points, use the bullet's indentation for level
+            content = trimmedLine.substring(bulletMatch[0].length);
+            level = Math.floor(bulletMatch[1].length / 2);
         }
         else {
-            // Remove bullet point
-            content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
+            content = trimmedLine;
         }
-        // Create new node
+        // Create regular node
         const node = {
             content,
             level,
             children: []
         };
-        // Find the appropriate parent for this node based on level
-        if (level === 0) {
+        // Pop stack until we find the parent level
+        while (stack.length > level) {
+            stack.pop();
+        }
+        // Add to appropriate parent
+        if (level === 0 || !stack[level - 1]) {
             rootNodes.push(node);
             stack[0] = node;
         }
         else {
-            // Pop stack until we find the parent level
-            while (stack.length > level) {
-                stack.pop();
-            }
-            // Add as child to parent
-            if (stack[level - 1]) {
-                stack[level - 1].children.push(node);
-            }
-            else {
-                // If no parent found, treat as root node
-                rootNodes.push(node);
-            }
-            stack[level] = node;
+            stack[level - 1].children.push(node);
         }
+        stack[level] = node;
     }
     return rootNodes;
 }
@@ -168,12 +279,13 @@ function convertNodesToBlocks(nodes) {
     return nodes.map(node => ({
         uid: generateBlockUid(),
         content: node.content,
+        ...(node.heading_level && { heading_level: node.heading_level }), // Preserve heading level if present
         children: convertNodesToBlocks(node.children)
     }));
 }
 function convertToRoamActions(nodes, parentUid, order = 'last') {
-    // First convert nodes to blocks with UIDs
-    const blocks = convertNodesToBlocks(nodes);
+    // First convert nodes to blocks with UIDs, reversing to maintain original order
+    const blocks = convertNodesToBlocks([...nodes].reverse());
     const actions = [];
     // Helper function to recursively create actions
     function createBlockActions(blocks, parentUid, order) {
@@ -187,7 +299,8 @@ function convertToRoamActions(nodes, parentUid, order = 'last') {
                 },
                 block: {
                     uid: block.uid,
-                    string: block.content
+                    string: block.content,
+                    ...(block.heading_level && { heading: block.heading_level })
                 }
             };
             actions.push(action);
@@ -202,4 +315,4 @@ function convertToRoamActions(nodes, parentUid, order = 'last') {
     return actions;
 }
 // Export public functions and types
-export { parseMarkdown, convertToRoamActions, hasMarkdownTable, convertAllTables, convertToRoamMarkdown };
+export { parseMarkdown, convertToRoamActions, hasMarkdownTable, convertAllTables, convertToRoamMarkdown, parseMarkdownHeadingLevel };

package/build/search/hierarchy-search.js

@@ -21,64 +21,68 @@ export class HierarchySearchHandler extends BaseSearchHandler {
         if (page_title_uid) {
             targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
         }
+        // Define ancestor rule for recursive traversal
+        const ancestorRule = `[
+      [ (ancestor ?child ?parent) 
+          [?parent :block/children ?child] ]
+      [ (ancestor ?child ?a) 
+          [?parent :block/children ?child] 
+          (ancestor ?parent ?a) ]
+    ]`;
         let queryStr;
         let queryParams;
         if (parent_uid) {
-            // Search for children of a specific block
+            // Search for all descendants using ancestor rule
             if (targetPageUid) {
                 queryStr = `[:find ?block-uid ?block-str ?depth
-                    :in $ ?parent-uid ?page-uid ?max-depth
+                    :in $ % ?parent-uid ?page-uid
                     :where [?p :block/uid ?page-uid]
                            [?parent :block/uid ?parent-uid]
-                           [?b :block/parents ?parent]
+                           (ancestor ?b ?parent)
                            [?b :block/string ?block-str]
                            [?b :block/uid ?block-uid]
                            [?b :block/page ?p]
-                           [(get-else $ ?b :block/path-length 1) ?depth]
-                           [(<= ?depth ?max-depth)]]`;
-                queryParams = [parent_uid, targetPageUid, max_depth];
+                           [(get-else $ ?b :block/path-length 1) ?depth]]`;
+                queryParams = [ancestorRule, parent_uid, targetPageUid];
             }
             else {
                 queryStr = `[:find ?block-uid ?block-str ?page-title ?depth
-                    :in $ ?parent-uid ?max-depth
+                    :in $ % ?parent-uid
                     :where [?parent :block/uid ?parent-uid]
-                           [?b :block/parents ?parent]
+                           (ancestor ?b ?parent)
                            [?b :block/string ?block-str]
                            [?b :block/uid ?block-uid]
                            [?b :block/page ?p]
                            [?p :node/title ?page-title]
-                           [(get-else $ ?b :block/path-length 1) ?depth]
-                           [(<= ?depth ?max-depth)]]`;
-                queryParams = [parent_uid, max_depth];
+                           [(get-else $ ?b :block/path-length 1) ?depth]]`;
+                queryParams = [ancestorRule, parent_uid];
             }
         }
         else {
-            // Search for parents of a specific block
+            // Search for ancestors using the same rule
             if (targetPageUid) {
                 queryStr = `[:find ?block-uid ?block-str ?depth
-                    :in $ ?child-uid ?page-uid ?max-depth
+                    :in $ % ?child-uid ?page-uid
                     :where [?p :block/uid ?page-uid]
                            [?child :block/uid ?child-uid]
-                           [?child :block/parents ?b]
+                           (ancestor ?child ?b)
                            [?b :block/string ?block-str]
                            [?b :block/uid ?block-uid]
                            [?b :block/page ?p]
-                           [(get-else $ ?b :block/path-length 1) ?depth]
-                           [(<= ?depth ?max-depth)]]`;
-                queryParams = [child_uid, targetPageUid, max_depth];
+                           [(get-else $ ?b :block/path-length 1) ?depth]]`;
+                queryParams = [ancestorRule, child_uid, targetPageUid];
             }
             else {
                 queryStr = `[:find ?block-uid ?block-str ?page-title ?depth
-                    :in $ ?child-uid ?max-depth
+                    :in $ % ?child-uid
                     :where [?child :block/uid ?child-uid]
-                           [?child :block/parents ?b]
+                           (ancestor ?child ?b)
                            [?b :block/string ?block-str]
                            [?b :block/uid ?block-uid]
                            [?b :block/page ?p]
                            [?p :node/title ?page-title]
-                           [(get-else $ ?b :block/path-length 1) ?depth]
-                           [(<= ?depth ?max-depth)]]`;
-                queryParams = [child_uid, max_depth];
+                           [(get-else $ ?b :block/path-length 1) ?depth]]`;
+                queryParams = [ancestorRule, child_uid];
             }
         }
         const results = await q(this.graph, queryStr, queryParams);
@@ -90,8 +94,8 @@ export class HierarchySearchHandler extends BaseSearchHandler {
             ...(pageTitle && { page_title: pageTitle })
         }));
         const searchDescription = parent_uid
-            ? `children of block ${parent_uid} (max depth: ${max_depth})`
-            : `parents of block ${child_uid} (max depth: ${max_depth})`;
+            ? `descendants of block ${parent_uid}`
+            : `ancestors of block ${child_uid}`;
         return {
             success: true,
             matches,

package/build/search/index.js

@@ -4,3 +4,4 @@ export * from './tag-search.js';
 export * from './status-search.js';
 export * from './block-ref-search.js';
 export * from './hierarchy-search.js';
+export * from './text-search.js';

package/build/search/tag-search.js

@@ -9,81 +9,27 @@ export class TagSearchHandler extends BaseSearchHandler {
     }
     async execute() {
         const { primary_tag, page_title_uid, near_tag, exclude_tag } = this.params;
-        // Format tags to handle both # and [[]] formats
-        const primaryTagFormats = SearchUtils.formatTag(primary_tag);
-        const nearTagFormats = near_tag ? SearchUtils.formatTag(near_tag) : undefined;
-        const excludeTagFormats = exclude_tag ? SearchUtils.formatTag(exclude_tag) : undefined;
-        // Get target page UID if provided
+        // Get target page UID if provided for scoped search
         let targetPageUid;
         if (page_title_uid) {
             targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
         }
-        // Build query based on whether we're searching in a specific page and/or for a nearby tag
-        let queryStr;
-        let queryParams;
-        if (targetPageUid) {
-            if (nearTagFormats) {
-                queryStr = `[:find ?block-uid ?block-str
-                    :in $ [?primary-tag1 ?primary-tag2] [?near-tag1 ?near-tag2] [?exclude-tag1 ?exclude-tag2] ?page-uid
-                    :where [?p :block/uid ?page-uid]
-                           [?b :block/page ?p]
-                           [?b :block/string ?block-str]
-                           [?b :block/uid ?block-uid]
-                           (or [(clojure.string/includes? ?block-str ?primary-tag1)]
-                               [(clojure.string/includes? ?block-str ?primary-tag2)])
-                           (or [(clojure.string/includes? ?block-str ?near-tag1)]
-                               [(clojure.string/includes? ?block-str ?near-tag2)])
-                           (not (or [(clojure.string/includes? ?block-str ?exclude-tag1)]
-                                  [(clojure.string/includes? ?block-str ?exclude-tag2)]))]`;
-                queryParams = [primaryTagFormats, nearTagFormats, excludeTagFormats || ['', ''], targetPageUid];
-            }
-            else {
-                queryStr = `[:find ?block-uid ?block-str
-                    :in $ [?primary-tag1 ?primary-tag2] [?exclude-tag1 ?exclude-tag2] ?page-uid
-                    :where [?p :block/uid ?page-uid]
-                           [?b :block/page ?p]
-                           [?b :block/string ?block-str]
-                           [?b :block/uid ?block-uid]
-                           (or [(clojure.string/includes? ?block-str ?primary-tag1)]
-                               [(clojure.string/includes? ?block-str ?primary-tag2)])
-                           (not (or [(clojure.string/includes? ?block-str ?exclude-tag1)]
-                                  [(clojure.string/includes? ?block-str ?exclude-tag2)]))]`;
-                queryParams = [primaryTagFormats, excludeTagFormats || ['', ''], targetPageUid];
-            }
-        }
-        else {
-            // Search across all pages
-            if (nearTagFormats) {
-                queryStr = `[:find ?block-uid ?block-str ?page-title
-                    :in $ [?primary-tag1 ?primary-tag2] [?near-tag1 ?near-tag2] [?exclude-tag1 ?exclude-tag2]
-                    :where [?b :block/string ?block-str]
-                           [?b :block/uid ?block-uid]
-                           [?b :block/page ?p]
-                           [?p :node/title ?page-title]
-                           (or [(clojure.string/includes? ?block-str ?primary-tag1)]
-                               [(clojure.string/includes? ?block-str ?primary-tag2)])
-                           (or [(clojure.string/includes? ?block-str ?near-tag1)]
-                               [(clojure.string/includes? ?block-str ?near-tag2)])
-                           (not (or [(clojure.string/includes? ?block-str ?exclude-tag1)]
-                                  [(clojure.string/includes? ?block-str ?exclude-tag2)]))]`;
-                queryParams = [primaryTagFormats, nearTagFormats, excludeTagFormats || ['', '']];
-            }
-            else {
-                queryStr = `[:find ?block-uid ?block-str ?page-title
-                    :in $ [?primary-tag1 ?primary-tag2] [?exclude-tag1 ?exclude-tag2]
-                    :where [?b :block/string ?block-str]
-                           [?b :block/uid ?block-uid]
-                           [?b :block/page ?p]
-                           [?p :node/title ?page-title]
-                           (or [(clojure.string/includes? ?block-str ?primary-tag1)]
-                               [(clojure.string/includes? ?block-str ?primary-tag2)])
-                           (not (or [(clojure.string/includes? ?block-str ?exclude-tag1)]
-                                  [(clojure.string/includes? ?block-str ?exclude-tag2)]))]`;
-                queryParams = [primaryTagFormats, excludeTagFormats || ['', '']];
-            }
-        }
+        // Build query to find blocks referencing the page
+        const queryStr = `[:find ?block-uid ?block-str ?page-title
+                      :in $ ?title
+                      :where 
+                      [?ref-page :node/title ?title-match]
+                      [(clojure.string/lower-case ?title-match) ?lower-title]
+                      [(clojure.string/lower-case ?title) ?search-title]
+                      [(= ?lower-title ?search-title)]
+                      [?b :block/refs ?ref-page]
+                      [?b :block/string ?block-str]
+                      [?b :block/uid ?block-uid]
+                      [?b :block/page ?p]
+                      [?p :node/title ?page-title]]`;
+        const queryParams = [primary_tag];
         const results = await q(this.graph, queryStr, queryParams);
-        const searchDescription = `containing ${primaryTagFormats.join(' or ')}${nearTagFormats ? ` near ${nearTagFormats.join(' or ')}` : ''}${excludeTagFormats ? ` excluding ${excludeTagFormats.join(' or ')}` : ''}`;
+        const searchDescription = `referencing "${primary_tag}"`;
         return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
     }
 }

package/build/search/text-search.js

@@ -0,0 +1,32 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { BaseSearchHandler } from './types.js';
+import { SearchUtils } from './utils.js';
+export class TextSearchHandler extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        const { text, page_title_uid, case_sensitive = false } = this.params;
+        // Get target page UID if provided for scoped search
+        let targetPageUid;
+        if (page_title_uid) {
+            targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
+        }
+        // Build query to find blocks containing the text
+        const queryStr = `[:find ?block-uid ?block-str ?page-title
+                      :in $ ?search-text
+                      :where 
+                      [?b :block/string ?block-str]
+                      [(clojure.string/includes? ${case_sensitive ? '?block-str' : '(clojure.string/lower-case ?block-str)'} 
+                                               ${case_sensitive ? '?search-text' : '(clojure.string/lower-case ?search-text)'})]
+                      [?b :block/uid ?block-uid]
+                      [?b :block/page ?p]
+                      [?p :node/title ?page-title]]`;
+        const queryParams = [text];
+        const results = await q(this.graph, queryStr, queryParams);
+        const searchDescription = `containing "${text}"${case_sensitive ? ' (case sensitive)' : ''}`;
+        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+    }
+}

package/build/server/roam-server.js

@@ -4,8 +4,8 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } f
 import { initializeGraph } from '@roam-research/roam-api-sdk';
 import { API_TOKEN, GRAPH_NAME } from '../config/environment.js';
 import { toolSchemas } from '../tools/schemas.js';
-import { ToolHandlers } from '../tools/handlers.js';
-import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler } from '../search/index.js';
+import { ToolHandlers } from '../tools/tool-handlers.js';
+import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler } from '../search/index.js';
 export class RoamServer {
     server;
     toolHandlers;
@@ -18,7 +18,7 @@ export class RoamServer {
         this.toolHandlers = new ToolHandlers(this.graph);
         this.server = new Server({
             name: 'roam-research',
-            version: '0.12.1',
+            version: '0.17.0',
         }, {
             capabilities: {
                 tools: {
@@ -31,7 +31,11 @@ export class RoamServer {
                     roam_search_for_tag: {},
                     roam_search_by_status: {},
                     roam_search_block_refs: {},
-                    roam_search_hierarchy: {}
+                    roam_search_hierarchy: {},
+                    find_pages_modified_today: {},
+                    roam_search_by_text: {},
+                    roam_update_block: {},
+                    roam_search_by_date: {}
                 },
             },
         });
@@ -125,6 +129,43 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
+                    case 'find_pages_modified_today': {
+                        const result = await this.toolHandlers.findPagesModifiedToday();
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                    case 'roam_search_by_text': {
+                        const params = request.params.arguments;
+                        const handler = new TextSearchHandler(this.graph, params);
+                        const result = await handler.execute();
+                        return {
+                            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;
+                        if (content) {
+                            result = await this.toolHandlers.updateBlock(block_uid, content);
+                        }
+                        else if (transform_pattern) {
+                            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) }],
+                        };
+                    }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }

package/build/tools/schemas.js

@@ -240,5 +240,111 @@ export const toolSchemas = {
                 { required: ['child_uid'] }
             ]
         }
+    },
+    find_pages_modified_today: {
+        name: 'find_pages_modified_today',
+        description: 'Find all pages that have been modified today (since midnight).',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
+    },
+    roam_search_by_text: {
+        name: 'roam_search_by_text',
+        description: 'Search for blocks containing specific text across all pages or within a specific page.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                text: {
+                    type: 'string',
+                    description: 'The text to search for'
+                },
+                page_title_uid: {
+                    type: 'string',
+                    description: 'Optional: Title or UID of the page to search in. If not provided, searches across all pages'
+                },
+                case_sensitive: {
+                    type: 'boolean',
+                    description: 'Optional: Whether to perform a case-sensitive search (default: false)'
+                }
+            },
+            required: ['text']
+        }
+    },
+    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.',
+        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'],
+            oneOf: [
+                { required: ['content'] },
+                { 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/{handlers.js → tool-handlers.js}

@@ -1,5 +1,5 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { q, createPage, createBlock, batchActions, } from '@roam-research/roam-api-sdk';
+import { q, createPage, createBlock, batchActions, updateBlock } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../utils/helpers.js';
 import { parseMarkdown, convertToRoamActions, convertToRoamMarkdown, hasMarkdownTable } from '../markdown-utils.js';
 // Helper function to capitalize each word
@@ -53,6 +53,46 @@ export class ToolHandlers {
     constructor(graph) {
         this.graph = graph;
     }
+    async findPagesModifiedToday() {
+        // Define ancestor rule for traversing block hierarchy
+        const ancestorRule = `[
+      [ (ancestor ?b ?a)
+        [?a :block/children ?b] ]
+      [ (ancestor ?b ?a)
+        [?parent :block/children ?b]
+        (ancestor ?parent ?a) ]
+    ]`;
+        // Get start of today
+        const startOfDay = new Date();
+        startOfDay.setHours(0, 0, 0, 0);
+        try {
+            // Query for pages modified today
+            const results = await q(this.graph, `[:find ?title
+          :in $ ?start_of_day %
+          :where
+          [?page :node/title ?title]
+          (ancestor ?block ?page)
+          [?block :edit/time ?time]
+          [(> ?time ?start_of_day)]]`, [startOfDay.getTime(), ancestorRule]);
+            if (!results || results.length === 0) {
+                return {
+                    success: true,
+                    pages: [],
+                    message: 'No pages have been modified today'
+                };
+            }
+            // Extract unique page titles
+            const uniquePages = [...new Set(results.map(([title]) => title))];
+            return {
+                success: true,
+                pages: uniquePages,
+                message: `Found ${uniquePages.length} page(s) modified today`
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to find modified pages: ${error.message}`);
+        }
+    }
     async createOutline(outline, page_title_uid, block_text_uid) {
         // Validate input
         if (!Array.isArray(outline) || outline.length === 0) {
@@ -295,71 +335,78 @@ export class ToolHandlers {
         if (!uid) {
             throw new McpError(ErrorCode.InvalidRequest, `Page with title "${title}" not found (tried original, capitalized words, and lowercase)`);
         }
-        // Get all blocks under this page with their order and parent relationships
+        // Define ancestor rule for traversing block hierarchy
+        const ancestorRule = `[
+      [ (ancestor ?b ?a)
+        [?a :block/children ?b] ]
+      [ (ancestor ?b ?a)
+        [?parent :block/children ?b]
+        (ancestor ?parent ?a) ]
+    ]`;
+        // Get all blocks under this page using ancestor rule
         const blocksQuery = `[:find ?block-uid ?block-str ?order ?parent-uid
-                        :where [?p :block/uid "${uid}"]
-                               [?b :block/page ?p]
-                               [?b :block/uid ?block-uid]
-                               [?b :block/string ?block-str]
-                               [?b :block/order ?order]
-                               [?b :block/parents ?parent]
+                        :in $ % ?page-title
+                        :where [?page :node/title ?page-title]
+                               [?block :block/string ?block-str]
+                               [?block :block/uid ?block-uid]
+                               [?block :block/order ?order]
+                               (ancestor ?block ?page)
+                               [?parent :block/children ?block]
                                [?parent :block/uid ?parent-uid]]`;
-        const blocks = await q(this.graph, blocksQuery, []);
-        if (blocks.length > 0) {
-            const blockMap = new Map();
-            for (const [uid, string, order] of blocks) {
-                if (!blockMap.has(uid)) {
-                    const resolvedString = await resolveRefs(this.graph, string);
-                    blockMap.set(uid, {
-                        uid,
-                        string: resolvedString,
-                        order: order,
-                        children: []
-                    });
-                }
+        const blocks = await q(this.graph, blocksQuery, [ancestorRule, title]);
+        if (!blocks || blocks.length === 0) {
+            return `${title} (no content found)`;
+        }
+        // Create a map of all blocks
+        const blockMap = new Map();
+        const rootBlocks = [];
+        // First pass: Create all block objects
+        for (const [blockUid, blockStr, order, parentUid] of blocks) {
+            const resolvedString = await resolveRefs(this.graph, blockStr);
+            const block = {
+                uid: blockUid,
+                string: resolvedString,
+                order: order,
+                children: []
+            };
+            blockMap.set(blockUid, block);
+            // If no parent or parent is the page itself, it's a root block
+            if (!parentUid || parentUid === uid) {
+                rootBlocks.push(block);
             }
-            // Build parent-child relationships
-            blocks.forEach(([childUid, _, __, parentUid]) => {
-                const child = blockMap.get(childUid);
+        }
+        // Second pass: Build parent-child relationships
+        for (const [blockUid, _, __, parentUid] of blocks) {
+            if (parentUid && parentUid !== uid) {
+                const child = blockMap.get(blockUid);
                 const parent = blockMap.get(parentUid);
                 if (child && parent && !parent.children.includes(child)) {
                     parent.children.push(child);
                 }
-            });
-            // Get top-level blocks
-            const topQuery = `[:find ?block-uid ?block-str ?order
-                       :where [?p :block/uid "${uid}"]
-                              [?b :block/page ?p]
-                              [?b :block/uid ?block-uid]
-                              [?b :block/string ?block-str]
-                              [?b :block/order ?order]
-                              (not-join [?b]
-                                [?b :block/parents ?parent]
-                                [?parent :block/page ?p])]`;
-            const topBlocks = await q(this.graph, topQuery, []);
-            // Create root blocks
-            const rootBlocks = topBlocks
-                .map(([uid, string, order]) => ({
-                uid,
-                string,
-                order: order,
-                children: blockMap.get(uid)?.children || []
-            }))
-                .sort((a, b) => a.order - b.order);
-            // Convert to markdown
-            const toMarkdown = (blocks, level = 0) => {
-                return blocks.map(block => {
-                    const indent = '  '.repeat(level);
-                    let md = `${indent}- ${block.string}\n`;
-                    if (block.children.length > 0) {
-                        md += toMarkdown(block.children.sort((a, b) => a.order - b.order), level + 1);
-                    }
-                    return md;
-                }).join('');
-            };
-            return `# ${title}\n\n${toMarkdown(rootBlocks)}`;
+            }
         }
-        return `${title} (no content found)`;
+        // Sort blocks recursively
+        const sortBlocks = (blocks) => {
+            blocks.sort((a, b) => a.order - b.order);
+            blocks.forEach(block => {
+                if (block.children.length > 0) {
+                    sortBlocks(block.children);
+                }
+            });
+        };
+        sortBlocks(rootBlocks);
+        // Convert to markdown with proper nesting
+        const toMarkdown = (blocks, level = 0) => {
+            return blocks.map(block => {
+                const indent = '  '.repeat(level);
+                let md = `${indent}- ${block.string}`;
+                if (block.children.length > 0) {
+                    md += '\n' + toMarkdown(block.children, level + 1);
+                }
+                return md;
+            }).join('\n');
+        };
+        return `# ${title}\n\n${toMarkdown(rootBlocks)}`;
     }
     async createPage(title, content) {
         // Ensure title is properly formatted
@@ -634,6 +681,53 @@ export class ToolHandlers {
             };
         }
     }
+    async updateBlock(block_uid, content, transform) {
+        if (!block_uid) {
+            throw new McpError(ErrorCode.InvalidRequest, 'block_uid is required');
+        }
+        // Get current block content
+        const blockQuery = `[:find ?string .
+                        :where [?b :block/uid "${block_uid}"]
+                               [?b :block/string ?string]]`;
+        const result = await q(this.graph, blockQuery, []);
+        if (result === null || result === undefined) {
+            throw new McpError(ErrorCode.InvalidRequest, `Block with UID "${block_uid}" not found`);
+        }
+        const currentContent = String(result);
+        if (currentContent === null || currentContent === undefined) {
+            throw new McpError(ErrorCode.InvalidRequest, `Block with UID "${block_uid}" not found`);
+        }
+        // Determine new content
+        let newContent;
+        if (content) {
+            newContent = content;
+        }
+        else if (transform) {
+            newContent = transform(currentContent);
+        }
+        else {
+            throw new McpError(ErrorCode.InvalidRequest, 'Either content or transform function must be provided');
+        }
+        try {
+            const success = await updateBlock(this.graph, {
+                action: 'update-block',
+                block: {
+                    uid: block_uid,
+                    string: newContent
+                }
+            });
+            if (!success) {
+                throw new Error('Failed to update block');
+            }
+            return {
+                success: true,
+                content: newContent
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to update block: ${error.message}`);
+        }
+    }
     async searchByStatus(status, page_title_uid, include, exclude) {
         // Get target page UID if provided
         let targetPageUid;
@@ -658,15 +752,6 @@ export class ToolHandlers {
         let queryStr;
         let queryParams;
         const statusPattern = `{{[[${status}]]}}`;
-        // Helper function to get parent block content
-        const getParentContent = async (blockUid) => {
-            const parentQuery = `[:find ?parent-str .
-                          :where [?b :block/uid "${blockUid}"]
-                                 [?b :block/parents ?parent]
-                                 [?parent :block/string ?parent-str]]`;
-            const result = await q(this.graph, parentQuery, []);
-            return result ? String(result) : null;
-        };
         if (targetPageUid) {
             queryStr = `[:find ?block-uid ?block-str
                   :in $ ?status-pattern ?page-uid
@@ -815,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.14.0",
+  "version": "0.18.0",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {

package/build/search/date-search.js

@@ -1,38 +0,0 @@
-import { q } from '@roam-research/roam-api-sdk';
-import { BaseSearchHandler } from './types.js';
-import { SearchUtils } from './utils.js';
-export class DateSearchHandler extends BaseSearchHandler {
-    params;
-    constructor(graph, params) {
-        super(graph);
-        this.params = params;
-    }
-    async execute() {
-        const { start_date, end_date, filter_tag } = this.params;
-        const [startDateFormatted, endDateFormatted] = SearchUtils.parseDateRange(start_date, end_date);
-        const filterTagFormatted = filter_tag ? `[[${filter_tag}]]` : undefined;
-        // Build Roam query string
-        const dateQuery = `{between: [[${startDateFormatted}]] [[${endDateFormatted}]]}`;
-        const query = filterTagFormatted
-            ? `{{query: {and: ${filterTagFormatted} ${dateQuery}}}}`
-            : `{{query: ${dateQuery}}}`;
-        // Log the query for debugging
-        console.log('Roam query:', query);
-        // Find blocks matching the query
-        const queryStr = `[:find ?block-uid ?block-str ?page-title
-                      :in $ ?query-str
-                      :where [?b :block/string ?block-str]
-                             [?b :block/uid ?block-uid]
-                             [?b :block/page ?p]
-                             [?p :node/title ?page-title]
-                             [(clojure.string/includes? ?block-str ?query-str)]]`;
-        const results = await q(this.graph, queryStr, [query]);
-        const dateRange = start_date === end_date
-            ? `on ${SearchUtils.parseDate(start_date)}`
-            : `between ${SearchUtils.parseDate(start_date)} and ${SearchUtils.parseDate(end_date)}`;
-        const searchDescription = filterTagFormatted
-            ? `${dateRange} containing ${filterTagFormatted}`
-            : dateRange;
-        return SearchUtils.formatSearchResults(results, searchDescription, true);
-    }
-}