roam-research-mcp 0.2.0 → 0.14.0

package/README.md

@@ -6,6 +6,8 @@
 
 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 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>
+
 ## Installation
 
 You can install the package globally:
@@ -25,7 +27,7 @@ npm run build
 
 ## Features
 
-The server provides six powerful tools for interacting with Roam Research:
+The server provides eight 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
@@ -33,6 +35,8 @@ The server provides six powerful tools for interacting with Roam Research:
 4. `roam_import_markdown`: Import nested markdown content under specific blocks
 5. `roam_add_todo`: Add multiple todo items to today's daily page with checkbox syntax
 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
 
 ## Setup
 
@@ -278,6 +282,92 @@ Parameters:
 - `parent_string`: Exact string content of the parent block (must provide either page_uid or page_title)
 - `order`: Where to add the content ("first" or "last", defaults to "first")
 
+### Search Block References
+
+Search for block references within pages or across the entire graph:
+
+```typescript
+use_mcp_tool roam-research roam_search_block_refs {
+  "block_uid": "optional-block-uid",
+  "page_title_uid": "optional-page-title-or-uid"
+}
+```
+
+Features:
+
+- Find all references to a specific block
+- Search for any block references within a page
+- Search across the entire graph
+- Supports both direct and indirect references
+- Includes block content and location context
+
+Parameters:
+
+- `block_uid`: UID of the block to find references to (optional)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "referenced-block-uid",
+      "content": "Block content with ((reference))",
+      "page_title": "Page containing reference"
+    }
+  ],
+  "message": "Found N block(s) referencing..."
+}
+```
+
+### Search Block Hierarchy
+
+Navigate and search through block parent-child relationships:
+
+```typescript
+use_mcp_tool roam-research roam_search_hierarchy {
+  "parent_uid": "optional-parent-block-uid",
+  "child_uid": "optional-child-block-uid",
+  "page_title_uid": "optional-page-title-or-uid",
+  "max_depth": 3
+}
+```
+
+Features:
+
+- Search up or down the block hierarchy
+- Find children of a specific block
+- Find parents of a specific block
+- Configure search depth (1-10 levels)
+- Optional page scope filtering
+- Includes depth information for each result
+
+Parameters:
+
+- `parent_uid`: UID of the block to find children of (required if searching down)
+- `child_uid`: UID of the block to find parents of (required if searching up)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+- `max_depth`: How many levels deep to search (optional, default: 1, max: 10)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "related-block-uid",
+      "content": "Block content",
+      "depth": 2,
+      "page_title": "Page containing block"
+    }
+  ],
+  "message": "Found N block(s) as children/parents..."
+}
+```
+
 ## Error Handling
 
 The server provides comprehensive error handling for common scenarios:

package/build/search/block-ref-search.js

@@ -0,0 +1,72 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { BaseSearchHandler } from './types.js';
+import { SearchUtils } from './utils.js';
+export class BlockRefSearchHandler extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        const { block_uid, page_title_uid } = this.params;
+        // Get target page UID if provided
+        let targetPageUid;
+        if (page_title_uid) {
+            targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
+        }
+        // Build query based on whether we're searching for references to a specific block
+        // or all block references within a page/graph
+        let queryStr;
+        let queryParams;
+        if (block_uid) {
+            // Search for references to a specific block
+            if (targetPageUid) {
+                queryStr = `[:find ?block-uid ?block-str
+                    :in $ ?ref-uid ?page-uid
+                    :where [?p :block/uid ?page-uid]
+                           [?b :block/page ?p]
+                           [?b :block/string ?block-str]
+                           [?b :block/uid ?block-uid]
+                           [(clojure.string/includes? ?block-str ?ref-uid)]]`;
+                queryParams = [`((${block_uid}))`, targetPageUid];
+            }
+            else {
+                queryStr = `[:find ?block-uid ?block-str ?page-title
+                    :in $ ?ref-uid
+                    :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 ?ref-uid)]]`;
+                queryParams = [`((${block_uid}))`];
+            }
+        }
+        else {
+            // Search for any block references
+            if (targetPageUid) {
+                queryStr = `[:find ?block-uid ?block-str
+                    :in $ ?page-uid
+                    :where [?p :block/uid ?page-uid]
+                           [?b :block/page ?p]
+                           [?b :block/string ?block-str]
+                           [?b :block/uid ?block-uid]
+                           [(re-find #"\\(\\([^)]+\\)\\)" ?block-str)]]`;
+                queryParams = [targetPageUid];
+            }
+            else {
+                queryStr = `[:find ?block-uid ?block-str ?page-title
+                    :where [?b :block/string ?block-str]
+                           [?b :block/uid ?block-uid]
+                           [?b :block/page ?p]
+                           [?p :node/title ?page-title]
+                           [(re-find #"\\(\\([^)]+\\)\\)" ?block-str)]]`;
+                queryParams = [];
+            }
+        }
+        const results = await q(this.graph, queryStr, queryParams);
+        const searchDescription = block_uid
+            ? `referencing block ((${block_uid}))`
+            : 'containing block references';
+        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+    }
+}

