roam-research-mcp 0.30.2 → 0.32.4

package/README.md

@@ -1,3 +1,5 @@
+![](./roam-research-mcp-image.jpeg)
+
 # Roam Research MCP Server
 
 [![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)
@@ -8,6 +10,7 @@
 A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. It supports standard input/output (stdio), HTTP Stream, and Server-Sent Events (SSE) communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
 
 <a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://glama.ai/mcp/servers/fzfznyaflu/badge" alt="Roam Research MCP server" /></a>
+<a href="https://mseep.ai/app/2b3pro-roam-research-mcp"><img width="380" height="200" src="https://mseep.net/pr/2b3pro-roam-research-mcp-badge.png" alt="MseeP.ai Security Assessment Badge" /></a>
 
 ## Installation and Usage
 
@@ -70,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
@@ -103,23 +107,26 @@ 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_create_page`: Create new pages with optional content and headings.
-3. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
-4. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
-5. `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`.)
-6. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
-7. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
-8. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight).
-9. `roam_search_by_text`: Search for blocks containing specific text.
-10. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
-11. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
-12. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.
-13. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
-14. `roam_recall`: Retrieve all stored memories.
-15. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools.
-16. `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`.)
+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. 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`.)
+7. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
+8. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
+9. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight).
+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.
+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.
+17. `roam_markdown_cheatsheet`: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if `CUSTOM_INSTRUCTIONS_PATH` environment variable is set.
+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`:
@@ -135,6 +142,8 @@ The following tools have been deprecated as of `v.0.30.0` in favor of the more p
 **Pre-computation and Context Loading:**
 ✅ Before attempting any Roam operations, **it is highly recommended** to load the `Roam Markdown Cheatsheet` resource into your context. This ensures you have immediate access to the correct Roam-flavored Markdown syntax, including details for tables, block references, and other special formatting. Example prompt: "Read the Roam cheatsheet first. Then, … <rest of your instructions>"
 
+- **Specific notes and preferences** concerning my Roam Research graph. Users can add their own specific notes and preferences for working with their own graph in the Cheatsheet.
+
 **Identifying Pages and Blocks for Manipulation:**
 To ensure accurate operations, always strive to identify target pages and blocks using their Unique Identifiers (UIDs) whenever possible. While some tools accept case-sensitive text titles or content, UIDs provide unambiguous references, reducing the risk of errors due to ambiguity or changes in text.
 
@@ -207,6 +216,14 @@ This demonstrates moving a block from one location to another and simultaneously
 "Move the block 'Important note about client feedback' (from page 'Meeting Notes 2025-06-30') under the 'Action Items' section on the 'Project Alpha Planning' page, and change its content to 'Client feedback reviewed and incorporated'."
 ```
 
+### Example 4: Making a Table
+
+This demonstrates moving a block from one location to another and simultaneously updating its content.
+
+```
+"In Roam, add a new table on the page "Fruity Tables" that compares four types of fruits: apples, oranges, grapes, and dates. Choose randomly four areas to compare."
+```
+
 ---
 
 ## Setup
@@ -227,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
    ```
@@ -247,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"
          }
@@ -258,6 +277,9 @@ This demonstrates moving a block from one location to another and simultaneously
    Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.
 
 3. Build the server (make sure you're in the root directory of the MCP):
+
+   Note: Customize 'Roam_Markdown_Cheatsheet.md' with any notes and preferences specific to your graph BEFORE building.
+
    ```bash
    cd roam-research-mcp
    npm install

package/build/Roam_Markdown_Cheatsheet.md

