roam-research-mcp 0.20.0 → 0.22.0

package/README.md

@@ -44,13 +44,14 @@ The server provides fourteen powerful tools for interacting with Roam Research:
 12. `roam_search_by_date`: Search for blocks and pages based on creation or modification dates
 13. `roam_search_for_tag`: Search for blocks containing specific tags with optional filtering by nearby tags
 14. `roam_remember`: Store and categorize memories or information with automatic tagging
+15. `roam_recall`: Recall memories of blocks marked with tag MEMORIES_TAG (see below) or blocks on page title of the same name.
 
 ## Setup
 
-1. Create a Roam Research API token:
+1. Create a [Roam Research API token](https://x.com/RoamResearch/status/1789358175474327881):
 
    - Go to your graph settings
-   - Navigate to the "API tokens" section
+   - Navigate to the "API tokens" section (Settings > "Graph" tab > "API Tokens" section and click on the "+ New API Token" button)
    - Create a new token
 
 2. Configure the environment variables:

package/build/search/text-search.js

@@ -8,7 +8,7 @@ export class TextSearchHandler extends BaseSearchHandler {
         this.params = params;
     }
     async execute() {
-        const { text, page_title_uid, case_sensitive = false } = this.params;
+        const { text, page_title_uid } = this.params;
         // Get target page UID if provided for scoped search
         let targetPageUid;
         if (page_title_uid) {
@@ -19,14 +19,13 @@ export class TextSearchHandler extends BaseSearchHandler {
                       :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)'})]
+                      [(clojure.string/includes? ?block-str ?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)' : ''}`;
+        const searchDescription = `containing "${text}"`;
         return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
     }
 }

package/build/server/roam-server.js

@@ -5,7 +5,6 @@ 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/tool-handlers.js';
-import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler } from '../search/index.js';
 export class RoamServer {
     server;
     toolHandlers;
@@ -23,6 +22,7 @@ export class RoamServer {
             capabilities: {
                 tools: {
                     roam_remember: {},
+                    roam_recall: {},
                     roam_add_todo: {},
                     roam_fetch_page_by_title: {},
                     roam_create_page: {},
@@ -108,9 +108,8 @@ export class RoamServer {
                         };
                     }
                     case 'roam_search_for_tag': {
-                        const params = request.params.arguments;
-                        const handler = new TagSearchHandler(this.graph, params);
-                        const result = await handler.execute();
+                        const { primary_tag, page_title_uid, near_tag } = request.params.arguments;
+                        const result = await this.toolHandlers.searchForTag(primary_tag, page_title_uid, near_tag);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
@@ -124,16 +123,14 @@ export class RoamServer {
                     }
                     case 'roam_search_block_refs': {
                         const params = request.params.arguments;
-                        const handler = new BlockRefSearchHandler(this.graph, params);
-                        const result = await handler.execute();
+                        const result = await this.toolHandlers.searchBlockRefs(params);
                         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();
+                        const result = await this.toolHandlers.searchHierarchy(params);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
@@ -146,8 +143,7 @@ export class RoamServer {
                     }
                     case 'roam_search_by_text': {
                         const params = request.params.arguments;
-                        const handler = new TextSearchHandler(this.graph, params);
-                        const result = await handler.execute();
+                        const result = await this.toolHandlers.searchByText(params);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
@@ -175,6 +171,12 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
+                    case 'roam_recall': {
+                        const result = await this.toolHandlers.recall();
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     case 'roam_update_blocks': {
                         const { updates } = request.params.arguments;
                         const result = await this.toolHandlers.updateBlocks(updates);

package/build/tools/helpers/refs.js

@@ -0,0 +1,47 @@
+import { q } from '@roam-research/roam-api-sdk';
+/**
+ * Collects all referenced block UIDs from text
+ */
+export const collectRefs = (text, depth = 0, refs = new Set()) => {
+    if (depth >= 4)
+        return refs; // Max recursion depth
+    const refRegex = /\(\(([a-zA-Z0-9_-]+)\)\)/g;
+    let match;
+    while ((match = refRegex.exec(text)) !== null) {
+        const [_, uid] = match;
+        refs.add(uid);
+    }
+    return refs;
+};
+/**
+ * Resolves block references in text by replacing them with their content
+ */
+export const resolveRefs = async (graph, text, depth = 0) => {
+    if (depth >= 4)
+        return text; // Max recursion depth
+    const refs = collectRefs(text, depth);
+    if (refs.size === 0)
+        return text;
+    // Get referenced block contents
+    const refQuery = `[:find ?uid ?string
+                    :in $ [?uid ...]
+                    :where [?b :block/uid ?uid]
+                          [?b :block/string ?string]]`;
+    const refResults = await q(graph, refQuery, [Array.from(refs)]);
+    // Create lookup map of uid -> string
+    const refMap = new Map();
+    refResults.forEach(([uid, string]) => {
+        refMap.set(uid, string);
+    });
+    // Replace references with their content
+    let resolvedText = text;
+    for (const uid of refs) {
+        const refContent = refMap.get(uid);
+        if (refContent) {
+            // Recursively resolve nested references
+            const resolvedContent = await resolveRefs(graph, refContent, depth + 1);
+            resolvedText = resolvedText.replace(new RegExp(`\\(\\(${uid}\\)\\)`, 'g'), resolvedContent);
+        }
+    }
+    return resolvedText;
+};

package/build/tools/helpers/text.js

@@ -0,0 +1,6 @@
+/**
+ * Capitalizes each word in a string
+ */
+export const capitalizeWords = (str) => {
+    return str.split(' ').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
+};

package/build/tools/operations/blocks.js

@@ -0,0 +1,269 @@
+import { q, createBlock as createRoamBlock, updateBlock as updateRoamBlock, batchActions, createPage } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { formatRoamDate } from '../../utils/helpers.js';
+import { parseMarkdown, convertToRoamActions, convertToRoamMarkdown } from '../../markdown-utils.js';
+export class BlockOperations {
+    graph;
+    constructor(graph) {
+        this.graph = graph;
+    }
+    async createBlock(content, page_uid, title) {
+        // If page_uid provided, use it directly
+        let targetPageUid = page_uid;
+        // If no page_uid but title provided, search for page by title
+        if (!targetPageUid && title) {
+            const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+            const findResults = await q(this.graph, findQuery, [title]);
+            if (findResults && findResults.length > 0) {
+                targetPageUid = findResults[0][0];
+            }
+            else {
+                // Create page with provided title if it doesn't exist
+                try {
+                    await createPage(this.graph, {
+                        action: 'create-page',
+                        page: { title }
+                    });
+                    // Get the new page's UID
+                    const results = await q(this.graph, findQuery, [title]);
+                    if (!results || results.length === 0) {
+                        throw new Error('Could not find created page');
+                    }
+                    targetPageUid = results[0][0];
+                }
+                catch (error) {
+                    throw new McpError(ErrorCode.InternalError, `Failed to create page: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        // If neither page_uid nor title provided, use today's date page
+        if (!targetPageUid) {
+            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]);
+            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 McpError(ErrorCode.InternalError, `Failed to create today's page: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        try {
+            // If the content has multiple lines or is a table, use nested import
+            if (content.includes('\n')) {
+                // Parse and import the nested content
+                const convertedContent = convertToRoamMarkdown(content);
+                const nodes = parseMarkdown(convertedContent);
+                const actions = convertToRoamActions(nodes, targetPageUid, 'last');
+                // Execute batch actions to create the nested structure
+                const result = await batchActions(this.graph, {
+                    action: 'batch-actions',
+                    actions
+                });
+                if (!result) {
+                    throw new Error('Failed to create nested blocks');
+                }
+                const blockUid = result.created_uids?.[0];
+                return {
+                    success: true,
+                    block_uid: blockUid,
+                    parent_uid: targetPageUid
+                };
+            }
+            else {
+                // For non-table content, create a simple block
+                await createRoamBlock(this.graph, {
+                    action: 'create-block',
+                    location: {
+                        "parent-uid": targetPageUid,
+                        "order": "last"
+                    },
+                    block: { string: content }
+                });
+                // Get the block's UID
+                const findBlockQuery = `[:find ?uid
+                               :in $ ?parent ?string
+                               :where [?b :block/uid ?uid]
+                                     [?b :block/string ?string]
+                                     [?b :block/parents ?p]
+                                     [?p :block/uid ?parent]]`;
+                const blockResults = await q(this.graph, findBlockQuery, [targetPageUid, content]);
+                if (!blockResults || blockResults.length === 0) {
+                    throw new Error('Could not find created block');
+                }
+                const blockUid = blockResults[0][0];
+                return {
+                    success: true,
+                    block_uid: blockUid,
+                    parent_uid: targetPageUid
+                };
+            }
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to create block: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    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 {
+            await updateRoamBlock(this.graph, {
+                action: 'update-block',
+                block: {
+                    uid: block_uid,
+                    string: newContent
+                }
+            });
+            return {
+                success: true,
+                content: newContent
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to update block: ${error.message}`);
+        }
+    }
+    async updateBlocks(updates) {
+        if (!Array.isArray(updates) || updates.length === 0) {
+            throw new McpError(ErrorCode.InvalidRequest, 'updates must be a non-empty array');
+        }
+        // Validate each update has required fields
+        updates.forEach((update, index) => {
+            if (!update.block_uid) {
+                throw new McpError(ErrorCode.InvalidRequest, `Update at index ${index} missing block_uid`);
+            }
+            if (!update.content && !update.transform) {
+                throw new McpError(ErrorCode.InvalidRequest, `Update at index ${index} must have either content or transform`);
+            }
+        });
+        // Get current content for all blocks
+        const blockUids = updates.map(u => u.block_uid);
+        const blockQuery = `[:find ?uid ?string
+                        :in $ [?uid ...]
+                        :where [?b :block/uid ?uid]
+                               [?b :block/string ?string]]`;
+        const blockResults = await q(this.graph, blockQuery, [blockUids]);
+        // Create map of uid -> current content
+        const contentMap = new Map();
+        blockResults.forEach(([uid, string]) => {
+            contentMap.set(uid, string);
+        });
+        // Prepare batch actions
+        const actions = [];
+        const results = [];
+        for (const update of updates) {
+            try {
+                const currentContent = contentMap.get(update.block_uid);
+                if (!currentContent) {
+                    results.push({
+                        block_uid: update.block_uid,
+                        content: '',
+                        success: false,
+                        error: `Block with UID "${update.block_uid}" not found`
+                    });
+                    continue;
+                }
+                // Determine new content
+                let newContent;
+                if (update.content) {
+                    newContent = update.content;
+                }
+                else if (update.transform) {
+                    const regex = new RegExp(update.transform.find, update.transform.global ? 'g' : '');
+                    newContent = currentContent.replace(regex, update.transform.replace);
+                }
+                else {
+                    // This shouldn't happen due to earlier validation
+                    throw new Error('Invalid update configuration');
+                }
+                // Add to batch actions
+                actions.push({
+                    action: 'update-block',
+                    block: {
+                        uid: update.block_uid,
+                        string: newContent
+                    }
+                });
+                results.push({
+                    block_uid: update.block_uid,
+                    content: newContent,
+                    success: true
+                });
+            }
+            catch (error) {
+                results.push({
+                    block_uid: update.block_uid,
+                    content: contentMap.get(update.block_uid) || '',
+                    success: false,
+                    error: error.message
+                });
+            }
+        }
+        // Execute batch update if we have any valid actions
+        if (actions.length > 0) {
+            try {
+                const batchResult = await batchActions(this.graph, {
+                    action: 'batch-actions',
+                    actions
+                });
+                if (!batchResult) {
+                    throw new Error('Batch update failed');
+                }
+            }
+            catch (error) {
+                // Mark all previously successful results as failed
+                results.forEach(result => {
+                    if (result.success) {
+                        result.success = false;
+                        result.error = `Batch update failed: ${error.message}`;
+                    }
+                });
+            }
+        }
+        return {
+            success: results.every(r => r.success),
+            results
+        };
+    }
+}

package/build/tools/operations/memory.js

@@ -0,0 +1,102 @@
+import { q, createBlock, createPage } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { formatRoamDate } from '../../utils/helpers.js';
+import { resolveRefs } from '../helpers/refs.js';
+import { SearchOperations } from './search/index.js';
+export class MemoryOperations {
+    graph;
+    searchOps;
+    constructor(graph) {
+        this.graph = graph;
+        this.searchOps = new SearchOperations(graph);
+    }
+    async remember(memory, categories) {
+        // 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 pageUid;
+        if (findResults && findResults.length > 0) {
+            pageUid = 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 McpError(ErrorCode.InternalError, 'Could not find created today\'s page');
+                }
+                pageUid = results[0][0];
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InternalError, 'Failed to create today\'s page');
+            }
+        }
+        // Get memories tag from environment
+        const memoriesTag = process.env.MEMORIES_TAG;
+        if (!memoriesTag) {
+            throw new McpError(ErrorCode.InternalError, 'MEMORIES_TAG environment variable not set');
+        }
+        // Format categories as Roam tags if provided
+        const categoryTags = categories?.map(cat => {
+            // Handle multi-word categories
+            return cat.includes(' ') ? `#[[${cat}]]` : `#${cat}`;
+        }).join(' ') || '';
+        // Create block with memory, memories tag, and optional categories
+        const blockContent = `${memoriesTag} ${memory} ${categoryTags}`.trim();
+        try {
+            await createBlock(this.graph, {
+                action: 'create-block',
+                location: {
+                    "parent-uid": pageUid,
+                    "order": "last"
+                },
+                block: { string: blockContent }
+            });
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, 'Failed to create memory block');
+        }
+        return { success: true };
+    }
+    async recall() {
+        // Get memories tag from environment
+        const memoriesTag = process.env.MEMORIES_TAG;
+        if (!memoriesTag) {
+            throw new McpError(ErrorCode.InternalError, 'MEMORIES_TAG environment variable not set');
+        }
+        // Extract the tag text, removing any formatting
+        const tagText = memoriesTag
+            .replace(/^#/, '') // Remove leading #
+            .replace(/^\[\[/, '').replace(/\]\]$/, ''); // Remove [[ and ]]
+        // Get results from tag search
+        const tagResults = await this.searchOps.searchForTag(tagText);
+        // Get blocks from the memories page
+        const pageQuery = `[:find ?string
+                       :in $ ?title
+                       :where [?p :node/title ?title]
+                              [?b :block/page ?p]
+                              [?b :block/string ?string]]`;
+        const pageResults = await q(this.graph, pageQuery, [tagText]);
+        // Combine both sets of results and remove the memories tag
+        const allMemories = [
+            ...tagResults.matches.map((match) => match.content),
+            ...pageResults.map(([content]) => content)
+        ].map(content => content.replace(`${memoriesTag} `, ''));
+        // Resolve any block references in the combined memories
+        const resolvedMemories = await Promise.all(allMemories.map(async (content) => resolveRefs(this.graph, content)));
+        // Remove duplicates
+        const uniqueMemories = [...new Set(resolvedMemories)];
+        return {
+            success: true,
+            memories: uniqueMemories
+        };
+    }
+}