roam-research-mcp 0.23.1 → 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/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 beyond the available search tools. 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.1",
+  "version": "0.24.1",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {