roam-research-mcp 0.30.2 → 0.32.0

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
 
@@ -105,21 +108,23 @@ The server provides powerful tools for interacting with Roam Research:
 - Enhanced documentation for Roam Tables in `Roam_Markdown_Cheatsheet.md` for clearer guidance on nesting.
 
 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.
+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 +140,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 +214,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
@@ -258,6 +273,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,118 @@
+!!!! 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
+
+---
+
+⭐️📋 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

@@ -268,8 +268,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

@@ -218,6 +218,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

package/build/tools/operations/pages.js

@@ -2,7 +2,7 @@ import { q, createPage as createRoamPage, batchActions } from '@roam-research/ro
 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';
 export class PageOperations {
     constructor(graph) {
         this.graph = graph;
@@ -84,7 +84,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: []

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.0",
   "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 && cp Roam_Markdown_Cheatsheet.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",