roam-research-mcp 0.19.0 → 0.22.0

package/README.md

@@ -28,7 +28,7 @@ npm run build
 
 ## Features
 
-The server provides twelve powerful tools for interacting with Roam Research:
+The server provides fourteen 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
@@ -42,13 +42,16 @@ The server provides twelve powerful tools for interacting with Roam Research:
 10. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page
 11. `roam_update_block`: Update block content with direct text or pattern-based transformations
 12. `roam_search_by_date`: Search for blocks and pages based on creation or modification dates
+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:
@@ -60,28 +63,14 @@ The server provides twelve powerful tools for interacting with Roam Research:
    ```
    ROAM_API_TOKEN=your-api-token
    ROAM_GRAPH_NAME=your-graph-name
+   MEMORIES_TAG='#[[LLM/Memories]]'
+   PROFILE_PAGE='LLM/Profile' (not yet implemented)
    ```
 
    Option 2: Using MCP settings (Alternative method)
    Add the configuration to your MCP settings file:
 
    - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
-
-   ```json
-   {
-     "mcpServers": {
-       "roam-research": {
-         "command": "node",
-         "args": ["/path/to/roam-research/build/index.js"],
-         "env": {
-           "ROAM_API_TOKEN": "your-api-token",
-           "ROAM_GRAPH_NAME": "your-graph-name"
-         }
-       }
-     }
-   }
-   ```
-
    - For Claude desktop app (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
    ```json
@@ -92,7 +81,9 @@ The server provides twelve powerful tools for interacting with Roam Research:
          "args": ["/path/to/roam-research/build/index.js"],
          "env": {
            "ROAM_API_TOKEN": "your-api-token",
-           "ROAM_GRAPH_NAME": "your-graph-name"
+           "ROAM_GRAPH_NAME": "your-graph-name",
+           "MEMORIES_TAG": "#[[LLM/Memories]]",
+           "PROFILE_PAGE": "LLM/Profile"
          }
        }
      }
@@ -421,6 +412,86 @@ Returns:
 }
 ```
 
+### Search For Tags
+
+Search for blocks containing specific tags with optional filtering by nearby tags:
+
+```typescript
+use_mcp_tool roam-research roam_search_for_tag {
+  "primary_tag": "Project/Tasks",
+  "page_title_uid": "optional-page-title-or-uid",
+  "near_tag": "optional-secondary-tag",
+  "case_sensitive": true
+}
+```
+
+Features:
+
+- Search for blocks containing specific tags
+- Optional filtering by presence of another tag
+- Page-scoped or graph-wide search
+- Case-sensitive or case-insensitive search
+- Returns block content with page context
+- Efficient tag matching using Datalog queries
+
+Parameters:
+
+- `primary_tag`: The main tag to search for (required)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+- `near_tag`: Another tag to filter results by (optional)
+- `case_sensitive`: Whether to perform case-sensitive search (optional, default: true to match Roam's native behavior)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "matching-block-uid",
+      "content": "Block content containing #[[primary_tag]]",
+      "page_title": "Page containing block"
+    }
+  ],
+  "message": "Found N block(s) referencing \"primary_tag\""
+}
+```
+
+### Remember Information
+
+Store memories or important information with automatic tagging and categorization:
+
+```typescript
+use_mcp_tool roam-research roam_remember {
+  "memory": "Important information to remember",
+  "categories": ["Work", "Project/Alpha"]
+}
+```
+
+Features:
+
+- Store information with #[[LLM/Memories]] tag
+- Add optional category tags for organization
+- Automatically adds to today's daily page
+- Supports multiple categories per memory
+- Easy retrieval using roam_search_for_tag
+- Maintains chronological order of memories
+
+Parameters:
+
+- `memory`: The information to remember (required)
+- `categories`: Optional array of categories to tag the memory with
+
+Returns:
+
+```json
+{
+  "success": true,
+  "block_uid": "created-block-uid",
+  "content": "Memory content with tags"
+}
+```
+
 ### Search By Date
 
 Search for blocks and pages based on creation or modification dates:

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;
@@ -22,6 +21,8 @@ export class RoamServer {
         }, {
             capabilities: {
                 tools: {
+                    roam_remember: {},
+                    roam_recall: {},
                     roam_add_todo: {},
                     roam_fetch_page_by_title: {},
                     roam_create_page: {},
@@ -57,6 +58,13 @@ export class RoamServer {
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
                 switch (request.params.name) {
+                    case 'roam_remember': {
+                        const { memory, categories } = request.params.arguments;
+                        const result = await this.toolHandlers.remember(memory, categories);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     case 'roam_fetch_page_by_title': {
                         const { title } = request.params.arguments;
                         const content = await this.toolHandlers.fetchPageByTitle(title);
@@ -100,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) }],
                         };
@@ -116,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) }],
                         };
@@ -138,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) }],
                         };
@@ -167,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
+        };
+    }
+}