roam-research-mcp 0.32.0 → 0.35.1

package/README.md

@@ -73,6 +73,7 @@ docker run -p 3000:3000 -p 8088:8088 -p 8087:8087 \
   -e ROAM_API_TOKEN="your-api-token" \
   -e ROAM_GRAPH_NAME="your-graph-name" \
   -e MEMORIES_TAG="#[[LLM/Memories]]" \
+  -e CUSTOM_INSTRUCTIONS_PATH="/path/to/your/custom_instructions_file.md" \
   -e HTTP_STREAM_PORT="8088" \
   -e SSE_PORT="8087" \
   roam-research-mcp
@@ -106,10 +107,11 @@ The server provides powerful tools for interacting with Roam Research:
 - Efficient batch operations
 - Hierarchical outline creation
 - Enhanced documentation for Roam Tables in `Roam_Markdown_Cheatsheet.md` for clearer guidance on nesting.
+  - Custom instruction appended to the cheat sheet about your specific Roam notes.
 
 1. `roam_fetch_page_by_title`: Fetch page content by title. Returns content in the specified format.
 2. `roam_fetch_block_with_children`: Fetch a block by its UID along with its hierarchical children down to a specified depth. Automatically handles `((UID))` formatting.
-3. `roam_create_page`: Create new pages with optional content and headings.
+3. `roam_create_page`: Create new pages with optional content and headings. Now creates a block on the daily page linking to the newly created page.
 4. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
 5. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
 6. `roam_create_outline`: Add a structured outline to an existing page or block, with support for `children_view_type`. Best for simpler, sequential outlines. For complex nesting (e.g., tables), consider `roam_process_batch_actions`. If `page_title_uid` and `block_text_uid` are both blank, content defaults to the daily page. (Internally uses `roam_process_batch_actions`.)
@@ -242,6 +244,7 @@ This demonstrates moving a block from one location to another and simultaneously
    ROAM_API_TOKEN=your-api-token
    ROAM_GRAPH_NAME=your-graph-name
    MEMORIES_TAG='#[[LLM/Memories]]'
+   CUSTOM_INSTRUCTIONS_PATH='/path/to/your/custom_instructions_file.md'
    HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication
    SSE_PORT=8087 # Or your desired port for SSE communication
    ```
@@ -262,6 +265,7 @@ This demonstrates moving a block from one location to another and simultaneously
            "ROAM_API_TOKEN": "your-api-token",
            "ROAM_GRAPH_NAME": "your-graph-name",
            "MEMORIES_TAG": "#[[LLM/Memories]]",
+           "CUSTOM_INSTRUCTIONS_PATH": "/path/to/your/custom_instructions_file.md",
            "HTTP_STREAM_PORT": "8088",
            "SSE_PORT": "8087"
          }
@@ -347,3 +351,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,7 +113,12 @@ 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
 
----
+NONE
+
+### Don't Include…
+
+NONE
 
 ⭐️📋 END (Cheat Sheet LOADED) < < < 📋⭐️

package/build/markdown-utils.js

@@ -75,73 +75,69 @@ function convertToRoamMarkdown(text) {
     return text;
 }
 function parseMarkdown(markdown) {
-    // Convert markdown syntax first
     markdown = convertToRoamMarkdown(markdown);
-    const lines = markdown.split('\n');
+    const originalLines = markdown.split('\n');
+    const processedLines = [];
+    // Pre-process lines to handle mid-line code blocks without splice
+    for (const line of originalLines) {
+        const trimmedLine = line.trimEnd();
+        const codeStartIndex = trimmedLine.indexOf('```');
+        if (codeStartIndex > 0) {
+            const indentationWhitespace = line.match(/^\s*/)?.[0] ?? '';
+            processedLines.push(indentationWhitespace + trimmedLine.substring(0, codeStartIndex));
+            processedLines.push(indentationWhitespace + trimmedLine.substring(codeStartIndex));
+        }
+        else {
+            processedLines.push(line);
+        }
+    }
     const rootNodes = [];
     const stack = [];
     let inCodeBlock = false;
     let codeBlockContent = '';
     let codeBlockIndentation = 0;
     let codeBlockParentLevel = 0;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