package/build/search/date-search.js

@@ -0,0 +1,38 @@
+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);
+    }
+}

package/build/search/hierarchy-search.js

@@ -0,0 +1,101 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { BaseSearchHandler } from './types.js';
+import { SearchUtils } from './utils.js';
+export class HierarchySearchHandler extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        const { parent_uid, child_uid, page_title_uid, max_depth = 1 } = this.params;
+        if (!parent_uid && !child_uid) {
+            return {
+                success: false,
+                matches: [],
+                message: 'Either parent_uid or child_uid must be provided'
+            };
+        }
+        // Get target page UID if provided
+        let targetPageUid;
+        if (page_title_uid) {
+            targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
+        }
+        let queryStr;
+        let queryParams;
+        if (parent_uid) {
+            // Search for children of a specific block
+            if (targetPageUid) {
+                queryStr = `[:find ?block-uid ?block-str ?depth
+                    :in $ ?parent-uid ?page-uid ?max-depth
+                    :where [?p :block/uid ?page-uid]
+                           [?parent :block/uid ?parent-uid]
+                           [?b :block/parents ?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];
+            }
+            else {
+                queryStr = `[:find ?block-uid ?block-str ?page-title ?depth
+                    :in $ ?parent-uid ?max-depth
+                    :where [?parent :block/uid ?parent-uid]
+                           [?b :block/parents ?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];
+            }
+        }
+        else {
+            // Search for parents of a specific block
+            if (targetPageUid) {
+                queryStr = `[:find ?block-uid ?block-str ?depth
+                    :in $ ?child-uid ?page-uid ?max-depth
+                    :where [?p :block/uid ?page-uid]
+                           [?child :block/uid ?child-uid]
+                           [?child :block/parents ?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];
+            }
+            else {
+                queryStr = `[:find ?block-uid ?block-str ?page-title ?depth
+                    :in $ ?child-uid ?max-depth
+                    :where [?child :block/uid ?child-uid]
+                           [?child :block/parents ?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];
+            }
+        }
+        const results = await q(this.graph, queryStr, queryParams);
+        // Format results to include depth information
+        const matches = results.map(([uid, content, pageTitle, depth]) => ({
+            block_uid: uid,
+            content,
+            depth: depth || 1,
+            ...(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})`;
+        return {
+            success: true,
+            matches,
+            message: `Found ${matches.length} block(s) as ${searchDescription}`
+        };
+    }
+}

package/build/search/index.js

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './utils.js';
+export * from './tag-search.js';
+export * from './status-search.js';
+export * from './block-ref-search.js';
+export * from './hierarchy-search.js';

package/build/search/status-search.js

@@ -0,0 +1,43 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { BaseSearchHandler } from './types.js';
+import { SearchUtils } from './utils.js';
+export class StatusSearchHandler extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        const { status, page_title_uid } = this.params;
+        // Get target page UID if provided
+        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
+        let queryStr;
+        let queryParams;
+        if (targetPageUid) {
+            queryStr = `[:find ?block-uid ?block-str
+                  :in $ ?status ?page-uid
+                  :where [?p :block/uid ?page-uid]
+                         [?b :block/page ?p]
+         [?b :block/string ?block-str]
+         [?b :block/uid ?block-uid]
+         [(clojure.string/includes? ?block-str (str "{{[[" ?status "]]}}"))]]`;
+            queryParams = [status, targetPageUid];
+        }
+        else {
+            queryStr = `[:find ?block-uid ?block-str ?page-title
+                  :in $ ?status
+                  :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 (str "{{[[" ?status "]]}}"))]]`;
+            queryParams = [status];
+        }
+        const results = await q(this.graph, queryStr, queryParams);
+        return SearchUtils.formatSearchResults(results, `with status ${status}`, !targetPageUid);
+    }
+}

package/build/search/tag-search.js

@@ -0,0 +1,89 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { BaseSearchHandler } from './types.js';
+import { SearchUtils } from './utils.js';
+export class TagSearchHandler extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    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
+        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 || ['', '']];
+            }
+        }
+        const results = await q(this.graph, queryStr, queryParams);
+        const searchDescription = `containing ${primaryTagFormats.join(' or ')}${nearTagFormats ? ` near ${nearTagFormats.join(' or ')}` : ''}${excludeTagFormats ? ` excluding ${excludeTagFormats.join(' or ')}` : ''}`;
+        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+    }
+}

package/build/search/types.js

@@ -0,0 +1,7 @@
+// Base class for all search handlers
+export class BaseSearchHandler {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+}

package/build/search/utils.js

@@ -0,0 +1,98 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { q } from '@roam-research/roam-api-sdk';
+export class SearchUtils {
+    /**
+     * Find a page by title or UID
+     */
+    static async findPageByTitleOrUid(graph, titleOrUid) {
+        // Try to find page by title
+        const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+        const findResults = await q(graph, findQuery, [titleOrUid]);
+        if (findResults && findResults.length > 0) {
+            return findResults[0][0];
+        }
+        // Try as UID
+        const uidQuery = `[:find ?uid :where [?e :block/uid "${titleOrUid}"] [?e :block/uid ?uid]]`;
+        const uidResults = await q(graph, uidQuery, []);
+        if (!uidResults || uidResults.length === 0) {
+            throw new McpError(ErrorCode.InvalidRequest, `Page with title/UID "${titleOrUid}" not found`);
+        }
+        return uidResults[0][0];
+    }
+    /**
+     * Format search results into a standard structure
+     */
+    static formatSearchResults(results, searchDescription, includePageTitle = true) {
+        if (!results || results.length === 0) {
+            return {
+                success: true,
+                matches: [],
+                message: `No blocks found ${searchDescription}`
+            };
+        }
+        const matches = results.map(([uid, content, pageTitle]) => ({
+            block_uid: uid,
+            content,
+            ...(includePageTitle && pageTitle && { page_title: pageTitle })
+        }));
+        return {
+            success: true,
+            matches,
+            message: `Found ${matches.length} block(s) ${searchDescription}`
+        };
+    }
+    /**
+     * Format a tag for searching, handling both # and [[]] formats
+     * @param tag Tag without prefix
+     * @returns Array of possible formats to search for
+     */
+    static formatTag(tag) {
+        // Remove any existing prefixes
+        const cleanTag = tag.replace(/^#|\[\[|\]\]$/g, '');
+        // Return both formats for comprehensive search
+        return [`#${cleanTag}`, `[[${cleanTag}]]`];
+    }
+    /**
+     * Parse a date string into a Roam-formatted date
+     */
+    static parseDate(dateStr) {
+        const date = new Date(dateStr);
+        const months = [
+            'January', 'February', 'March', 'April', 'May', 'June',
+            'July', 'August', 'September', 'October', 'November', 'December'
+        ];
+        // Adjust for timezone to ensure consistent date comparison
+        const utcDate = new Date(date.getTime() + date.getTimezoneOffset() * 60000);
+        return `${months[utcDate.getMonth()]} ${utcDate.getDate()}${this.getOrdinalSuffix(utcDate.getDate())}, ${utcDate.getFullYear()}`;
+    }
+    /**
+     * Parse a date string into a Roam-formatted date range
+     * Returns [startDate, endDate] with endDate being inclusive (end of day)
+     */
+    static parseDateRange(startStr, endStr) {
+        const startDate = new Date(startStr);
+        const endDate = new Date(endStr);
+        endDate.setHours(23, 59, 59, 999); // Make end date inclusive
+        const months = [
+            'January', 'February', 'March', 'April', 'May', 'June',
+            'July', 'August', 'September', 'October', 'November', 'December'
+        ];
+        // Adjust for timezone
+        const utcStart = new Date(startDate.getTime() + startDate.getTimezoneOffset() * 60000);
+        const utcEnd = new Date(endDate.getTime() + endDate.getTimezoneOffset() * 60000);
+        return [
+            `${months[utcStart.getMonth()]} ${utcStart.getDate()}${this.getOrdinalSuffix(utcStart.getDate())}, ${utcStart.getFullYear()}`,
+            `${months[utcEnd.getMonth()]} ${utcEnd.getDate()}${this.getOrdinalSuffix(utcEnd.getDate())}, ${utcEnd.getFullYear()}`
+        ];
+    }
+    static getOrdinalSuffix(day) {
+        if (day > 3 && day < 21)
+            return 'th';
+        switch (day % 10) {
+            case 1: return 'st';
+            case 2: return 'nd';
+            case 3: return 'rd';
+            default: return 'th';
+        }
+    }
+}

