roam-research-mcp 0.23.0 → 0.24.1

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

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class BlockRefSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -63,10 +64,15 @@ export class BlockRefSearchHandler extends BaseSearchHandler {
                 queryParams = [];
             }
         }
-        const results = await q(this.graph, queryStr, queryParams);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
         const searchDescription = block_uid
             ? `referencing block ((${block_uid}))`
             : 'containing block references';
-        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+        return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
     }
 }

package/build/search/hierarchy-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class HierarchySearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -85,13 +86,16 @@ export class HierarchySearchHandler extends BaseSearchHandler {
                 queryParams = [ancestorRule, child_uid];
             }
         }
-        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 rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references and format results to include depth information
+        const matches = await Promise.all(rawResults.map(async ([uid, content, pageTitle, depth]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return {
+                block_uid: uid,
+                content: resolvedContent,
+                depth: depth || 1,
+                ...(pageTitle && { page_title: pageTitle })
+            };
         }));
         const searchDescription = parent_uid
             ? `descendants of block ${parent_uid}`

package/build/search/status-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class StatusSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -37,7 +38,12 @@ export class StatusSearchHandler extends BaseSearchHandler {
                          [(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);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
+        return SearchUtils.formatSearchResults(resolvedResults, `with status ${status}`, !targetPageUid);
     }
 }

package/build/search/tag-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class TagSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -28,8 +29,13 @@ export class TagSearchHandler extends BaseSearchHandler {
                       [?b :block/page ?p]
                       [?p :node/title ?page-title]]`;
         const queryParams = [primary_tag];
-        const results = await q(this.graph, queryStr, queryParams);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
         const searchDescription = `referencing "${primary_tag}"`;
-        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+        return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
     }
 }

package/build/search/text-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class TextSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -24,8 +25,13 @@ export class TextSearchHandler extends BaseSearchHandler {
                       [?b :block/page ?p]
                       [?p :node/title ?page-title]]`;
         const queryParams = [text];
-        const results = await q(this.graph, queryStr, queryParams);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
         const searchDescription = `containing "${text}"`;
-        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+        return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
     }
 }

package/build/tools/operations/outline.js