@@ -0,0 +1,123 @@
+!!!! IMPORTANT: Always consult this cheatsheet for correct Roam-flavored markdown syntax BEFORE making any Roam tool calls.
+
+# Roam Markdown Cheatsheet
+
+⭐️📋 > > > START 📋⭐️
+
+## Markdown Styles in Roam:
+
+- **Bold Text here**
+- **Italics Text here**
+- External Link: `[Link text](URL)`
+- Image Embed: `![Alt text](URL)`
+- ^^Highlighted Text here^^
+- Bullet points: - or \* followed by a space and the text
+- {{[[TODO]]}} todo text
+- {{[[DONE]]}} todo text
+- LaTeX: `$$E=mc^2$$` or `$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$`
+
+## Roam-specific Markdown:
+
+- Dates are in ordinal format: `[[January 1st, 2025]]`
+- Block references: `((block-id))` This inserts a reference to the content of a specific block.
+- Page references: `[[Page name]]` This creates a link to another page within your Roam graph.
+- Link to blocks: `[Link Text](<((block-id))>)` This will link to the block.
+- Embed block in a block: `{{[[embed]]: ((block-id))}}`
+- To-do items: `{{[[TODO]]}} todo text` or `{{[[DONE]]}} todo text`
+- Syntax highlighting for fenced code blocks (add language next to backticks before fenced code block - all in one block) - Example:
+  ```javascript
+      const foo(bar) => {
+          return bar;
+      }
+  ```
+- Tags:
+  - one-word: `#word`
+  - multiple words: `#[[two or more words]]`
+  - hyphenated words: `#self-esteem`
+
+## Roam Tables
+
+Roam tables are created by nesting blocks under a `{{[[table]]}}` parent block. The key to correct table rendering is to ensure proper indentation levels for headers and data cells. Each subsequent header or data cell within a row must be nested one level deeper than the previous one.
+
+- The `{{[[table]]}}` block acts as the container for the entire table.
+- The first header block should be at level 2 (one level deeper than `{{[[table]]}}`).
+- Subsequent header blocks must increase their level by one.
+- Each row starts at level 2.
+- The first data cell in a row is at level 3 (one level deeper than the row block).
+- Subsequent data cells within the same row must increase their level by one.
+
+Example of a 4x4 table structure:
+
+```
+{{[[table]]}}
+    - Header 1
+        - Header 2
+            - Header 3
+                - Header 4
+    - Row 1
+        - Data 1.1
+            - Data 1.2
+                - Data 1.3
+                    - Data 1.4
+    - Row 2
+        - Data 2.1
+            - Data 2.2
+                - Data 2.3
+                    - Data 2.4
+    - Row 3
+        - Data 3.1
+            - Data 3.2
+                - Data 3.3
+                    - Data 3.4
+    - Row 4
+        - Data 4.1
+            - Data 4.2
+                - Data 4.3
+                    - Data 4.4
+```
+
+## Roam Mermaid
+
+This markdown structure represents a Roam Research Mermaid diagram. It begins with a `{{[[mermaid]]}}` block, which serves as the primary container for the diagram definition. Nested underneath this block, using bullet points, is the actual Mermaid syntax. Each bullet point corresponds to a line of the Mermaid graph definition, allowing Roam to render a visual diagram based on the provided code. For example, `graph TD` specifies a top-down directed graph, and subsequent bullet points define nodes and their connections.
+
+```
+- {{[[mermaid]]}}
+    - graph TD
+        - A[Start] --> B{Decision Point}
+        - B -->|Yes| C[Process A]
+        - B -->|No| D[Process B]
+        - C --> E[Merge Results]
+        - D --> E
+        - E --> F[End]
+```
+
+## Roam Kanban Boards
+
+The provided markdown structure represents a Roam Research Kanban board. It starts with a `{{[[kanban]]}}` block, under which nested bullet points define the Kanban cards. Each top-level bullet point directly under `{{[[kanban]]}}` serves as a card title, and any further nested bullet points under a card title act as details or sub-items for that specific card.
+
+```
+- {{[[kanban]]}}
+    - card title 1
+        - bullet point 1.1
+        - bullet point 1.2
+    - card title 2
+        - bullet point 2.1
+        - bullet point 2.2
+```
+
+---
+
+## Roam Hiccup
+
+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/config/environment.js

@@ -41,6 +41,7 @@ if (!API_TOKEN || !GRAPH_NAME) {
         '   ROAM_API_TOKEN=your-api-token\n' +
         '   ROAM_GRAPH_NAME=your-graph-name');
 }
-const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088'; // Default to 8080
+const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088'; // Default to 8088
 const SSE_PORT = process.env.SSE_PORT || '8087'; // Default to 8087