package/build/server/roam-server.js

@@ -5,15 +5,17 @@ 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';
 export class RoamServer {
     server;
     toolHandlers;
+    graph;
     constructor() {
-        const graph = initializeGraph({
+        this.graph = initializeGraph({
             token: API_TOKEN,
             graph: GRAPH_NAME,
         });
-        this.toolHandlers = new ToolHandlers(graph);
+        this.toolHandlers = new ToolHandlers(this.graph);
         this.server = new Server({
             name: 'roam-research',
             version: '0.12.1',
@@ -25,7 +27,11 @@ export class RoamServer {
                     roam_create_page: {},
                     roam_create_block: {},
                     roam_import_markdown: {},
-                    roam_create_outline: {}
+                    roam_create_outline: {},
+                    roam_search_for_tag: {},
+                    roam_search_by_status: {},
+                    roam_search_block_refs: {},
+                    roam_search_hierarchy: {}
                 },
             },
         });
@@ -88,6 +94,37 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
+                    case 'roam_search_for_tag': {
+                        const params = request.params.arguments;
+                        const handler = new TagSearchHandler(this.graph, params);
+                        const result = await handler.execute();
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                    case 'roam_search_by_status': {
+                        const { status, page_title_uid, include, exclude } = request.params.arguments;
+                        const result = await this.toolHandlers.searchByStatus(status, page_title_uid, include, exclude);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                    case 'roam_search_block_refs': {
+                        const params = request.params.arguments;
+                        const handler = new BlockRefSearchHandler(this.graph, params);
+                        const result = await handler.execute();
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                    case 'roam_search_hierarchy': {
+                        const params = request.params.arguments;
+                        const handler = new HierarchySearchHandler(this.graph, params);
+                        const result = await handler.execute();
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }

package/build/tools/handlers.js

@@ -634,6 +634,187 @@ export class ToolHandlers {
             };
         }
     }
+    async searchByStatus(status, page_title_uid, include, exclude) {
+        // Get target page UID if provided
+        let targetPageUid;
+        if (page_title_uid) {
+            // Try to find page by title or UID
+            const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+            const findResults = await q(this.graph, findQuery, [page_title_uid]);
+            if (findResults && findResults.length > 0) {
+                targetPageUid = findResults[0][0];
+            }
+            else {
+                // Try as UID
+                const uidQuery = `[:find ?uid :where [?e :block/uid "${page_title_uid}"] [?e :block/uid ?uid]]`;
+                const uidResults = await q(this.graph, uidQuery, []);
+                if (!uidResults || uidResults.length === 0) {
+                    throw new McpError(ErrorCode.InvalidRequest, `Page with title/UID "${page_title_uid}" not found`);
+                }
+                targetPageUid = uidResults[0][0];
+            }
+        }
+        // Build query based on whether we're searching in a specific page
+        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
+                  :where [?p :block/uid ?page-uid]
+                         [?b :block/page ?p]
+                         [?b :block/string ?block-str]
+                         [?b :block/uid ?block-uid]
+                         [(clojure.string/includes? ?block-str ?status-pattern)]]`;
+            queryParams = [statusPattern, targetPageUid];
+        }
+        else {
+            queryStr = `[:find ?block-uid ?block-str ?page-title
+                  :in $ ?status-pattern
+                  :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 ?status-pattern)]]`;
+            queryParams = [statusPattern];
+        }
+        const results = await q(this.graph, queryStr, queryParams);
+        if (!results || results.length === 0) {
+            return {
+                success: true,
+                matches: [],
+                message: `No blocks found with status ${status}`
+            };
+        }
+        // Format initial results
+        let matches = results.map(result => {
+            const [uid, content, pageTitle] = result;
+            return {
+                block_uid: uid,
+                content,
+                ...(pageTitle && { page_title: pageTitle })
+            };
+        });
+        // Post-query filtering
+        if (include) {
+            const includeTerms = include.toLowerCase().split(',').map(term => term.trim());
+            matches = matches.filter(match => includeTerms.some(term => match.content.toLowerCase().includes(term) ||
+                (match.page_title && match.page_title.toLowerCase().includes(term))));
+        }
+        if (exclude) {
+            const excludeTerms = exclude.toLowerCase().split(',').map(term => term.trim());
+            matches = matches.filter(match => !excludeTerms.some(term => match.content.toLowerCase().includes(term) ||
+                (match.page_title && match.page_title.toLowerCase().includes(term))));
+        }
+        return {
+            success: true,
+            matches,
+            message: `Found ${matches.length} block(s) with status ${status}${include ? ` including "${include}"` : ''}${exclude ? ` excluding "${exclude}"` : ''}`
+        };
+    }
+    async searchForTag(primary_tag, page_title_uid, near_tag) {
+        // Ensure tags are properly formatted with #
+        const formatTag = (tag) => tag.startsWith('#') ? tag : `#${tag}`;
+        const primaryTagFormatted = formatTag(primary_tag);
+        const nearTagFormatted = near_tag ? formatTag(near_tag) : undefined;
+        // Get target page UID if provided
+        let targetPageUid;
+        if (page_title_uid) {
+            // Try to find page by title or UID
+            const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+            const findResults = await q(this.graph, findQuery, [page_title_uid]);
+            if (findResults && findResults.length > 0) {
+                targetPageUid = findResults[0][0];
+            }
+            else {
+                // Try as UID
+                const uidQuery = `[:find ?uid :where [?e :block/uid "${page_title_uid}"] [?e :block/uid ?uid]]`;
+                const uidResults = await q(this.graph, uidQuery, []);
+                if (!uidResults || uidResults.length === 0) {
+                    throw new McpError(ErrorCode.InvalidRequest, `Page with title/UID "${page_title_uid}" not found`);
+                }
+                targetPageUid = uidResults[0][0];
+            }
+        }
+        // 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 (nearTagFormatted) {
+                queryStr = `[:find ?block-uid ?block-str
+                    :in $ ?primary-tag ?near-tag ?page-uid
+                    :where [?p :block/uid ?page-uid]
+                           [?b :block/page ?p]
+                           [?b :block/string ?block-str]
+                           [?b :block/uid ?block-uid]
+                           [(clojure.string/includes? ?block-str ?primary-tag)]
+                           [(clojure.string/includes? ?block-str ?near-tag)]]`;
+                queryParams = [primaryTagFormatted, nearTagFormatted, targetPageUid];
+            }
+            else {
+                queryStr = `[:find ?block-uid ?block-str
+                    :in $ ?primary-tag ?page-uid
+                    :where [?p :block/uid ?page-uid]
+                           [?b :block/page ?p]
+                           [?b :block/string ?block-str]
+                           [?b :block/uid ?block-uid]
+                           [(clojure.string/includes? ?block-str ?primary-tag)]]`;
+                queryParams = [primaryTagFormatted, targetPageUid];
+            }
+        }
+        else {
+            // Search across all pages
+            if (nearTagFormatted) {
+                queryStr = `[:find ?block-uid ?block-str ?page-title
+                    :in $ ?primary-tag ?near-tag
+                    :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 ?primary-tag)]
+                           [(clojure.string/includes? ?block-str ?near-tag)]]`;
+                queryParams = [primaryTagFormatted, nearTagFormatted];
+            }
+            else {
+                queryStr = `[:find ?block-uid ?block-str ?page-title
+                    :in $ ?primary-tag
+                    :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 ?primary-tag)]]`;
+                queryParams = [primaryTagFormatted];
+            }
+        }
+        const results = await q(this.graph, queryStr, queryParams);
+        if (!results || results.length === 0) {
+            return {
+                success: true,
+                matches: [],
+                message: `No blocks found containing ${primaryTagFormatted}${nearTagFormatted ? ` near ${nearTagFormatted}` : ''}`
+            };
+        }
+        // Format results
+        const matches = results.map(([uid, content, pageTitle]) => ({
+            block_uid: uid,
+            content,
+            ...(pageTitle && { page_title: pageTitle })
+        }));
+        return {
+            success: true,
+            matches,
+            message: `Found ${matches.length} block(s) containing ${primaryTagFormatted}${nearTagFormatted ? ` near ${nearTagFormatted}` : ''}`
+        };
+    }
     async addTodos(todos) {
         if (!Array.isArray(todos) || todos.length === 0) {
             throw new McpError(ErrorCode.InvalidRequest, 'todos must be a non-empty array');

package/build/tools/schemas.js

@@ -73,8 +73,8 @@ export const toolSchemas = {
         },
     },
     roam_create_outline: {
-        name: 'roam_create_outline',
-        description: 'Create a structured outline in Roam from an array of outline items with explicit levels. Can be added under a specific page or block.',
+        name: 'roam_create_output_with_nested_structure',
+        description: 'Create a structured outline or output with nested structure in Roam from an array of items with explicit levels. Can be added on a specific page or under a specific block.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -144,4 +144,101 @@ export const toolSchemas = {
             required: ['content']
         }
     },