@@ -54,20 +54,14 @@ export class OutlineOperations {
                 }
                 // If still not found and this is the first retry, try to create the page
                 if (retry === 0) {
-                    try {
-                        await createPage(this.graph, {
-                            action: 'create-page',
-                            page: { title: titleOrUid }
-                        });
-                        // Wait a bit and continue to next retry to check if page was created
-                        await new Promise(resolve => setTimeout(resolve, delayMs));
-                        continue;
-                    }
-                    catch (error) {
-                        console.error('Error creating page:', error);
-                        // Continue to next retry
-                        continue;
-                    }
+                    const success = await createPage(this.graph, {
+                        action: 'create-page',
+                        page: { title: titleOrUid }
+                    });
+                    // Even if createPage returns false, the page might still have been created
+                    // Wait a bit and continue to next retry
+                    await new Promise(resolve => setTimeout(resolve, delayMs));
+                    continue;
                 }
                 if (retry < maxRetries - 1) {
                     await new Promise(resolve => setTimeout(resolve, delayMs));
@@ -78,23 +72,21 @@ export class OutlineOperations {
         // Get or create the target page
         const targetPageUid = await findOrCreatePage(page_title_uid || formatRoamDate(new Date()));
         // Helper function to find block with improved relationship checks
-        const findBlockWithRetry = async (pageUid, blockString, maxRetries = 5, initialDelay = 1000, case_sensitive = false) => {
+        const findBlockWithRetry = async (pageUid, blockString, maxRetries = 5, initialDelay = 1000) => {
             // Try multiple query strategies
             const queries = [
                 // Strategy 1: Direct page and string match
                 `[:find ?b-uid ?order
           :where [?p :block/uid "${pageUid}"]
                  [?b :block/page ?p]
-                 [?b :block/string ?block-str]
-                 [(${case_sensitive ? '=' : 'clojure.string/equals-ignore-case'} ?block-str "${blockString}")]
+                 [?b :block/string "${blockString}"]
                  [?b :block/order ?order]
                  [?b :block/uid ?b-uid]]`,
                 // Strategy 2: Parent-child relationship
                 `[:find ?b-uid ?order
           :where [?p :block/uid "${pageUid}"]
                  [?b :block/parents ?p]
-                 [?b :block/string ?block-str]
-                 [(${case_sensitive ? '=' : 'clojure.string/equals-ignore-case'} ?block-str "${blockString}")]
+                 [?b :block/string "${blockString}"]
                  [?b :block/order ?order]
                  [?b :block/uid ?b-uid]]`,
                 // Strategy 3: Broader page relationship
@@ -102,8 +94,7 @@ export class OutlineOperations {
           :where [?p :block/uid "${pageUid}"]
                  [?b :block/page ?page]
                  [?p :block/page ?page]
-                 [?b :block/string ?block-str]
-                 [(${case_sensitive ? '=' : 'clojure.string/equals-ignore-case'} ?block-str "${blockString}")]
+                 [?b :block/string "${blockString}"]
                  [?b :block/order ?order]
                  [?b :block/uid ?b-uid]]`
             ];
@@ -125,7 +116,7 @@ export class OutlineOperations {
             throw new McpError(ErrorCode.InternalError, `Failed to find block "${blockString}" under page "${pageUid}" after trying multiple strategies`);
         };
         // Helper function to create and verify block with improved error handling
-        const createAndVerifyBlock = async (content, parentUid, maxRetries = 5, initialDelay = 1000, isRetry = false, case_sensitive = false) => {
+        const createAndVerifyBlock = async (content, parentUid, maxRetries = 5, initialDelay = 1000, isRetry = false) => {
             try {
                 // Initial delay before any operations
                 if (!isRetry) {
@@ -133,25 +124,25 @@ export class OutlineOperations {
                 }
                 for (let retry = 0; retry < maxRetries; retry++) {
                     console.log(`Attempt ${retry + 1}/${maxRetries} to create block "${content}" under "${parentUid}"`);
+                    // Create block
+                    const success = await createBlock(this.graph, {
+                        action: 'create-block',
+                        location: {
+                            'parent-uid': parentUid,
+                            order: 'last'
+                        },
+                        block: { string: content }
+                    });
+                    // Wait with exponential backoff
+                    const delay = initialDelay * Math.pow(2, retry);
+                    await new Promise(resolve => setTimeout(resolve, delay));
                     try {
-                        // Create block
-                        await createBlock(this.graph, {
-                            action: 'create-block',
-                            location: {
-                                'parent-uid': parentUid,
-                                order: 'first'
-                            },
-                            block: { string: content }
-                        });
-                        // Wait with exponential backoff
-                        const delay = initialDelay * Math.pow(2, retry);
-                        await new Promise(resolve => setTimeout(resolve, delay));
                         // Try to find the block using our improved findBlockWithRetry
-                        return await findBlockWithRetry(parentUid, content, maxRetries, initialDelay, case_sensitive);
+                        return await findBlockWithRetry(parentUid, content);
                     }
                     catch (error) {
                         const errorMessage = error instanceof Error ? error.message : String(error);
-                        console.log(`Failed to create/find block on attempt ${retry + 1}: ${errorMessage}`);
+                        console.log(`Failed to find block on attempt ${retry + 1}: ${errorMessage}`);
                         if (retry === maxRetries - 1)
                             throw error;
                     }
@@ -165,7 +156,7 @@ export class OutlineOperations {
                 // Otherwise, try one more time with a clean slate
                 console.log(`Retrying block creation for "${content}" with fresh attempt`);
                 await new Promise(resolve => setTimeout(resolve, initialDelay * 2));
-                return createAndVerifyBlock(content, parentUid, maxRetries, initialDelay, true, case_sensitive);
+                return createAndVerifyBlock(content, parentUid, maxRetries, initialDelay, true);
             }
         };
         // Get or create the parent block

package/build/tools/operations/pages.js

@@ -87,7 +87,7 @@ export class PageOperations {
                     // Use import_nested_markdown functionality
                     const convertedContent = convertToRoamMarkdown(content);
                     const nodes = parseMarkdown(convertedContent);
-                    const actions = convertToRoamActions(nodes, pageUid, 'last');
+                    const actions = convertToRoamActions(nodes, pageUid, 'first');
                     const result = await batchActions(this.graph, {
                         action: 'batch-actions',
                         actions

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

@@ -1,4 +1,4 @@
-import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler, DatomicSearchHandler } from '../../../search/index.js';
+import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler, DatomicSearchHandler, StatusSearchHandler } from '../../../search/index.js';
 // Base class for all search handlers
 export class BaseSearchHandler {
     graph;
@@ -54,6 +54,18 @@ export class TextSearchHandlerImpl extends BaseSearchHandler {
         return handler.execute();
     }
 }
+// Status search handler
+export class StatusSearchHandlerImpl extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        const handler = new StatusSearchHandler(this.graph, this.params);
+        return handler.execute();
+    }
+}
 // Datomic query handler
 export class DatomicSearchHandlerImpl extends BaseSearchHandler {
     params;

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

@@ -1,12 +1,12 @@
-import { TagSearchHandlerImpl, BlockRefSearchHandlerImpl, HierarchySearchHandlerImpl, TextSearchHandlerImpl } from './handlers.js';
+import { TagSearchHandlerImpl, BlockRefSearchHandlerImpl, HierarchySearchHandlerImpl, TextSearchHandlerImpl, StatusSearchHandlerImpl } 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}]]}}`,
+        const handler = new StatusSearchHandlerImpl(this.graph, {
+            status,
             page_title_uid,
         });
         const result = await handler.execute();
@@ -14,7 +14,7 @@ export class SearchOperations {
         let matches = result.matches;
         if (include) {
             const includeTerms = include.split(',').map(term => term.trim());
-            matches = matches.filter(match => {
+            matches = matches.filter((match) => {
                 const matchContent = match.content;
                 const matchTitle = match.page_title;
                 const terms = includeTerms;
@@ -24,7 +24,7 @@ export class SearchOperations {
         }
         if (exclude) {
             const excludeTerms = exclude.split(',').map(term => term.trim());
-            matches = matches.filter(match => {
+            matches = matches.filter((match) => {
                 const matchContent = match.content;
                 const matchTitle = match.page_title;
                 const terms = excludeTerms;

package/build/tools/schemas.js

@@ -34,7 +34,7 @@ export const toolSchemas = {
     },
     roam_create_page: {
         name: 'roam_create_page',
-        description: 'Create a new standalone page in Roam from markdown with given title. Best for hierarchical content, reference materials, markdown tables, and topics that deserve their own namespace. Optional initial content will be properly nested as blocks.',
+        description: 'Create a new standalone page in Roam with optional content using markdown-style formatting. The nesting structure is inferred from markdown indentation (spaces). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -44,7 +44,7 @@ export const toolSchemas = {
                 },
                 content: {
                     type: 'string',
-                    description: 'Initial content for the page (optional)',
+                    description: 'Initial content for the page (optional). Each line becomes a separate block. Indentation (using spaces or tabs) determines the nesting level of each block.',
                 },
             },
             required: ['title'],
@@ -74,7 +74,7 @@ export const toolSchemas = {
     },
     roam_create_outline: {
         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.',
+        description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. Best for:\n- Adding supplementary structured content to existing pages\n- Creating temporary or working outlines (meeting notes, brainstorms)\n- Organizing thoughts or research under a specific topic\n- Breaking down subtopics or components of a larger concept',
         inputSchema: {
             type: 'object',
             properties: {
@@ -88,7 +88,7 @@ export const toolSchemas = {
                 },
                 outline: {
                     type: 'array',
-                    description: 'Array of outline items with block text and level',
+                    description: 'Array of outline items with block text and explicit nesting level',
                     items: {
                         type: 'object',
                         properties: {
@@ -429,7 +429,7 @@ export const toolSchemas = {
     },
     roam_datomic_query: {
         name: 'roam_datomic_query',
-        description: 'Execute a custom Datomic query on the Roam graph. This provides direct access to Roam\'s query engine for advanced data retrieval. Note: The Roam graph is case-sensitive.\nA list of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
+        description: 'Execute a custom Datomic query on the Roam graph beyond the available search tools. This provides direct access to Roam\'s query engine for advanced data retrieval. Note: Roam graph is case-sensitive.\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

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