+    for (let i = 0; i < processedLines.length; i++) {
+        const line = processedLines[i];
         const trimmedLine = line.trimEnd();
-        // Handle code blocks
         if (trimmedLine.match(/^(\s*)```/)) {
             if (!inCodeBlock) {
-                // Start of code block
                 inCodeBlock = true;
-                // Store the opening backticks without indentation
                 codeBlockContent = trimmedLine.trimStart() + '\n';
                 codeBlockIndentation = line.match(/^\s*/)?.[0].length ?? 0;
-                // Save current parent level
                 codeBlockParentLevel = stack.length;
             }
             else {
-                // End of code block
                 inCodeBlock = false;
-                // Add closing backticks without indentation
                 codeBlockContent += trimmedLine.trimStart();
-                // Process the code block content to fix indentation
-                const lines = codeBlockContent.split('\n');
-                // Find the first non-empty code line to determine base indentation
+                const linesInCodeBlock = codeBlockContent.split('\n');
                 let baseIndentation = '';
-                let codeStartIndex = -1;
-                for (let i = 1; i < lines.length - 1; i++) {
-                    const line = lines[i];
-                    if (line.trim().length > 0) {
-                        const indentMatch = line.match(/^[\t ]*/);
+                for (let j = 1; j < linesInCodeBlock.length - 1; j++) {
+                    const codeLine = linesInCodeBlock[j];
+                    if (codeLine.trim().length > 0) {
+                        const indentMatch = codeLine.match(/^[\t ]*/);
                         if (indentMatch) {
                             baseIndentation = indentMatch[0];
-                            codeStartIndex = i;
                             break;
                         }
                     }
                 }
-                // Process lines maintaining relative indentation from the first code line
-                const processedLines = lines.map((line, index) => {
-                    // Keep backticks as is
-                    if (index === 0 || index === lines.length - 1)
-                        return line.trimStart();
-                    // Empty lines should be completely trimmed
-                    if (line.trim().length === 0)
+                const processedCodeLines = linesInCodeBlock.map((codeLine, index) => {
+                    if (index === 0 || index === linesInCodeBlock.length - 1)
+                        return codeLine.trimStart();
+                    if (codeLine.trim().length === 0)
                         return '';
-                    // For code lines, remove only the base indentation
-                    if (line.startsWith(baseIndentation)) {
-                        return line.slice(baseIndentation.length);
+                    if (codeLine.startsWith(baseIndentation)) {
+                        return codeLine.slice(baseIndentation.length);
                     }
-                    // If line has less indentation than base, trim all leading whitespace
-                    return line.trimStart();
+                    return codeLine.trimStart();
                 });
-                // Create node for the entire code block
                 const level = Math.floor(codeBlockIndentation / 2);
                 const node = {
-                    content: processedLines.join('\n'),
+                    content: processedCodeLines.join('\n'),
                     level,
                     children: []
                 };
-                // Restore to code block's parent level
                 while (stack.length > codeBlockParentLevel) {
                     stack.pop();
                 }
@@ -169,37 +165,30 @@ function parseMarkdown(markdown) {
             codeBlockContent += line + '\n';
             continue;
         }
-        // Skip truly empty lines (no spaces)
         if (trimmedLine === '') {
             continue;
         }
-        // Calculate indentation level (2 spaces = 1 level)
         const indentation = line.match(/^\s*/)?.[0].length ?? 0;
         let level = Math.floor(indentation / 2);
         let contentToParse;
         const bulletMatch = trimmedLine.match(/^(\s*)[-*+]\s+/);
         if (bulletMatch) {
-            // If it's a bullet point, adjust level based on bullet indentation
             level = Math.floor(bulletMatch[1].length / 2);
-            contentToParse = trimmedLine.substring(bulletMatch[0].length); // Content after bullet
+            contentToParse = trimmedLine.substring(bulletMatch[0].length);
         }
         else {
-            contentToParse = trimmedLine; // No bullet, use trimmed line
+            contentToParse = trimmedLine;
         }
-        // Now, from the content after bullet/initial indentation, check for heading
         const { heading_level, content: finalContent } = parseMarkdownHeadingLevel(contentToParse);
-        // Create node
         const node = {
-            content: finalContent, // Use content after heading parsing
-            level, // Use level derived from bullet/indentation
+            content: finalContent,
+            level,
             ...(heading_level > 0 && { heading_level }),
             children: []
         };
-        // Pop stack until we find the parent level
         while (stack.length > level) {
             stack.pop();
         }
-        // Add to appropriate parent
         if (level === 0 || !stack[level - 1]) {
             rootNodes.push(node);
             stack[0] = node;
@@ -273,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/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.
@@ -21,6 +203,7 @@ export class OutlineOperations {
      *                         no matching block is found, a new block with that text will be created
      *                         on the page to serve as the parent. If a UID is provided and the block
      *                         is not found, an error will be thrown.
+     * @returns An object containing success status, page UID, parent UID, and a nested array of created block UIDs.
      */
     async createOutline(outline, page_title_uid, block_text_uid) {
         // Validate input
@@ -85,104 +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));
-                console.log(`Retry ${retry + 1}/${maxRetries} finding block "${blockString}" under "${pageUid}"`);
-            }
-            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}`);
-                        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`);
-                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;
-        };
         // Get or create the parent block
         let targetParentUid;
         if (!block_text_uid) {
@@ -190,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}"]
@@ -206,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
@@ -235,7 +320,9 @@ export class OutlineOperations {
                 const indent = '  '.repeat(item.level - 1);
                 // If the item text starts with a markdown heading (e.g., #, ##, ###),
                 // treat it as a direct heading without adding a bullet or outline indentation.
-                return `${indent}- ${item.text?.trim()}`;
+                // NEW CHANGE: Handle standalone code blocks - do not prepend bullet
+                const isCodeBlock = item.text?.startsWith('```') && item.text.endsWith('```') && item.text.includes('\n');
+                return isCodeBlock ? `${indent}${item.text?.trim()}` : `${indent}- ${item.text?.trim()}`;
             })
                 .join('\n');
             // Convert to Roam markdown format
@@ -243,13 +330,16 @@ export class OutlineOperations {
             // Parse markdown into hierarchical structure
             // We pass the original OutlineItem properties (heading, children_view_type)
             // along with the parsed content to the nodes.
-            const nodes = parseMarkdown(convertedContent).map((node, index) => ({
-                ...node,
-                ...(validOutline[index].heading && { heading_level: validOutline[index].heading }),
-                ...(validOutline[index].children_view_type && { children_view_type: validOutline[index].children_view_type })
-            }));
+            const nodes = parseMarkdown(convertedContent).map((node, index) => {
+                const outlineItem = validOutline[index];
+                return {
+                    ...node,
+                    ...(outlineItem?.heading && { heading_level: outlineItem.heading }),
+                    ...(outlineItem?.children_view_type && { children_view_type: outlineItem.children_view_type })
+                };
+            });
             // Convert nodes to batch actions
-            const actions = convertToRoamActions(nodes, targetParentUid, 'first');
+            const actions = convertToRoamActions(nodes, targetParentUid, 'last');
             if (actions.length === 0) {
                 throw new McpError(ErrorCode.InvalidRequest, 'No valid actions generated from outline');
             }
@@ -269,16 +359,35 @@ export class OutlineOperations {
                 throw error;
             throw new McpError(ErrorCode.InternalError, `Failed to create outline: ${error.message}`);
         }
-        // Get the created block UIDs
-        const createdUids = result?.created_uids || [];
+        // Post-creation verification to get actual UIDs for top-level blocks and their children
+        const createdBlocks = [];
+        // Only query for top-level blocks (level 1) based on the original outline input
+        const topLevelOutlineItems = validOutline.filter(item => item.level === 1);
+        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 this.findBlockWithRetry(targetParentUid, item.text);
+                if (foundUid) {
+                    const nestedBlock = await this.fetchBlockWithChildren(foundUid);
+                    if (nestedBlock) {
+                        createdBlocks.push(nestedBlock);
+                    }
+                }
+            }
+            catch (error) {
+                // This is a warning because even if one block fails to fetch, others might succeed.
+                // The error will be logged but not re-thrown to allow partial success reporting.
+                // console.warn(`Could not fetch nested block for "${item.text}": ${error.message}`);
+            }
+        }
         return {
             success: true,
             page_uid: targetPageUid,
             parent_uid: targetParentUid,
-            created_uids: createdUids
+            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) {
@@ -325,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) {
@@ -355,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,
@@ -370,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/operations/pages.js

@@ -1,8 +1,19 @@
-import { q, createPage as createRoamPage, batchActions } from '@roam-research/roam-api-sdk';
+import { q, createPage as createRoamPage, batchActions, createBlock } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { capitalizeWords } from '../helpers/text.js';
 import { resolveRefs } from '../helpers/refs.js';
 import { convertToRoamActions, convertToRoamMarkdown } from '../../markdown-utils.js';
+// Helper to get ordinal suffix for dates
+function getOrdinalSuffix(day) {
+    if (day > 3 && day < 21)
+        return 'th'; // Handles 11th, 12th, 13th
+    switch (day % 10) {
+        case 1: return 'st';
+        case 2: return 'nd';
+        case 3: return 'rd';
+        default: return 'th';
+    }
+}
 export class PageOperations {
     constructor(graph) {
         this.graph = graph;
@@ -124,6 +135,37 @@ export class PageOperations {
                 throw new McpError(ErrorCode.InternalError, `Failed to add content to page: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        // Add a link to the created page on today's daily page
+        try {
+            const today = new Date();
+            const day = today.getDate();
+            const month = today.toLocaleString('en-US', { month: 'long' });
+            const year = today.getFullYear();
+            const formattedTodayTitle = `${month} ${day}${getOrdinalSuffix(day)}, ${year}`;
+            const dailyPageQuery = `[:find ?uid .
+                              :where [?e :node/title "${formattedTodayTitle}"]
+                                     [?e :block/uid ?uid]]`;
+            const dailyPageResult = await q(this.graph, dailyPageQuery, []);
+            const dailyPageUid = dailyPageResult ? String(dailyPageResult) : null;
+            if (dailyPageUid) {
+                await createBlock(this.graph, {
+                    action: 'create-block',
+                    block: {
+                        string: `Created page: [[${pageTitle}]]`
+                    },
+                    location: {
+                        'parent-uid': dailyPageUid,
+                        order: 'last'
+                    }
+                });
+            }
+            else {
+                console.warn(`Could not find daily page with title: ${formattedTodayTitle}. Link to created page not added.`);
+            }
+        }
+        catch (error) {
+            console.error(`Failed to add link to daily page: ${error instanceof Error ? error.message : String(error)}`);
+        }
         return { success: true, uid: pageUid };
     }
     async fetchPageByTitle(title, format = 'raw') {

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',
@@ -463,7 +463,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.0",
+  "version": "0.35.1",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -28,7 +28,7 @@
     "build"
   ],
   "scripts": {
-    "build": "tsc && cp Roam_Markdown_Cheatsheet.md build/Roam_Markdown_Cheatsheet.md && chmod 755 build/index.js",
+    "build": "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",