+    roam_search_for_tag: {
+        name: 'roam_search_for_tag',
+        description: 'Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                primary_tag: {
+                    type: 'string',
+                    description: 'The main tag to search for (without the [[ ]] brackets)',
+                },
+                page_title_uid: {
+                    type: 'string',
+                    description: 'Optional: Title or UID of the page to search in. Defaults to today\'s daily page if not provided',
+                },
+                near_tag: {
+                    type: 'string',
+                    description: 'Optional: Another tag to filter results by - will only return blocks where both tags appear',
+                }
+            },
+            required: ['primary_tag']
+        }
+    },
+    roam_search_by_status: {
+        name: 'roam_search_by_status',
+        description: 'Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    description: 'Status to search for (TODO or DONE)',
+                    enum: ['TODO', 'DONE']
+                },
+                page_title_uid: {
+                    type: 'string',
+                    description: 'Optional: Title or UID of the page to search in. If not provided, searches across all pages'
+                },
+                include: {
+                    type: 'string',
+                    description: 'Optional: Comma-separated list of terms to filter results by inclusion (matches content or page title)'
+                },
+                exclude: {
+                    type: 'string',
+                    description: 'Optional: Comma-separated list of terms to filter results by exclusion (matches content or page title)'
+                }
+            },
+            required: ['status']
+        }
+    },
+    roam_search_block_refs: {
+        name: 'roam_search_block_refs',
+        description: 'Search for block references within a page or across the entire graph. Can search for references to a specific block or find all block references.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                block_uid: {
+                    type: 'string',
+                    description: 'Optional: UID of the block to find references to'
+                },
+                page_title_uid: {
+                    type: 'string',
+                    description: 'Optional: Title or UID of the page to search in. If not provided, searches across all pages'
+                }
+            }
+        }
+    },
+    roam_search_hierarchy: {
+        name: 'roam_search_hierarchy',
+        description: 'Search for parent or child blocks in the block hierarchy. Can search up or down the hierarchy from a given block.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                parent_uid: {
+                    type: 'string',
+                    description: 'Optional: UID of the block to find children of'
+                },
+                child_uid: {
+                    type: 'string',
+                    description: 'Optional: UID of the block to find parents of'
+                },
+                page_title_uid: {
+                    type: 'string',
+                    description: 'Optional: Title or UID of the page to search in'
+                },
+                max_depth: {
+                    type: 'integer',
+                    description: 'Optional: How many levels deep to search (default: 1)',
+                    minimum: 1,
+                    maximum: 10
+                }
+            },
+            oneOf: [
+                { required: ['parent_uid'] },
+                { required: ['child_uid'] }
+            ]
+        }
+    }
 };

package/package.json

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