-export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT };
+const CORS_ORIGIN = process.env.CORS_ORIGIN || 'http://localhost:5678';
+export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT, CORS_ORIGIN };

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;
@@ -268,8 +257,8 @@ function convertNodesToBlocks(nodes) {
     }));
 }
 function convertToRoamActions(nodes, parentUid, order = 'last') {
-    // First convert nodes to blocks with UIDs, reversing to maintain original order
-    const blocks = convertNodesToBlocks([...nodes].reverse());
+    // First convert nodes to blocks with UIDs
+    const blocks = convertNodesToBlocks(nodes);
     const actions = [];
     // Helper function to recursively create actions
     function createBlockActions(blocks, parentUid, order) {

package/build/search/tag-search.js

@@ -15,9 +15,8 @@ export class TagSearchHandler extends BaseSearchHandler {
             targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
         }
         // Build query to find blocks referencing the page
-        const queryStr = `[:find ?block-uid ?block-str ?page-title
-                      :in $ ?title
-                      :where 
+        let queryArgs = [primary_tag];
+        let queryWhereClauses = `
                       [?ref-page :node/title ?title-match]
                       [(clojure.string/lower-case ?title-match) ?lower-title]
                       [(clojure.string/lower-case ?title) ?search-title]
@@ -26,9 +25,19 @@ export class TagSearchHandler extends BaseSearchHandler {
                       [?b :block/string ?block-str]
                       [?b :block/uid ?block-uid]
                       [?b :block/page ?p]
-                      [?p :node/title ?page-title]]`;
-        const queryParams = [primary_tag];
-        const rawResults = await q(this.graph, queryStr, queryParams);
+                      [?p :node/title ?page-title]`;
+        let inClause = `:in $ ?title`;
+        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}
+                      :where 
+                      ${queryWhereClauses}]`;
+        const rawResults = await q(this.graph, queryStr, queryArgs);
         // Resolve block references in content
         const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
             const resolvedContent = await resolveRefs(this.graph, content);

package/build/server/roam-server.js

@@ -1,10 +1,9 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initializeGraph } from '@roam-research/roam-api-sdk';
-import { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT } from '../config/environment.js';
+import { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT } from '../config/environment.js';
 import { toolSchemas } from '../tools/schemas.js';
 import { ToolHandlers } from '../tools/tool-handlers.js';
 import { readFileSync } from 'node:fs';
@@ -12,6 +11,7 @@ import { join, dirname } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { findAvailablePort } from '../utils/net.js';
+import { CORS_ORIGIN } from '../config/environment.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read package.json to get the version
@@ -20,7 +20,7 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 const serverVersion = packageJson.version;
 export class RoamServer {
     constructor() {
-        console.log('RoamServer: Constructor started.');
+        // console.log('RoamServer: Constructor started.');
         try {
             this.graph = initializeGraph({
                 token: API_TOKEN,
@@ -42,7 +42,7 @@ export class RoamServer {
         if (Object.keys(toolSchemas).length === 0) {
             throw new McpError(ErrorCode.InternalError, 'No tool schemas defined in src/tools/schemas.ts');
         }
-        console.log('RoamServer: Constructor finished.');
+        // console.log('RoamServer: Constructor finished.');
     }
     // Refactored to accept a Server instance
     setupRequestHandlers(mcpServer) {
@@ -52,34 +52,23 @@ export class RoamServer {
         }));
         // List available resources
         mcpServer.setRequestHandler(ListResourcesRequestSchema, async () => {
-            const resources = [
-                {
-                    name: 'Roam Markdown Cheatsheet',
-                    uri: 'roam-markdown-cheatsheet.md',
-                    type: 'text', // Changed from ResourceType.Text to string literal 'text'
-                    description: 'A cheatsheet for Roam-flavored Markdown syntax.',
-                },
-            ];
+            const resources = []; // No resources, as cheatsheet is now a tool
             return { resources };
         });
-        // Access resource
+        // Access resource - no resources handled directly here anymore
         mcpServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-            if (request.params.uri === 'roam-markdown-cheatsheet.md') {
-                const cheatsheetPath = join(__dirname, '../../Roam_Markdown_Cheatsheet.md');
-                try {
-                    const content = readFileSync(cheatsheetPath, 'utf8');
-                    return { contents: [{ type: 'text', text: content, uri: request.params.uri }] };
-                }
-                catch (error) {
-                    throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`); // Changed to InternalError
-                }
-            }
-            throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`); // Changed to InternalError
+            throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`);
         });
         // Handle tool calls
         mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
                 switch (request.params.name) {
+                    case 'roam_markdown_cheatsheet': {
+                        const content = await this.toolHandlers.getRoamMarkdownCheatsheet();
+                        return {
+                            content: [{ type: 'text', text: content }],
+                        };
+                    }
                     case 'roam_remember': {
                         const { memory, categories } = request.params.arguments;
                         const result = await this.toolHandlers.remember(memory, categories);
@@ -196,6 +185,13 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
+                    case 'roam_fetch_block_with_children': {
+                        const { block_uid, depth } = request.params.arguments;
+                        const result = await this.toolHandlers.fetchBlockWithChildren(block_uid, depth);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }
@@ -210,55 +206,65 @@ export class RoamServer {
         });
     }
     async run() {
-        console.log('RoamServer: run() method started.');
+        // console.log('RoamServer: run() method started.');
         try {
-            console.log('RoamServer: Attempting to create stdioMcpServer...');
+            // console.log('RoamServer: Attempting to create stdioMcpServer...');
             const stdioMcpServer = new Server({
                 name: 'roam-research',
                 version: serverVersion,
             }, {
                 capabilities: {
                     tools: {
-                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
+                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, toolSchemas[toolName].inputSchema])),
                     },
                     resources: {
                         'roam-markdown-cheatsheet.md': {}
                     }
                 },
             });
-            console.log('RoamServer: stdioMcpServer created. Setting up request handlers...');
+            // console.log('RoamServer: stdioMcpServer created. Setting up request handlers...');
             this.setupRequestHandlers(stdioMcpServer);
-            console.log('RoamServer: stdioMcpServer handlers setup complete. Connecting transport...');
+            // console.log('RoamServer: stdioMcpServer handlers setup complete. Connecting transport...');
             const stdioTransport = new StdioServerTransport();
             await stdioMcpServer.connect(stdioTransport);
-            console.log('RoamServer: stdioTransport connected. Attempting to create httpMcpServer...');
+            // console.log('RoamServer: stdioTransport connected. Attempting to create httpMcpServer...');
             const httpMcpServer = new Server({
                 name: 'roam-research-http', // A distinct name for the HTTP server
                 version: serverVersion,
             }, {
                 capabilities: {
                     tools: {
-                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
+                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, toolSchemas[toolName].inputSchema])),
                     },
                     resources: {
                         'roam-markdown-cheatsheet.md': {}
                     }
                 },
             });
-            console.log('RoamServer: httpMcpServer created. Setting up request handlers...');
+            // console.log('RoamServer: httpMcpServer created. Setting up request handlers...');
             this.setupRequestHandlers(httpMcpServer);
-            console.log('RoamServer: httpMcpServer handlers setup complete. Connecting transport...');
+            // console.log('RoamServer: httpMcpServer handlers setup complete. Connecting transport...');
             const httpStreamTransport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: () => Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
             });
             await httpMcpServer.connect(httpStreamTransport);
