roam-research-mcp 0.32.4 → 0.36.0

package/README.md

@@ -121,7 +121,7 @@ The server provides powerful tools for interacting with Roam Research:
 10. `roam_search_by_text`: Search for blocks containing specific text.
 11. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
 12. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
-13. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.
+13. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby or exclude blocks with a specific tag.
 14. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
 15. `roam_recall`: Retrieve all stored memories.
 16. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools.
@@ -129,7 +129,7 @@ The server provides powerful tools for interacting with Roam Research:
 18. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
 
 **Deprecated Tools**:
-The following tools have been deprecated as of `v.0.30.0` in favor of the more powerful and flexible `roam_process_batch_actions`:
+The following tools have been deprecated as of `v1.36.0` in favor of the more powerful and flexible `roam_process_batch_actions`:
 
 - `roam_create_block`: Use `roam_process_batch_actions` with the `create-block` action.
 - `roam_update_block`: Use `roam_process_batch_actions` with the `update-block` action.
@@ -176,6 +176,20 @@ Please note that while the `roam_process_batch_actions` tool can set block headi
 
 ---
 
+## Propose Improvements
+
+### Pagination for Search Tools
+
+The `roam_search_for_tag` and `roam_search_by_text` tools now support `limit` and `offset` parameters, enabling basic pagination. To achieve full, robust pagination (e.g., retrieving "page 2" of results), the client consuming these tools would need to:
+
+1.  Make an initial call with `limit` and `offset=0` to get the first set of results and the `total_count`.
+2.  Calculate the total number of pages based on `total_count` and the desired `limit`.
+3.  Make subsequent calls, incrementing the `offset` by `limit` for each "page" of results.
+
+Example: To get the second page of 10 results, the call would be `roam_search_by_text(text: "your query", limit: 10, offset: 10)`.
+
+---
+
 ## Example Prompts
 
 Here are some examples of how to creatively use the Roam tool in an LLM to interact with your Roam graph, particularly leveraging `roam_process_batch_actions` for complex operations.
@@ -351,3 +365,9 @@ This will:
 ## License
 
 MIT License
