roam-research-mcp 0.20.0 → 0.22.1

package/build/tools/operations/search/index.js

@@ -0,0 +1,95 @@
+import { TagSearchHandlerImpl, BlockRefSearchHandlerImpl, HierarchySearchHandlerImpl, TextSearchHandlerImpl } from './handlers.js';
+export class SearchOperations {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    async searchByStatus(status, page_title_uid, include, exclude) {
+        const handler = new TagSearchHandlerImpl(this.graph, {
+            primary_tag: `{{[[${status}]]}}`,
+            page_title_uid,
+        });
+        const result = await handler.execute();
+        // Post-process results with include/exclude filters
+        let matches = result.matches;
+        if (include) {
+            const includeTerms = include.split(',').map(term => term.trim());
+            matches = matches.filter(match => {
+                const matchContent = match.content;
+                const matchTitle = match.page_title;
+                const terms = includeTerms;
+                return terms.some(term => matchContent.includes(term) ||
+                    (matchTitle && matchTitle.includes(term)));
+            });
+        }
+        if (exclude) {
+            const excludeTerms = exclude.split(',').map(term => term.trim());
+            matches = matches.filter(match => {
+                const matchContent = match.content;
+                const matchTitle = match.page_title;
+                const terms = excludeTerms;
+                return !terms.some(term => matchContent.includes(term) ||
+                    (matchTitle && matchTitle.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) {
+        const handler = new TagSearchHandlerImpl(this.graph, {
+            primary_tag,
+            page_title_uid,
+            near_tag,
+        });
+        return handler.execute();
+    }
+    async searchBlockRefs(params) {
+        const handler = new BlockRefSearchHandlerImpl(this.graph, params);
+        return handler.execute();
+    }
+    async searchHierarchy(params) {
+        const handler = new HierarchySearchHandlerImpl(this.graph, params);
+        return handler.execute();
+    }
+    async searchByText(params) {
+        const handler = new TextSearchHandlerImpl(this.graph, params);
+        return handler.execute();
+    }
+    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;
+        // Use text search handler for content-based filtering
+        const handler = new TextSearchHandlerImpl(this.graph, {
+            text: '', // Empty text to match all blocks
+        });
+        const result = await handler.execute();
+        // Filter results by date
+        const matches = result.matches
+            .filter(match => {
+            const time = params.type === 'created' ?
+                new Date(match.content || '').getTime() : // Use content date for creation time
+                Date.now(); // Use current time for modification time (simplified)
+            return time >= startTimestamp && (!endTimestamp || time <= endTimestamp);
+        })
+            .map(match => ({
+            uid: match.block_uid,
+            type: 'block',
+            time: params.type === 'created' ?
+                new Date(match.content || '').getTime() :
+                Date.now(),
+            ...(params.include_content && { content: match.content }),
+            page_title: match.page_title
+        }));
+        // 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`
+        };
+    }
+}

package/build/tools/operations/search/types.js

@@ -0,0 +1 @@
+export {};

package/build/tools/operations/search.js

@@ -0,0 +1,285 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler } from '../../search/index.js';
+export class SearchOperations {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    async searchBlockRefs(params) {
+        const handler = new BlockRefSearchHandler(this.graph, params);
+        return handler.execute();
+    }
+    async searchHierarchy(params) {
+        const handler = new HierarchySearchHandler(this.graph, params);
+        return handler.execute();
+    }
+    async searchByText(params) {
+        const handler = new TextSearchHandler(this.graph, params);
+        return handler.execute();
+    }
+    async searchByStatus(status, page_title_uid, include, exclude, case_sensitive = true) {
+        // 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}]]}}`;
+        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 with case sensitivity option
+        if (include) {
+            const includeTerms = include.split(',').map(term => term.trim());
+            matches = matches.filter(match => {
+                const matchContent = case_sensitive ? match.content : match.content.toLowerCase();
+                const matchTitle = match.page_title && (case_sensitive ? match.page_title : match.page_title.toLowerCase());
+                const terms = case_sensitive ? includeTerms : includeTerms.map(t => t.toLowerCase());
+                return terms.some(term => matchContent.includes(case_sensitive ? term : term.toLowerCase()) ||
+                    (matchTitle && matchTitle.includes(case_sensitive ? term : term.toLowerCase())));
+            });
+        }
+        if (exclude) {
+            const excludeTerms = exclude.split(',').map(term => term.trim());
+            matches = matches.filter(match => {
+                const matchContent = case_sensitive ? match.content : match.content.toLowerCase();
+                const matchTitle = match.page_title && (case_sensitive ? match.page_title : match.page_title.toLowerCase());
+                const terms = case_sensitive ? excludeTerms : excludeTerms.map(t => t.toLowerCase());
+                return !terms.some(term => matchContent.includes(case_sensitive ? term : term.toLowerCase()) ||
+                    (matchTitle && matchTitle.includes(case_sensitive ? term : term.toLowerCase())));
+            });
+        }
+        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, case_sensitive = true) {
+        // Ensure tags are properly formatted with #
+        const formatTag = (tag) => {
+            return tag.replace(/^#/, '').replace(/^\[\[/, '').replace(/\]\]$/, '');
+        };
+        // Extract the tag text, removing any formatting
+        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? 
+                             ${case_sensitive ? '?block-str' : '(clojure.string/lower-case ?block-str)'} 
+                             ${case_sensitive ? '?primary-tag' : '(clojure.string/lower-case ?primary-tag)'})]
+                           [(clojure.string/includes? 
+                             ${case_sensitive ? '?block-str' : '(clojure.string/lower-case ?block-str)'} 
+                             ${case_sensitive ? '?near-tag' : '(clojure.string/lower-case ?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? 
+                             ${case_sensitive ? '?block-str' : '(clojure.string/lower-case ?block-str)'} 
+                             ${case_sensitive ? '?primary-tag' : '(clojure.string/lower-case ?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? 
+                             ${case_sensitive ? '?block-str' : '(clojure.string/lower-case ?block-str)'} 
+                             ${case_sensitive ? '?primary-tag' : '(clojure.string/lower-case ?primary-tag)'})]
+                           [(clojure.string/includes? 
+                             ${case_sensitive ? '?block-str' : '(clojure.string/lower-case ?block-str)'} 
+                             ${case_sensitive ? '?near-tag' : '(clojure.string/lower-case ?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? 
+                             ${case_sensitive ? '?block-str' : '(clojure.string/lower-case ?block-str)'} 
+                             ${case_sensitive ? '?primary-tag' : '(clojure.string/lower-case ?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 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
+        }));
+        // Apply case sensitivity if content is included
+        if (params.include_content) {
+            const case_sensitive = params.case_sensitive ?? true; // Default to true to match Roam's behavior
+            if (!case_sensitive) {
+                matches.forEach(match => {
+                    if (match.content) {
+                        match.content = match.content.toLowerCase();
+                    }
+                    if (match.page_title) {
+                        match.page_title = match.page_title.toLowerCase();
+                    }
+                });
+            }
+        }
+        // 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`
+        };
+    }
+}

package/build/tools/operations/todos.js

@@ -0,0 +1,82 @@
+import { q, createBlock, createPage, batchActions } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { formatRoamDate } from '../../utils/helpers.js';
+export class TodoOperations {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    async addTodos(todos) {
+        if (!Array.isArray(todos) || todos.length === 0) {
+            throw new McpError(ErrorCode.InvalidRequest, 'todos must be a non-empty array');
+        }
+        // Get today's date
+        const today = new Date();
+        const dateStr = formatRoamDate(today);
+        // Try to find today's page
+        const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+        const findResults = await q(this.graph, findQuery, [dateStr]);
+        let targetPageUid;
+        if (findResults && findResults.length > 0) {
+            targetPageUid = findResults[0][0];
+        }
+        else {
+            // Create today's page if it doesn't exist
+            try {
+                await createPage(this.graph, {
+                    action: 'create-page',
+                    page: { title: dateStr }
+                });
+                // Get the new page's UID
+                const results = await q(this.graph, findQuery, [dateStr]);
+                if (!results || results.length === 0) {
+                    throw new Error('Could not find created today\'s page');
+                }
+                targetPageUid = results[0][0];
+            }
+            catch (error) {
+                throw new Error('Failed to create today\'s page');
+            }
+        }
+        // If more than 10 todos, use batch actions
+        const todo_tag = "{{TODO}}";
+        if (todos.length > 10) {
+            const actions = todos.map((todo, index) => ({
+                action: 'create-block',
+                location: {
+                    'parent-uid': targetPageUid,
+                    order: index
+                },
+                block: {
+                    string: `${todo_tag} ${todo}`
+                }
+            }));
+            const result = await batchActions(this.graph, {
+                action: 'batch-actions',
+                actions
+            });
+            if (!result) {
+                throw new Error('Failed to create todo blocks');
+            }
+        }
+        else {
+            // Create todos sequentially
+            for (const todo of todos) {
+                try {
+                    await createBlock(this.graph, {
+                        action: 'create-block',
+                        location: {
+                            "parent-uid": targetPageUid,
+                            "order": "last"
+                        },
+                        block: { string: `${todo_tag} ${todo}` }
+                    });
+                }
+                catch (error) {
+                    throw new Error('Failed to create todo block');
+                }
+            }
+        }
+        return { success: true };
+    }
+}

package/build/tools/schemas.js

@@ -73,8 +73,8 @@ export const toolSchemas = {
         },
     },
     roam_create_outline: {
-        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. Ideal for saving a conversation with an LLM response, research, or organizing thoughts.',
+        name: 'roam_create_outline',
+        description: 'Create a structured outline 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. Ideal for saving a conversation with an LLM response, research, or organizing thoughts.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -98,7 +98,9 @@ export const toolSchemas = {
                             },
                             level: {
                                 type: 'integer',
-                                description: 'Indentation level (1-5, where 1 is top level)'
+                                description: 'Indentation level (1-10, where 1 is top level)',
+                                minimum: 1,
+                                maximum: 10
                             }
                         },
                         required: ['text', 'level']
@@ -161,11 +163,6 @@ export const toolSchemas = {
                 near_tag: {
                     type: 'string',
                     description: 'Optional: Another tag to filter results by - will only return blocks where both tags appear',
-                },
-                case_sensitive: {
-                    type: 'boolean',
-                    description: 'Optional: Whether to perform case-sensitive matching (default: true, matching Roam\'s native behavior)',
-                    default: true
                 }
             },
             required: ['primary_tag']
@@ -193,11 +190,6 @@ export const toolSchemas = {
                 exclude: {
                     type: 'string',
                     description: 'Optional: Comma-separated list of terms to filter results by exclusion (matches content or page title)'
-                },
-                case_sensitive: {
-                    type: 'boolean',
-                    description: 'Optional: Whether to perform case-sensitive matching (default: true, matching Roam\'s native behavior)',
-                    default: true
                 }
             },
             required: ['status']
@@ -273,11 +265,6 @@ export const toolSchemas = {
                 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 case-sensitive search (default: true, matching Roam\'s native behavior)',
-                    default: true
                 }
             },
             required: ['text']
@@ -405,11 +392,6 @@ export const toolSchemas = {
                     type: 'boolean',
                     description: 'Whether to include the content of matching blocks/pages',
                     default: true,
-                },
-                case_sensitive: {
-                    type: 'boolean',
-                    description: 'Optional: Whether to perform case-sensitive matching (default: true, matching Roam\'s native behavior)',
-                    default: true
                 }
             },
             required: ['start_date', 'type', 'scope']
@@ -417,7 +399,7 @@ export const toolSchemas = {
     },
     roam_remember: {
         name: 'roam_remember',
-        description: 'Add a memory or piece of information to remember, stored on the daily page with #[[LLM/Memories]] tag and optional categories. Use roam_search_for_tag with "LLM/Memories" to find stored memories.\nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
+        description: 'Add a memory or piece of information to remember, stored on the daily page with #[[LLM/Memories]] tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -435,5 +417,14 @@ export const toolSchemas = {
             },
             required: ['memory']
         }
+    },
+    roam_recall: {
+        name: 'roam_recall',
+        description: 'Retrieve all stored memories by searching for blocks tagged with MEMORIES_TAG and content from the page with the same name. Returns a combined, deduplicated list of memories.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
     }
 };