-            console.log('RoamServer: httpStreamTransport connected.');
+            // console.log('RoamServer: httpStreamTransport connected.');
             const httpServer = createServer(async (req, res) => {
+                // Set CORS headers
+                res.setHeader('Access-Control-Allow-Origin', CORS_ORIGIN);
+                res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+                // Handle preflight OPTIONS requests
+                if (req.method === 'OPTIONS') {
+                    res.writeHead(204); // No Content
+                    res.end();
+                    return;
+                }
                 try {
                     await httpStreamTransport.handleRequest(req, res);
                 }
                 catch (error) {
-                    // console.error('HTTP Stream Server error:', error);
+                    // // console.error('HTTP Stream Server error:', error);
                     if (!res.headersSent) {
                         res.writeHead(500, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({ error: 'Internal Server Error' }));
@@ -267,70 +273,7 @@ export class RoamServer {
             });
             const availableHttpPort = await findAvailablePort(parseInt(HTTP_STREAM_PORT));
             httpServer.listen(availableHttpPort, () => {
-                // console.log(`MCP Roam Research server running HTTP Stream on port ${availableHttpPort}`);
-            });
-            // SSE Server setup
-            const sseMcpServer = new Server({
-                name: 'roam-research-sse', // Distinct name for SSE server
-                version: serverVersion,
-            }, {
-                capabilities: {
-                    tools: {
-                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
-                    },
-                },
-            });
-            this.setupRequestHandlers(sseMcpServer);
-            const sseHttpServer = createServer(async (req, res) => {
-                const parseBody = (request) => {
-                    return new Promise((resolve, reject) => {
-                        let body = '';
-                        request.on('data', (chunk) => {
-                            body += chunk.toString();
-                        });
-                        request.on('end', () => {
-                            try {
-                                resolve(body ? JSON.parse(body) : {});
-                            }
-                            catch (error) {
-                                reject(error);
-                            }
-                        });
-                        request.on('error', reject);
-                    });
-                };
-                try {
-                    if (req.url === '/sse') {
-                        const sseTransport = new SSEServerTransport('/sse', res);
-                        await sseMcpServer.connect(sseTransport);
-                        if (req.method === 'GET') {
-                            await sseTransport.start();
-                        }
-                        else if (req.method === 'POST') {
-                            const parsedBody = await parseBody(req);
-                            await sseTransport.handlePostMessage(req, res, parsedBody);
-                        }
-                        else {
-                            res.writeHead(405, { 'Content-Type': 'text/plain' });
-                            res.end('Method Not Allowed');
-                        }
-                    }
-                    else {
-                        res.writeHead(404, { 'Content-Type': 'text/plain' });
-                        res.end('Not Found');
-                    }
-                }
-                catch (error) {
-                    // console.error('SSE HTTP Server error:', error);
-                    if (!res.headersSent) {
-                        res.writeHead(500, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ error: 'Internal Server Error' }));
-                    }
-                }
-            });
-            const availableSsePort = await findAvailablePort(parseInt(SSE_PORT));
-            sseHttpServer.listen(availableSsePort, () => {
-                // console.log(`MCP Roam Research server running SSE on port ${availableSsePort}`);
+                // // console.log(`MCP Roam Research server running HTTP Stream on port ${availableHttpPort}`);
             });
         }
         catch (error) {

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

@@ -0,0 +1,74 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+export class BlockRetrievalOperations {
+    constructor(graph) {
+        this.graph = graph;
+    }
+    async fetchBlockWithChildren(block_uid_raw, depth = 4) {
+        if (!block_uid_raw) {
+            throw new McpError(ErrorCode.InvalidRequest, 'block_uid is required.');
+        }
+        const block_uid = block_uid_raw.replace(/^\(\((.*)\)\)$/, '$1');
+        const fetchChildren = async (parentUids, currentDepth) => {
+            if (currentDepth >= depth || parentUids.length === 0) {
+                return {};
+            }
+            const childrenQuery = `[:find ?parentUid ?childUid ?childString ?childOrder ?childHeading
+                              :in $ [?parentUid ...]
+                              :where [?parent :block/uid ?parentUid]
+                                     [?child :block/parents ?parent]
+                                     [?child :block/uid ?childUid]
+                                     [?child :block/string ?childString]
+                                     [?child :block/order ?childOrder]
+                                     [(get-else $ ?child :block/heading 0) ?childHeading]]`;
+            const childrenResults = await q(this.graph, childrenQuery, [parentUids]);
+            const childrenByParent = {};
+            const allChildUids = [];
+            for (const [parentUid, childUid, childString, childOrder, childHeading] of childrenResults) {
+                if (!childrenByParent[parentUid]) {
+                    childrenByParent[parentUid] = [];
+                }
+                childrenByParent[parentUid].push({
+                    uid: childUid,
+                    string: childString,
+                    order: childOrder,
+                    heading: childHeading || undefined,
+                    children: [],
+                });
+                allChildUids.push(childUid);
+            }
+            const grandChildren = await fetchChildren(allChildUids, currentDepth + 1);
+            for (const parentUid in childrenByParent) {
+                for (const child of childrenByParent[parentUid]) {
+                    child.children = grandChildren[child.uid] || [];
+                }
+                childrenByParent[parentUid].sort((a, b) => a.order - b.order);
+            }
+            return childrenByParent;
+        };
+        try {
+            const rootBlockQuery = `[:find ?string ?order ?heading
+                               :in $ ?blockUid
+                               :where [?b :block/uid ?blockUid]
+                                      [?b :block/string ?string]
+                                      [?b :block/order ?order]
+                                      [(get-else $ ?b :block/heading 0) ?heading]]`;
+            const rootBlockResult = await q(this.graph, rootBlockQuery, [block_uid]);
+            if (!rootBlockResult) {
+                return null;
+            }
+            const [rootString, rootOrder, rootHeading] = rootBlockResult;
+            const childrenMap = await fetchChildren([block_uid], 0);
+            return {
+                uid: block_uid,
+                string: rootString,
+                order: rootOrder,
+                heading: rootHeading || undefined,
+                children: childrenMap[block_uid] || [],
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to fetch block with children: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}

package/build/tools/operations/blocks.js

@@ -96,14 +96,6 @@ export class BlockOperations {
                     // No heading parameter, use original parsing logic
                     const convertedContent = convertToRoamMarkdown(content);
                     nodes = parseMarkdown(convertedContent);
-                    // If we have simple newline-separated content (no markdown formatting),
-                    // and parseMarkdown created nodes at level 0, reverse them to maintain original order
-                    if (nodes.every(node => node.level === 0 && !node.heading_level)) {
-                        const lines = content.split('\n').filter(line => line.trim());
-                        if (lines.length === nodes.length) {
-                            nodes.reverse();
-                        }
-                    }
                 }
                 const actions = convertToRoamActions(nodes, targetPageUid, 'last');
                 // Execute batch actions to create the nested structure

package/build/tools/operations/outline.js

@@ -21,6 +21,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
@@ -125,7 +126,6 @@ export class OutlineOperations {
                 // 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`);
         };
@@ -162,7 +162,7 @@ export class OutlineOperations {
                     }
                     catch (error) {
                         const errorMessage = error instanceof Error ? error.message : String(error);
-                        console.log(`Failed to find block on attempt ${retry + 1}: ${errorMessage}`);
+                        // console.log(`Failed to find block on attempt ${retry + 1}: ${errorMessage}`); // Removed console.log
                         if (retry === maxRetries - 1)
                             throw error;
                     }
@@ -174,7 +174,7 @@ export class OutlineOperations {
                 if (isRetry)
                     throw error;
                 // Otherwise, try one more time with a clean slate
-                console.log(`Retrying block creation for "${content}" with fresh attempt`);
+                // 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);
             }
@@ -183,6 +183,50 @@ export class OutlineOperations {
         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) {
@@ -218,6 +262,9 @@ export class OutlineOperations {
         let result;
         try {
             // Validate level sequence
+            if (validOutline.length > 0 && validOutline[0].level !== 1) {
+                throw new McpError(ErrorCode.InvalidRequest, 'Invalid outline structure - the first item must be at level 1');
+            }
             let prevLevel = 0;
             for (const item of validOutline) {
                 // Level should not increase by more than 1 at a time
@@ -232,7 +279,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
@@ -240,13 +289,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');
             }
@@ -266,13 +318,32 @@ 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 findBlockWithRetry(targetParentUid, item.text);
+                if (foundUid) {
+                    const nestedBlock = await 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') {

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 } from '../../markdown-utils.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;
@@ -84,7 +95,7 @@ export class PageOperations {
             try {
                 // Convert content array to MarkdownNode format expected by convertToRoamActions
                 const nodes = content.map(block => ({
-                    content: block.text,
+                    content: convertToRoamMarkdown(block.text.replace(/^#+\s*/, '')),
                     level: block.level,
                     ...(block.heading && { heading_level: block.heading }),
                     children: []
@@ -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

@@ -50,7 +50,7 @@ export const toolSchemas = {
                 },
                 content: {
                     type: 'array',
-                    description: 'Initial content for the page as an array of blocks with explicit nesting levels',
+                    description: 'Initial content for the page as an array of blocks with explicit nesting levels. Note: While empty blocks (e.g., {"text": "", "level": 1}) can be used for visual spacing, they create empty entities in the database. Please use them sparingly and only for structural purposes, not for simple visual separation.',
                     items: {
                         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. 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. 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: {
@@ -94,7 +94,7 @@ export const toolSchemas = {
                 },
                 outline: {
                     type: 'array',
-                    description: 'Array of outline items with block text and explicit nesting level',
+                    description: 'Array of outline items with block text and explicit nesting level. Must be a valid hierarchy: the first item must be level 1, and subsequent levels cannot increase by more than 1 at a time (e.g., a level 3 cannot follow a level 1).',
                     items: {
                         type: 'object',
                         properties: {
@@ -104,7 +104,7 @@ export const toolSchemas = {
                             },
                             level: {
                                 type: 'integer',
-                                description: 'Indentation level (1-10, where 1 is top level)',
+                                description: 'Indentation level (1-10, where 1 is top level). Levels must be sequential and cannot be skipped (e.g., a level 3 item cannot directly follow a level 1 item).',
                                 minimum: 1,
                                 maximum: 10
                             },
@@ -155,7 +155,7 @@ export const toolSchemas = {
                 },
                 order: {
                     type: 'string',
-                    description: 'Optional: Where to add the content under the parent ("first" or "last")',
+                    description: 'Optional: Where to add the content undeIs this tr the parent ("first" or "last")',
                     enum: ['first', 'last'],
                     default: 'first'
                 }
@@ -322,6 +322,15 @@ export const toolSchemas = {
             required: ['start_date', 'type', 'scope']
         }
     },
+    roam_markdown_cheatsheet: {
+        name: 'roam_markdown_cheatsheet',
+        description: 'Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if CUSTOM_INSTRUCTIONS_PATH is set.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
     roam_remember: {
         name: 'roam_remember',
         description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
@@ -436,8 +445,11 @@ export const toolSchemas = {
                                         description: 'The UID of the parent block or page.'
                                     },
                                     "order": {
-                                        type: ['number', 'string'],
-                                        description: 'The position of the block under its parent (0 for top, "last" for bottom).'
+                                        oneOf: [
+                                            { type: 'integer', description: 'Zero-indexed position.' },
+                                            { type: 'string', enum: ['first', 'last'], description: 'Position keyword.' }
+                                        ],
+                                        description: 'The position of the block under its parent (e.g., 0, 1, 2) or a keyword ("first", "last").'
                                     }
                                 }
                             }
@@ -448,5 +460,25 @@ export const toolSchemas = {
             },
             required: ['actions']
         }
-    }
+    },
+    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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                block_uid: {
+                    type: 'string',
+                    description: 'The UID of the block to fetch.'
+                },
+                depth: {
+                    type: 'integer',
+                    description: 'Optional: The number of levels deep to fetch children. Defaults to 4.',
+                    minimum: 0,
+                    maximum: 10
+                }
+            },
+            required: ['block_uid']
+        },
+    },
 };

package/build/tools/tool-handlers.js

@@ -1,5 +1,9 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
 import { PageOperations } from './operations/pages.js';
 import { BlockOperations } from './operations/blocks.js';
+import { BlockRetrievalOperations } from './operations/block-retrieval.js'; // New import
 import { SearchOperations } from './operations/search/index.js';
 import { MemoryOperations } from './operations/memory.js';
 import { TodoOperations } from './operations/todos.js';
@@ -11,6 +15,7 @@ export class ToolHandlers {
         this.graph = graph;
         this.pageOps = new PageOperations(graph);
         this.blockOps = new BlockOperations(graph);
+        this.blockRetrievalOps = new BlockRetrievalOperations(graph); // Initialize new instance
         this.searchOps = new SearchOperations(graph);
         this.memoryOps = new MemoryOperations(graph);
         this.todoOps = new TodoOperations(graph);
@@ -28,6 +33,9 @@ export class ToolHandlers {
         return this.pageOps.fetchPageByTitle(title, format);
     }
     // Block Operations
+    async fetchBlockWithChildren(block_uid, depth) {
+        return this.blockRetrievalOps.fetchBlockWithChildren(block_uid, depth);
+    }
     // Search Operations
     async searchByStatus(status, page_title_uid, include, exclude) {
         return this.searchOps.searchByStatus(status, page_title_uid, include, exclude);
@@ -74,4 +82,21 @@ export class ToolHandlers {
     async processBatch(actions) {
         return this.batchOps.processBatch(actions);
     }
+    async getRoamMarkdownCheatsheet() {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const cheatsheetPath = path.join(__dirname, '../../Roam_Markdown_Cheatsheet.md');
+        let cheatsheetContent = fs.readFileSync(cheatsheetPath, 'utf-8');
+        const customInstructionsPath = process.env.CUSTOM_INSTRUCTIONS_PATH;
+        if (customInstructionsPath && fs.existsSync(customInstructionsPath)) {
+            try {
+                const customInstructionsContent = fs.readFileSync(customInstructionsPath, 'utf-8');
+                cheatsheetContent += `\n\n${customInstructionsContent}`;
+            }
+            catch (error) {
+                console.warn(`Could not read custom instructions file at ${customInstructionsPath}: ${error}`);
+            }
+        }
+        return cheatsheetContent;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.30.2",
+  "version": "0.32.4",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -28,10 +28,15 @@
     "build"
   ],
   "scripts": {
-    "build": "tsc && 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",
-    "start": "node build/index.js"
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run clean && npm run build",
+    "release:patch": "npm version patch && git push origin v$(node -p \"require('./package.json').version\")",
+    "release:minor": "npm version minor && git push origin v$(node -p \"require('./package.json').version\")",
+    "release:major": "npm version major && git push origin v$(node -p \"require('./package.json').version\")"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",