+
+---
+
+## About the Author
+
+This project is maintained by [Ian Shen](https://github.com/2b3pro).

package/build/Roam_Markdown_Cheatsheet.md

@@ -15,6 +15,7 @@
 - {{[[TODO]]}} todo text
 - {{[[DONE]]}} todo text
 - LaTeX: `$$E=mc^2$$` or `$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$`
+- Bullet points use dashes not asterisks.
 
 ## Roam-specific Markdown:
 
@@ -112,12 +113,70 @@ The provided markdown structure represents a Roam Research Kanban board. It star
 This markdown structure allows embedding custom HTML or other content using Hiccup syntax. The `:hiccup` keyword is followed by a Clojure-like vector defining the HTML elements and their attributes in one block. This provides a powerful way to inject dynamic or custom components into your Roam graph. Example: `:hiccup [:iframe {:width "600" :height "400" :src "https://www.example.com"}]`
 
 ## Specific notes and preferences concerning my Roam Research graph
-### What To Tag
+### When creating new pages
 
-NONE
+- After creating a new page, ensure you add a new block on the daily page that references it if one doesn't already exist: `Created page: [[…]]`
 
-### Don't Include…
+### What To Tag
 
-NONE
+- Always think in terms of Future Me: How will I find this gem of information in this block in the future? What about this core idea might I be looking for? Aim for high relevance and helpfulness.
+- My notes in Roam are interconnected via wrapped terms/expressions [[…]] and hashtags (#…). The general salience guidelines are as follows:
+
+  - What greater domain would this core idea be best categorization?
+  - If block is parent of children blocks, can a word/phrase in the parent be wrapped in brackets.
+    - If not, could a hashtag be appended to the block? (This is like a "please see more"-on-this-subject categorization).
+  - Wrap any proper names—no titles—(Dr. [[Werner Erhard]]), organizations, abbreviations e.g. `[NASA]([[National Aeronautics and Space Administration (NASA)]])`
+  - Any synonyms or multi-worded phrases of already established categories/pages, e.g. `[frameworks for making quality decisions]([[decision-making frameworks]])`
+
+#### Advanced tagging methodology combining [[zettelkasten]] principles with serendipity engineering for maximum intellectual discovery potential. #[[knowledge management]] #[[tagging methodology]]
+
+- # Core Philosophy
+  - Tag for **intellectual collision** and **future conversation**, not just categorization. Every tag should maximize the potential for unexpected discoveries and cross-domain insights.
+  - Traditional academic categorization creates silos; serendipity-engineered tagging creates **conceptual magnets** that attract surprising connections.
+- ## Zettelkasten-Informed Principles
+  - **Atomic Thought Units**: Each tagged concept should function as a standalone intellectual object capable of connecting to ANY other domain
+  - **Conversation-Driven Linking**: Tag by the intellectual dialogues and debates a concept could inform, not just its subject matter
+  - **Temporal Intellectual Journey**: Tag for different phases of understanding - beginner discoveries, expert refinements, teaching moments
+  - **Intellectual Genealogy**: Create concept lineages that trace how ideas evolve and connect across domains
+- ## Serendipity Engineering Techniques
+  - **Conceptual Collision Matrix**: Force unlikely intellectual meetings by tagging across disparate domains
+    - Example: #[[parenting techniques]] + [[cognitive engineering]] = developing children's meta-cognitive awareness
+    - Example: #[[cooking methods]] + [[cultural rotation]] = how different cultures balance flavors → balancing competing AI instructions
+  - **Anti-Obvious Tagging**: Deliberately tag against natural categorization to maximize surprise
+    - Tag by **structural similarities** rather than surface content: #[[has feedback loops]], #[[requires calibration]], #[[exhibits emergence]]
+    - Connect concepts through **metaphorical bridges**: meditation techniques + bias detection (both about noticing the unnoticed)
+  - **Question Cascade Strategy**: Tag by what questions a concept could answer across unexpected domains
+    - Instead of "this is about X," ask "what problems could this solve that I haven't thought of yet?"
+    - Examples: #[[how do experts prevent tunnel vision?]], #[[what creates cognitive flexibility?]], #[[how do systems self-correct?]]
+  - **Future Collision Potential**: Tag with temporal discovery triggers
+    - [[will be relevant in 5 years]], #[[connects to unborn projects]], #[[solves problems I don't know I have yet]]
+- ## Practical Implementation
+  - **The Serendipity Test**: Before tagging, ask "Could this concept surprise me by connecting to something completely unrelated?"
+  - **Cross-Domain Bridge Tags**: Use structural rather than content-based categorization
+    - [[flow dynamics]] - connects fluid mechanics, music, conversation, AI prompt sequences
+    - [[calibration processes]] - bridges instrument tuning, relationships, AI parameters, personal habits
+    - [[perspective switching]] - connects photography, negotiation, cultural analysis, prompt engineering
+  - **Problem-Solution Pairing**: Tag by the problems solved rather than methods used
+    - [[breaking cognitive constraints]], #[[expanding solution spaces]], #[[preventing expert blindness]]
+  - **Intellectual State Triggers**: Tag for when you'd actually search based on mental/emotional context
+    - [[feeling stuck in patterns]], #[[needing fresh perspective]], #[[frustrated with conventional approaches]]
+- ## Tag Maintenance Strategy
+  - **Regular Collision Audits**: Periodically review tags to identify missed connection opportunities
+  - **Surprise Discovery Log**: Track when unexpected tag connections lead to insights, then engineer more of those patterns
+  - **Question Evolution**: Update question-based tags as your intellectual interests and problems evolve
+  - **Cross-Reference Integration**: Ensure new tagging approach complements existing page reference `[[…]]` and hashtag `#[[…]]` conventions
+
+### How to Tag (nuances)
+
+- Consider that when linking a parent block, all children blocks will also accompany future search results. Linking a childblock will only link the child block, not siblings.
+- The convention for tags is lower case unless proper nouns. When tagging might affect the capitalization within a sentence, use aliases. e.g. `[Cognitive biases]([[cognitive biases]]) of the person are listed…"
+- Can longer phrases and expressions be aliased to existing notes? `How one can leverage [[cognitive dissonance]] to [hypnotically influence others using language]([[hypnotic language techniques]])`
+- Reformat quotes in this format structure: `<quote> —[[<Quoted Person>]] #quote <hashtags>` with 2-3 additional relevant hashtag links
+- Anything that needs follow-up, further research, preface with `{{[[TODO]]}}`
+  - Scheduled review: Tag future dates in ordinal format so that it can come up for review when relevant, e.g. `[[For review]]: [[August 12th, 2026]]` Optionally, prepend with label ("Deadline", "For review", "Approved", "Pending", "Deferred", "Postponed until"). Place on parent block if relevant (if children blocks are related).
+
+### Constraints
+
+- Don't overtag.
 
 ⭐️📋 END (Cheat Sheet LOADED) < < < 📋⭐️

package/build/markdown-utils.js

@@ -262,13 +262,14 @@ function convertToRoamActions(nodes, parentUid, order = 'last') {
     const actions = [];
     // Helper function to recursively create actions
     function createBlockActions(blocks, parentUid, order) {
-        for (const block of blocks) {
+        for (let i = 0; i < blocks.length; i++) {
+            const block = blocks[i];
             // Create the current block
             const action = {
                 action: 'create-block',
                 location: {
                     'parent-uid': parentUid,
-                    order
+                    order: typeof order === 'number' ? order + i : i
                 },
                 block: {
                     uid: block.uid,

package/build/search/tag-search.js

@@ -8,42 +8,102 @@ export class TagSearchHandler extends BaseSearchHandler {
         this.params = params;
     }
     async execute() {
-        const { primary_tag, page_title_uid, near_tag, exclude_tag } = this.params;
+        const { primary_tag, page_title_uid, near_tag, exclude_tag, case_sensitive = false, limit = -1, offset = 0 } = this.params;
+        let nearTagUid;
+        if (near_tag) {
+            nearTagUid = await SearchUtils.findPageByTitleOrUid(this.graph, near_tag);
+            if (!nearTagUid) {
+                return {
+                    success: false,
+                    matches: [],
+                    message: `Near tag "${near_tag}" not found.`,
+                    total_count: 0
+                };
+            }
+        }
+        let excludeTagUid;
+        if (exclude_tag) {
+            excludeTagUid = await SearchUtils.findPageByTitleOrUid(this.graph, exclude_tag);
+            if (!excludeTagUid) {
+                return {
+                    success: false,
+                    matches: [],
+                    message: `Exclude tag "${exclude_tag}" not found.`,
+                    total_count: 0
+                };
+            }
+        }
         // Get target page UID if provided for scoped search
         let targetPageUid;
         if (page_title_uid) {
             targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
         }
-        // Build query to find blocks referencing the page
-        let queryArgs = [primary_tag];
+        const searchTags = [];
+        if (case_sensitive) {
+            searchTags.push(primary_tag);
+        }
+        else {
+            searchTags.push(primary_tag);
+            searchTags.push(primary_tag.charAt(0).toUpperCase() + primary_tag.slice(1));
+            searchTags.push(primary_tag.toUpperCase());
+            searchTags.push(primary_tag.toLowerCase());
+        }
+        const tagWhereClauses = searchTags.map(tag => {
+            // Roam tags can be [[tag name]] or #tag-name or #[[tag name]]
+            // The :node/title for a tag page is just the tag name without any # or [[ ]]
+            return `[?ref-page :node/title "${tag}"]`;
+        }).join(' ');
+        let inClause = `:in $`;
+        let queryLimit = limit === -1 ? '' : `:limit ${limit}`;
+        let queryOffset = offset === 0 ? '' : `:offset ${offset}`;
+        let queryOrder = `:order ?page-edit-time asc ?block-uid asc`; // Sort by page edit time, then block UID
         let queryWhereClauses = `
-                      [?ref-page :node/title ?title-match]
-                      [(clojure.string/lower-case ?title-match) ?lower-title]
-                      [(clojure.string/lower-case ?title) ?search-title]
-                      [(= ?lower-title ?search-title)]
+                      (or ${tagWhereClauses})
                       [?b :block/refs ?ref-page]
                       [?b :block/string ?block-str]
                       [?b :block/uid ?block-uid]
                       [?b :block/page ?p]
-                      [?p :node/title ?page-title]`;
-        let inClause = `:in $ ?title`;
+                      [?p :node/title ?page-title]
+                      [?p :edit/time ?page-edit-time]`; // Fetch page edit time for sorting
+        if (nearTagUid) {
+            queryWhereClauses += `
+                      [?b :block/refs ?near-tag-page]
+                      [?near-tag-page :block/uid "${nearTagUid}"]`;
+        }
+        if (excludeTagUid) {
+            queryWhereClauses += `
+                      (not [?b :block/refs ?exclude-tag-page])
+                      [?exclude-tag-page :block/uid "${excludeTagUid}"]`;
+        }
         if (targetPageUid) {
             inClause += ` ?target-page-uid`;
-            queryArgs.push(targetPageUid);
             queryWhereClauses += `
                       [?p :block/uid ?target-page-uid]`;
         }
         const queryStr = `[:find ?block-uid ?block-str ?page-title
-                      ${inClause}
+                      ${inClause} ${queryLimit} ${queryOffset} ${queryOrder}
                       :where 
                       ${queryWhereClauses}]`;
+        const queryArgs = [];
+        if (targetPageUid) {
+            queryArgs.push(targetPageUid);
+        }
         const rawResults = await q(this.graph, queryStr, queryArgs);
+        // Query to get total count without limit
+        const countQueryStr = `[:find (count ?b)
+                            ${inClause}
+                            :where
+                            ${queryWhereClauses.replace(/\[\?p :edit\/time \?page-edit-time\]/, '')}]`; // Remove edit time for count query
+        const totalCountResults = await q(this.graph, countQueryStr, queryArgs);
+        const totalCount = totalCountResults[0] ? totalCountResults[0][0] : 0;
         // 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(resolvedResults, searchDescription, !targetPageUid);
+        const formattedResults = SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
+        formattedResults.total_count = totalCount;
+        return formattedResults;
     }
 }

package/build/search/text-search.js

@@ -8,29 +8,68 @@ export class TextSearchHandler extends BaseSearchHandler {
         this.params = params;
     }
     async execute() {
-        const { text, page_title_uid } = this.params;
+        const { text, page_title_uid, case_sensitive = false, limit = -1, offset = 0 } = this.params;
         // Get target page UID if provided for scoped search
         let targetPageUid;
         if (page_title_uid) {
             targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
         }
-        // Build query to find blocks containing the text
-        const queryStr = `[:find ?block-uid ?block-str ?page-title
-                      :in $ ?search-text
-                      :where 
-                      [?b :block/string ?block-str]
-                      [(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 searchTerms = [];
+        if (case_sensitive) {
+            searchTerms.push(text);
+        }
+        else {
+            searchTerms.push(text);
+            // Add capitalized version (e.g., "Hypnosis")
+            searchTerms.push(text.charAt(0).toUpperCase() + text.slice(1));
+            // Add all caps version (e.g., "HYPNOSIS")
+            searchTerms.push(text.toUpperCase());
+            // Add all lowercase version (e.g., "hypnosis")
+            searchTerms.push(text.toLowerCase());
+        }
+        const whereClauses = searchTerms.map(term => `[(clojure.string/includes? ?block-str "${term}")]`).join(' ');
+        let queryStr;
+        let queryParams = [];
+        let queryLimit = limit === -1 ? '' : `:limit ${limit}`;
+        let queryOffset = offset === 0 ? '' : `:offset ${offset}`;
+        let queryOrder = `:order ?page-edit-time asc ?block-uid asc`; // Sort by page edit time, then block UID
+        let baseQueryWhereClauses = `
+                    [?b :block/string ?block-str]
+                    (or ${whereClauses})
+                    [?b :block/uid ?block-uid]
+                    [?b :block/page ?p]
+                    [?p :node/title ?page-title]
+                    [?p :edit/time ?page-edit-time]`; // Fetch page edit time for sorting
+        if (targetPageUid) {
+            queryStr = `[:find ?block-uid ?block-str ?page-title
+                    :in $ ?page-uid ${queryLimit} ${queryOffset} ${queryOrder}
+                    :where
+                    ${baseQueryWhereClauses}
+                    [?p :block/uid ?page-uid]]`;
+            queryParams = [targetPageUid];
+        }
+        else {
+            queryStr = `[:find ?block-uid ?block-str ?page-title
+                    :in $ ${queryLimit} ${queryOffset} ${queryOrder}
+                    :where
+                    ${baseQueryWhereClauses}]`;
+        }
         const rawResults = await q(this.graph, queryStr, queryParams);
+        // Query to get total count without limit
+        const countQueryStr = `[:find (count ?b)
+                            :in $
+                            :where
+                            ${baseQueryWhereClauses.replace(/\[\?p :edit\/time \?page-edit-time\]/, '')}]`; // Remove edit time for count query
+        const totalCountResults = await q(this.graph, countQueryStr, queryParams);
+        const totalCount = totalCountResults[0] ? totalCountResults[0][0] : 0;
         // 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(resolvedResults, searchDescription, !targetPageUid);
+        const formattedResults = SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
+        formattedResults.total_count = totalCount;
+        return formattedResults;
     }
 }

package/build/tools/helpers/text.js

@@ -1,6 +1,65 @@
+/**
+ * Capitalizes each word in a string
+ */
+import { q } from '@roam-research/roam-api-sdk';
 /**
  * Capitalizes each word in a string
  */
 export const capitalizeWords = (str) => {
     return str.split(' ').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
 };
+/**
+ * Retrieves a block's UID based on its exact text content.
+ * This function is intended for internal use by other MCP tools.
+ * @param graph The Roam graph instance.
+ * @param blockText The exact text content of the block to find.
+ * @returns The UID of the block if found, otherwise null.
+ */
+export const getBlockUidByText = async (graph, blockText) => {
+    const query = `[:find ?uid .
+                  :in $ ?blockString
+                  :where [?b :block/string ?blockString]
+                         [?b :block/uid ?uid]]`;
+    const result = await q(graph, query, [blockText]);
+    return result && result.length > 0 ? result[0][0] : null;
+};
+/**
+ * Retrieves all UIDs nested under a given block_uid or block_text (exact match).
+ * This function is intended for internal use by other MCP tools.
+ * @param graph The Roam graph instance.
+ * @param rootIdentifier The UID or exact text content of the root block.
+ * @returns An array of UIDs of all descendant blocks, including the root block's UID.
+ */
+export const getNestedUids = async (graph, rootIdentifier) => {
+    let rootUid = rootIdentifier;
+    // If the rootIdentifier is not a UID (simple check for 9 alphanumeric characters), try to resolve it as block text
+    if (!rootIdentifier.match(/^[a-zA-Z0-9]{9}$/)) {
+        rootUid = await getBlockUidByText(graph, rootIdentifier);
+    }
+    if (!rootUid) {
+        return []; // No root block found
+    }
+    const query = `[:find ?child-uid
+                  :in $ ?root-uid
+                  :where
+                    [?root-block :block/uid ?root-uid]
+                    [?root-block :block/children ?child-block]
+                    [?child-block :block/uid ?child-uid]]`;
+    const results = await q(graph, query, [rootUid]);
+    return results.map(r => r[0]);
+};
+/**
+ * Retrieves all UIDs nested under a given block_text (exact match).
+ * This function is intended for internal use by other MCP tools.
+ * It strictly requires an exact text match for the root block.
+ * @param graph The Roam graph instance.
+ * @param blockText The exact text content of the root block.
+ * @returns An array of UIDs of all descendant blocks, including the root block's UID.
+ */
+export const getNestedUidsByText = async (graph, blockText) => {
+    const rootUid = await getBlockUidByText(graph, blockText);
+    if (!rootUid) {
+        return []; // No root block found with exact text match
+    }
+    return getNestedUids(graph, rootUid);
+};

package/build/tools/operations/block-retrieval.js

@@ -16,7 +16,7 @@ export class BlockRetrievalOperations {
             const childrenQuery = `[:find ?parentUid ?childUid ?childString ?childOrder ?childHeading
                               :in $ [?parentUid ...]
                               :where [?parent :block/uid ?parentUid]
-                                     [?child :block/parents ?parent]
+                                     [?parent :block/children ?child]
                                      [?child :block/uid ?childUid]
                                      [?child :block/string ?childString]
                                      [?child :block/order ?childOrder]

package/build/tools/operations/outline.js

@@ -6,6 +6,188 @@ import { parseMarkdown, convertToRoamActions, convertToRoamMarkdown } from '../.
 export class OutlineOperations {
     constructor(graph) {
         this.graph = graph;
+        /**
+         * Helper function to check if string is a valid Roam UID (9 characters)
+         */
+        this.isValidUid = (str) => {
+            return typeof str === 'string' && str.length === 9;
+        };
+    }
+    /**
+     * Helper function to find block with improved relationship checks
+     */
+    async findBlockWithRetry(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 "${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 "${blockString}"]
+                 [?b :block/order ?order]
+                 [?b :block/uid ?b-uid]]`,
+            // Strategy 3: Broader page relationship
+            `[:find ?b-uid ?order
+          :where [?p :block/uid "${pageUid}"]
+                 [?b :block/page ?page]
+                 [?p :block/page ?page]
+                 [?b :block/string "${blockString}"]
+                 [?b :block/order ?order]
+                 [?b :block/uid ?b-uid]]`
+        ];
+        for (let retry = 0; retry < maxRetries; retry++) {
+            // Try each query strategy
+            for (const queryStr of queries) {
+                const blockResults = await q(this.graph, queryStr, []);
+                if (blockResults && blockResults.length > 0) {
+                    // Use the most recently created block
+                    const sorted = blockResults.sort((a, b) => b[1] - a[1]);
+                    return sorted[0][0];
+                }
+            }
+            // Exponential backoff
+            const delay = initialDelay * Math.pow(2, retry);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+        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
+     */
+    async createAndVerifyBlock(content, parentUid, maxRetries = 5, initialDelay = 1000, isRetry = false) {
+        try {
+            // Initial delay before any operations
+            if (!isRetry) {
+                await new Promise(resolve => setTimeout(resolve, initialDelay));
+            }
+            for (let retry = 0; retry < maxRetries; retry++) {
+                console.log(`Attempt ${retry + 1}/${maxRetries} to create block "${content}" under "${parentUid}"`);
+                // Create block using batchActions
+                const batchResult = await batchActions(this.graph, {
+                    action: 'batch-actions',
+                    actions: [{
+                            action: 'create-block',
+                            location: {
+                                'parent-uid': parentUid,
+                                order: 'last'
+                            },
+                            block: { string: content }
+                        }]
+                });
+                if (!batchResult) {
+                    throw new McpError(ErrorCode.InternalError, `Failed to create block "${content}" via batch action`);
+                }
+                // Wait with exponential backoff
+                const delay = initialDelay * Math.pow(2, retry);
+                await new Promise(resolve => setTimeout(resolve, delay));
+                try {
+                    // Try to find the block using our improved findBlockWithRetry
+                    return await this.findBlockWithRetry(parentUid, content);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    // console.log(`Failed to find block on attempt ${retry + 1}: ${errorMessage}`); // Removed console.log
+                    if (retry === maxRetries - 1)
+                        throw error;
+                }
+            }
+            throw new McpError(ErrorCode.InternalError, `Failed to create and verify block "${content}" after ${maxRetries} attempts`);
+        }
+        catch (error) {
+            // If this is already a retry, throw the error
+            if (isRetry)
+                throw error;
+            // Otherwise, try one more time with a clean slate
+            // console.log(`Retrying block creation for "${content}" with fresh attempt`); // Removed console.log
+            await new Promise(resolve => setTimeout(resolve, initialDelay * 2));
+            return this.createAndVerifyBlock(content, parentUid, maxRetries, initialDelay, true);
+        }
+    }
+    ;
+    /**
+     * Helper function to fetch a block and its children recursively
+     */
+    async fetchBlockWithChildren(blockUid, level = 1) {
+        const query = `
+        [:find ?childUid ?childString ?childOrder
+         :in $ ?parentUid
+         :where
+         [?parentEntity :block/uid ?parentUid]
+         [?parentEntity :block/children ?childEntity] ; This ensures direct children
+         [?childEntity :block/uid ?childUid]
+         [?childEntity :block/string ?childString]
+         [?childEntity :block/order ?childOrder]]
+      `;
+        const blockQuery = `
+        [:find ?string
+         :in $ ?uid
+         :where
+         [?e :block/uid ?uid]
+         [?e :block/string ?string]]
+      `;
+        try {
+            const blockStringResult = await q(this.graph, blockQuery, [blockUid]);
+            if (!blockStringResult || blockStringResult.length === 0) {
+                return null;
+            }
+            const text = blockStringResult[0][0];
+            const childrenResults = await q(this.graph, query, [blockUid]);
+            const children = [];
+            if (childrenResults && childrenResults.length > 0) {
+                // Sort children by order
+                const sortedChildren = childrenResults.sort((a, b) => a[2] - b[2]);
+                for (const childResult of sortedChildren) {
+                    const childUid = childResult[0];
+                    const nestedChild = await this.fetchBlockWithChildren(childUid, level + 1);
+                    if (nestedChild) {
+                        children.push(nestedChild);
+                    }
+                }
+            }
+            // The order of the root block is not available from this query, so we set it to 0
+            return { uid: blockUid, text, level, order: 0, children: children.length > 0 ? children : undefined };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to fetch block with children for UID "${blockUid}": ${error.message}`);
+        }
+    }
+    ;
+    /**
+     * Recursively fetches a nested structure of blocks under a given root block UID.
+     */
+    async fetchNestedStructure(rootUid) {
+        const query = `[:find ?child-uid ?child-string ?child-order
+                    :in $ ?parent-uid
+                    :where
+                      [?parent :block/uid ?parent-uid]
+                      [?parent :block/children ?child]
+                      [?child :block/uid ?child-uid]
+                      [?child :block/string ?child-string]
+                      [?child :block/order ?child-order]]`;
+        const directChildrenResult = await q(this.graph, query, [rootUid]);
+        if (directChildrenResult.length === 0) {
+            return [];
+        }
+        const nestedBlocks = [];
+        for (const [childUid, childString, childOrder] of directChildrenResult) {
+            const children = await this.fetchNestedStructure(childUid);
+            nestedBlocks.push({
+                uid: childUid,
+                text: childString,
+                level: 0, // Level is not easily determined here, so we set it to 0
+                children: children,
+                order: childOrder
+            });
+        }
+        return nestedBlocks.sort((a, b) => a.order - b.order);
     }
     /**
      * Creates an outline structure on a Roam Research page, optionally under a specific block.
@@ -86,147 +268,6 @@ 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) => {
-            // 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 "${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 "${blockString}"]
-                 [?b :block/order ?order]
-                 [?b :block/uid ?b-uid]]`,
-                // Strategy 3: Broader page relationship
-                `[:find ?b-uid ?order
-          :where [?p :block/uid "${pageUid}"]
-                 [?b :block/page ?page]
-                 [?p :block/page ?page]
-                 [?b :block/string "${blockString}"]
-                 [?b :block/order ?order]
-                 [?b :block/uid ?b-uid]]`
-            ];
-            for (let retry = 0; retry < maxRetries; retry++) {
-                // Try each query strategy
-                for (const queryStr of queries) {
-                    const blockResults = await q(this.graph, queryStr, []);
-                    if (blockResults && blockResults.length > 0) {
-                        // Use the most recently created block
-                        const sorted = blockResults.sort((a, b) => b[1] - a[1]);
-                        return sorted[0][0];
-                    }
-                }
-                // Exponential backoff
-                const delay = initialDelay * Math.pow(2, retry);
-                await new Promise(resolve => setTimeout(resolve, delay));
-            }
-            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) => {
-            try {
-                // Initial delay before any operations
-                if (!isRetry) {
-                    await new Promise(resolve => setTimeout(resolve, initialDelay));
-                }
-                for (let retry = 0; retry < maxRetries; retry++) {
-                    console.log(`Attempt ${retry + 1}/${maxRetries} to create block "${content}" under "${parentUid}"`);
-                    // Create block using batchActions
-                    const batchResult = await batchActions(this.graph, {
-                        action: 'batch-actions',
-                        actions: [{
-                                action: 'create-block',
-                                location: {
-                                    'parent-uid': parentUid,
-                                    order: 'last'
-                                },
-                                block: { string: content }
-                            }]
-                    });
-                    if (!batchResult) {
-                        throw new McpError(ErrorCode.InternalError, `Failed to create block "${content}" via batch action`);
-                    }
-                    // Wait with exponential backoff
-                    const delay = initialDelay * Math.pow(2, retry);
-                    await new Promise(resolve => setTimeout(resolve, delay));
-                    try {
-                        // Try to find the block using our improved findBlockWithRetry
-                        return await findBlockWithRetry(parentUid, content);
-                    }
-                    catch (error) {
-                        const errorMessage = error instanceof Error ? error.message : String(error);
-                        // console.log(`Failed to find block on attempt ${retry + 1}: ${errorMessage}`); // Removed console.log
-                        if (retry === maxRetries - 1)
-                            throw error;
-                    }
-                }
-                throw new McpError(ErrorCode.InternalError, `Failed to create and verify block "${content}" after ${maxRetries} attempts`);
-            }
-            catch (error) {
-                // If this is already a retry, throw the error
-                if (isRetry)
-                    throw error;
-                // Otherwise, try one more time with a clean slate
-                // console.log(`Retrying block creation for "${content}" with fresh attempt`); // Removed console.log
-                await new Promise(resolve => setTimeout(resolve, initialDelay * 2));
-                return createAndVerifyBlock(content, parentUid, maxRetries, initialDelay, true);
-            }
-        };
-        // Helper function to check if string is a valid Roam UID (9 characters)
-        const isValidUid = (str) => {
-            return typeof str === 'string' && str.length === 9;
-        };
-        // Helper function to fetch a block and its children recursively
-        const fetchBlockWithChildren = async (blockUid, level = 1) => {
-            const query = `
-        [:find ?childUid ?childString ?childOrder
-         :in $ ?parentUid
-         :where
-         [?parentEntity :block/uid ?parentUid]
-         [?parentEntity :block/children ?childEntity] ; This ensures direct children
-         [?childEntity :block/uid ?childUid]
-         [?childEntity :block/string ?childString]
-         [?childEntity :block/order ?childOrder]]
-      `;
-            const blockQuery = `
-        [:find ?string
-         :in $ ?uid
-         :where
-         [?e :block/uid ?uid]
-         [?e :block/string ?string]]
-      `;
-            try {
-                const blockStringResult = await q(this.graph, blockQuery, [blockUid]);
-                if (!blockStringResult || blockStringResult.length === 0) {
-                    return null;
-                }
-                const text = blockStringResult[0][0];
-                const childrenResults = await q(this.graph, query, [blockUid]);
-                const children = [];
-                if (childrenResults && childrenResults.length > 0) {
-                    // Sort children by order
-                    const sortedChildren = childrenResults.sort((a, b) => a[2] - b[2]);
-                    for (const childResult of sortedChildren) {
-                        const childUid = childResult[0];
-                        const nestedChild = await fetchBlockWithChildren(childUid, level + 1);
-                        if (nestedChild) {
-                            children.push(nestedChild);
-                        }
-                    }
-                }
-                return { uid: blockUid, text, level, children: children.length > 0 ? children : undefined };
-            }
-            catch (error) {
-                throw new McpError(ErrorCode.InternalError, `Failed to fetch block with children for UID "${blockUid}": ${error.message}`);
-            }
-        };
         // Get or create the parent block
         let targetParentUid;
         if (!block_text_uid) {
@@ -234,7 +275,7 @@ export class OutlineOperations {
         }
         else {
             try {
-                if (isValidUid(block_text_uid)) {
+                if (this.isValidUid(block_text_uid)) {
                     // First try to find block by UID
                     const uidQuery = `[:find ?uid
                            :where [?e :block/uid "${block_text_uid}"]
@@ -250,12 +291,12 @@ export class OutlineOperations {
                 }
                 else {
                     // Create header block and get its UID if not a valid UID
-                    targetParentUid = await createAndVerifyBlock(block_text_uid, targetPageUid);
+                    targetParentUid = await this.createAndVerifyBlock(block_text_uid, targetPageUid);
                 }
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                throw new McpError(ErrorCode.InternalError, `Failed to ${isValidUid(block_text_uid) ? 'find' : 'create'} block "${block_text_uid}": ${errorMessage}`);
+                throw new McpError(ErrorCode.InternalError, `Failed to ${this.isValidUid(block_text_uid) ? 'find' : 'create'} block "${block_text_uid}": ${errorMessage}`);
             }
         }
         // Initialize result variable
@@ -325,9 +366,9 @@ export class OutlineOperations {
         for (const item of topLevelOutlineItems) {
             try {
                 // Assert item.text is a string as it's filtered earlier to be non-undefined and non-empty
-                const foundUid = await findBlockWithRetry(targetParentUid, item.text);
+                const foundUid = await this.findBlockWithRetry(targetParentUid, item.text);
                 if (foundUid) {
-                    const nestedBlock = await fetchBlockWithChildren(foundUid);
+                    const nestedBlock = await this.fetchBlockWithChildren(foundUid);
                     if (nestedBlock) {
                         createdBlocks.push(nestedBlock);
                     }
@@ -346,7 +387,7 @@ export class OutlineOperations {
             created_uids: createdBlocks
         };
     }
-    async importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order = 'first') {
+    async importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order = 'last') {
         // First get the page UID
         let targetPageUid = page_uid;
         if (!targetPageUid && page_title) {
@@ -393,15 +434,20 @@ export class OutlineOperations {
                 throw new McpError(ErrorCode.InvalidRequest, 'Must provide either page_uid or page_title when using parent_string');
             }
             // Find block by exact string match within the page
-            const findBlockQuery = `[:find ?uid
-                             :where [?p :block/uid "${targetPageUid}"]
+            const findBlockQuery = `[:find ?b-uid
+                             :in $ ?page-uid ?block-string
+                             :where [?p :block/uid ?page-uid]
                                     [?b :block/page ?p]
-                                    [?b :block/string "${parent_string}"]]`;
-            const blockResults = await q(this.graph, findBlockQuery, []);
-            if (!blockResults || blockResults.length === 0) {
-                throw new McpError(ErrorCode.InvalidRequest, `Block with content "${parent_string}" not found on specified page`);
+                                    [?b :block/string ?block-string]
+                                    [?b :block/uid ?b-uid]]`;
+            const blockResults = await q(this.graph, findBlockQuery, [targetPageUid, parent_string]);
+            if (blockResults && blockResults.length > 0) {
+                targetParentUid = blockResults[0][0];
+            }
+            else {
+                // If parent_string block doesn't exist, create it
+                targetParentUid = await this.createAndVerifyBlock(parent_string, targetPageUid);
             }
-            targetParentUid = blockResults[0][0];
         }
         // If no parent specified, use page as parent
         if (!targetParentUid) {
@@ -423,8 +469,8 @@ export class OutlineOperations {
             if (!result) {
                 throw new McpError(ErrorCode.InternalError, 'Failed to import nested markdown content');
             }
-            // Get the created block UIDs
-            const createdUids = result.created_uids || [];
+            // After successful batch action, get all nested UIDs under the parent
+            const createdUids = await this.fetchNestedStructure(targetParentUid);
             return {
                 success: true,
                 page_uid: targetPageUid,
@@ -438,26 +484,42 @@ export class OutlineOperations {
                     action: 'create-block',
                     location: {
                         "parent-uid": targetParentUid,
-                        order
+                        "order": order
                     },
                     block: { string: content }
                 }];
             try {
-                const result = await batchActions(this.graph, {
+                await batchActions(this.graph, {
                     action: 'batch-actions',
                     actions
                 });
-                if (!result) {
-                    throw new McpError(ErrorCode.InternalError, 'Failed to create content block via batch action');
-                }
             }
             catch (error) {
                 throw new McpError(ErrorCode.InternalError, `Failed to create content block: ${error instanceof Error ? error.message : String(error)}`);
             }
+            // For single-line content, we still need to fetch the UID and construct a NestedBlock
+            const createdUids = [];
+            try {
+                const foundUid = await this.findBlockWithRetry(targetParentUid, content);
+                if (foundUid) {
+                    createdUids.push({
+                        uid: foundUid,
+                        text: content,
+                        level: 0,
+                        order: 0,
+                        children: []
+                    });
+                }
+            }
+            catch (error) {
+                // Log warning but don't re-throw, as the block might be created, just not immediately verifiable
+                // console.warn(`Could not verify single block creation for "${content}": ${error.message}`);
+            }
             return {
                 success: true,
                 page_uid: targetPageUid,
-                parent_uid: targetParentUid
+                parent_uid: targetParentUid,
+                created_uids: createdUids
             };
         }
     }

package/build/tools/schemas.js

@@ -40,7 +40,7 @@ export const toolSchemas = {
     },
     roam_create_page: {
         name: 'roam_create_page',
-        description: 'Create new standalone page in Roam with optional content using explicit nesting levels and headings (H1-H3). 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.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        description: 'Create a new standalone page in Roam with optional content, including structured outlines, using explicit nesting levels and headings (H1-H3). This is the preferred method for creating a new page with an outline in a single step. 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.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -80,7 +80,7 @@ export const toolSchemas = {
     },
     roam_create_outline: {
         name: 'roam_create_outline',
-        description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. The `outline` parameter defines *new* blocks to be created. To nest content under an *existing* block, provide its UID or exact text in `block_text_uid`, and ensure the `outline` array contains only the child blocks with levels relative to that parent. Including the parent block\'s text in the `outline` array will create a duplicate block. 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\nBest for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider `roam_process_batch_actions` instead.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. To create a new page with an outline, use the `roam_create_page` tool instead. The `outline` parameter defines *new* blocks to be created. To nest content under an *existing* block, provide its UID or exact text in `block_text_uid`, and ensure the `outline` array contains only the child blocks with levels relative to that parent. Including the parent block\'s text in the `outline` array will create a duplicate block. 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\nBest for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider `roam_process_batch_actions` instead.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -129,7 +129,7 @@ export const toolSchemas = {
     },
     roam_import_markdown: {
         name: 'roam_import_markdown',
-        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page. If a `parent_string` is provided and the block does not exist, it will be created. Returns a nested structure of the created blocks.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -151,7 +151,7 @@ export const toolSchemas = {
                 },
                 parent_string: {
                     type: 'string',
-                    description: 'Optional: Exact string content of the parent block to add content under (used if parent_uid is not provided; requires page_uid or page_title).'
+                    description: 'Optional: Exact string content of an existing parent block to add content under (used if parent_uid is not provided; requires page_uid or page_title). If the block does not exist, it will be created.'
                 },
                 order: {
                     type: 'string',
@@ -165,7 +165,7 @@ export const toolSchemas = {
     },
     roam_search_for_tag: {
         name: 'roam_search_for_tag',
-        description: 'Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby. Example: Use this to search for memories that are tagged with the MEMORIES_TAG.',
+        description: 'Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby or exclude blocks with a specific tag. This tool supports pagination via the `limit` and `offset` parameters. Use this tool to search for memories tagged with the MEMORIES_TAG.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -180,6 +180,21 @@ 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 the search should be case-sensitive. If false, it will search for the provided tag, capitalized versions, and first word capitalized versions.',
+                    default: false
+                },
+                limit: {
+                    type: 'integer',
+                    description: 'Optional: The maximum number of results to return. Defaults to 1. Use -1 for no limit.',
+                    default: 1
+                },
+                offset: {
+                    type: 'integer',
+                    description: 'Optional: The number of results to skip before returning matches. Useful for pagination. Defaults to 0.',
+                    default: 0
                 }
             },
             required: ['primary_tag']
@@ -273,7 +288,7 @@ export const toolSchemas = {
     },
     roam_search_by_text: {
         name: 'roam_search_by_text',
-        description: 'Search for blocks containing specific text across all pages or within a specific page.',
+        description: 'Search for blocks containing specific text across all pages or within a specific page. This tool supports pagination via the `limit` and `offset` parameters.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -284,6 +299,21 @@ export const toolSchemas = {
                 page_title_uid: {
                     type: 'string',
                     description: 'Optional: Title or UID of the page to search in (UID is preferred for accuracy). If not provided, searches across all pages.'
+                },
+                case_sensitive: {
+                    type: 'boolean',
+                    description: 'Optional: Whether the search should be case-sensitive. If false, it will search for the provided text, capitalized versions, and first word capitalized versions.',
+                    default: false
+                },
+                limit: {
+                    type: 'integer',
+                    description: 'Optional: The maximum number of results to return. Defaults to 1. Use -1 for no limit.',
+                    default: 1
+                },
+                offset: {
+                    type: 'integer',
+                    description: 'Optional: The number of results to skip before returning matches. Useful for pagination. Defaults to 0.',
+                    default: 0
                 }
             },
             required: ['text']
@@ -354,7 +384,7 @@ export const toolSchemas = {
     },
     roam_recall: {
         name: 'roam_recall',
-        description: 'Retrieve all stored memories on page titled MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories. Optionally filter blcoks with a specified tag and sort by creation date.',
+        description: 'Retrieve all stored memories on page titled MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories. Optionally filter blcoks with a specific tag and sort by creation date.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -373,13 +403,13 @@ export const toolSchemas = {
     },
     roam_datomic_query: {
         name: 'roam_datomic_query',
-        description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. 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.',
+        description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. Note: Roam graph is case-sensitive.\n\n__Optimal Use Cases for `roam_datomic_query`:__\n- __Regex Search:__ Use for scenarios requiring regex, as Datalog does not natively support full regular expressions. It can fetch broader results for client-side post-processing.\n- __Highly Complex Boolean Logic:__ Ideal for intricate combinations of "AND", "OR", and "NOT" conditions across multiple terms or attributes.\n- __Arbitrary Sorting Criteria:__ The go-to for highly customized sorting needs beyond default options.\n- __Proximity Search:__ For advanced search capabilities involving proximity, which are difficult to implement efficiently with simpler tools.\n\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: {
                 query: {
                     type: 'string',
-                    description: 'The Datomic query to execute (in Datalog syntax)'
+                    description: 'The Datomic query to execute (in Datalog syntax). Example: `[:find ?block-string :where [?block :block/string ?block-string] (or [(clojure.string/includes? ?block-string "hypnosis")] [(clojure.string/includes? ?block-string "trance")] [(clojure.string/includes? ?block-string "suggestion")]) :limit 25]`'
                 },
                 inputs: {
                     type: 'array',
@@ -445,10 +475,7 @@ export const toolSchemas = {
                                         description: 'The UID of the parent block or page.'
                                     },
                                     "order": {
-                                        oneOf: [
-                                            { type: 'integer', description: 'Zero-indexed position.' },
-                                            { type: 'string', enum: ['first', 'last'], description: 'Position keyword.' }
-                                        ],
+                                        type: ['integer', 'string'],
                                         description: 'The position of the block under its parent (e.g., 0, 1, 2) or a keyword ("first", "last").'
                                     }
                                 }
@@ -463,7 +490,7 @@ export const toolSchemas = {
     },
     roam_fetch_block_with_children: {
         name: 'roam_fetch_block_with_children',
-        description: 'Fetch a block by its UID along with its hierarchical children down to a specified depth.',
+        description: 'Fetch a block by its UID along with its hierarchical children down to a specified depth. Returns a nested object structure containing the block\'s UID, text, order, and an array of its children.',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.32.4",
+  "version": "0.36.0",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -28,7 +28,7 @@
     "build"
   ],
   "scripts": {
-    "build": "tsc && cat Roam_Markdown_Cheatsheet.md .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md > build/Roam_Markdown_Cheatsheet.md && chmod 755 build/index.js",
+    "build": "echo \"Using custom instructions: .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md\" && tsc && cat Roam_Markdown_Cheatsheet.md .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md > build/Roam_Markdown_Cheatsheet.md && chmod 755 build/index.js",
     "clean": "rm -rf build",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",