roam-research-mcp 0.30.1 → 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
 
@@ -102,23 +105,26 @@ The server provides powerful tools for interacting with Roam Research:
 - Detailed debug logging
 - Efficient batch operations
 - Hierarchical outline creation
-
-1. `roam_fetch_page_by_title`: Fetch page content by title.
-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`. (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 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.
+- 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_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`:
@@ -127,7 +133,29 @@ The following tools have been deprecated as of `v.0.30.0` in favor of the more p
 - `roam_update_block`: Use `roam_process_batch_actions` with the `update-block` action.
 - `roam_update_multiple_blocks`: Use `roam_process_batch_actions` with multiple `update-block` actions.
 
-### Important Considerations for Tool Usage
+---
+
+### Tool Usage Guidelines and Best Practices
+
+**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.
+
+- **For Pages:** Use `roam_fetch_page_by_title` to retrieve a page's UID if you only have its title. Example: "Read the page titled 'Trip to Las Vegas'"
+- **For Blocks:** If you need to manipulate an existing block, first use search tools like `roam_search_by_text`, `roam_search_for_tag`, or `roam_fetch_page_by_title` (with raw format) to find the block and obtain its UID. If the block exists on a page that has already been read, then a search isn't necessary.
+
+**Case-Sensitivity:**
+Be aware that text-based inputs (e.g., page titles, block content for search) are generally case-sensitive in Roam. Always match the exact casing of the text as it appears in your graph.
+
+**Iterative Refinement and Verification:**
+For complex operations, especially those involving nested structures or multiple changes, it is often beneficial to break down the task into smaller, verifiable steps. After each significant tool call, consider fetching the affected content to verify the changes before proceeding.
+
+**Understanding Tool Nuances:**
+Familiarize yourself with the specific behaviors and limitations of each tool. For instance, `roam_create_outline` is best for sequential outlines, while `roam_process_batch_actions` offers granular control for complex structures like tables. Refer to the individual tool descriptions for detailed usage notes.
 
 When making changes to your Roam graph, precision in your requests is crucial for achieving desired outcomes.
 
@@ -141,119 +169,61 @@ Instead of:
 Prefer:
 `"parent_uid": "((some-unique-uid))"`
 
-**Migrating from Deprecated Tools:**
-The following examples demonstrate how to achieve the functionality of the deprecated tools using `roam_process_batch_actions`.
-
-**1. Replacing `roam_create_block`:**
-
-- **Old (Deprecated):**
-  ```json
-  {
-    "tool_name": "roam_create_block",
-    "arguments": {
-      "content": "New block content",
-      "page_uid": "((page-uid))"
-    }
-  }
-  ```
-- **New (Recommended):**
-  ```json
-  {
-    "tool_name": "roam_process_batch_actions",
-    "arguments": {
-      "actions": [
-        {
-          "action": "create-block",
-          "location": {
-            "parent-uid": "((page-uid))",
-            "order": "last"
-          },
-          "block": {
-            "string": "New block content"
-          }
-        }
-      ]
-    }
-  }
-  ```
-
-**2. Replacing `roam_update_block`:**
-
-- **Old (Deprecated):**
-  ```json
-  {
-    "tool_name": "roam_update_block",
-    "arguments": {
-      "block_uid": "((block-uid))",
-      "content": "Updated block content"
-    }
-  }
-  ```
-- **New (Recommended):**
-  ```json
-  {
-    "tool_name": "roam_process_batch_actions",
-    "arguments": {
-      "actions": [
-        {
-          "action": "update-block",
-          "uid": "((block-uid))",
-          "string": "Updated block content"
-        }
-      ]
-    }
-  }
-  ```
-
-**3. Replacing `roam_update_multiple_blocks`:**
-
-- **Old (Deprecated):**
-  ```json
-  {
-    "tool_name": "roam_update_multiple_blocks",
-    "arguments": {
-      "updates": [
-        {
-          "block_uid": "((block-uid-1))",
-          "content": "Content for block 1"
-        },
-        {
-          "block_uid": "((block-uid-2))",
-          "transform": {
-            "find": "old text",
-            "replace": "new text"
-          }
-        }
-      ]
-    }
-  }
-  ```
-- **New (Recommended):**
-  ```json
-  {
-    "tool_name": "roam_process_batch_actions",
-    "arguments": {
-      "actions": [
-        {
-          "action": "update-block",
-          "uid": "((block-uid-1))",
-          "string": "Content for block 1"
-        },
-        {
-          "action": "update-block",
-          "uid": "((block-uid-2))",
-          "string": "((block-content-with-new-text))"
-          // Note: Transformations (find/replace) must be handled by the client
-          // before sending the 'string' to roam_process_batch_actions.
-        }
-      ]
-    }
-  }
-  ```
-
 **Caveat Regarding Heading Formatting:**
 Please note that while the `roam_process_batch_actions` tool can set block headings (H1, H2, H3), directly **removing** an existing heading (i.e., reverting a heading block to a plain text block) through this tool is not currently supported by the Roam API. The `heading` attribute persists its value once set, and attempting to remove it by setting `heading` to `0`, `null`, or omitting the property will not unset the heading.
 
+---
+
+## Example Prompts
+
+Here are some examples of how to creatively use the Roam tool in an LLM to interact with your Roam graph, particularly leveraging `roam_process_batch_actions` for complex operations.
+
+### Example 1: Creating a Project Outline
+
+This prompt demonstrates creating a new page and populating it with a structured outline using a single `roam_process_batch_actions` call.
+
+```
+"Create a new Roam page titled 'Project Alpha Planning' and add the following outline:
+- Overview
+  - Goals
+  - Scope
+- Team Members
+  - John Doe
+  - Jane Smith
+- Tasks
+  - Task 1
+    - Subtask 1.1
+    - Subtask 1.2
+  - Task 2
+- Deadlines"
+```
+
+### Example 2: Updating Multiple To-Dos and Adding a New One
+
+This example shows how to mark existing to-do items as `DONE` and add a new one, all within a single batch.
+
+```
+"Mark 'Finish report' and 'Review presentation' as done on today's daily page, and add a new todo 'Prepare for meeting'."
+```
+
+### Example 3: Moving and Updating a Block
+
+This demonstrates moving a block from one location to another and simultaneously updating its content.
+
+```
+"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
 
 1. Create a [Roam Research API token](https://x.com/RoamResearch/status/1789358175474327881):
@@ -303,6 +273,9 @@ Please note that while the `roam_process_batch_actions` tool can set block headi
    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
@@ -333,6 +306,8 @@ Each error response includes:
 - Detailed error message
 - Suggestions for resolution when applicable
 
+---
+
 ## Development
 
 ### Building

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

@@ -21,7 +21,7 @@ function convertTableToRoamFormat(text) {
         .replace(/^\||\|$/g, '')
         .split('|')
         .map(cell => cell.trim()));
-    let roamTable = '{{table}}\n';
+    let roamTable = '{{[[table]]}}\n';
     // First row becomes column headers
     const headers = rows[0];
     for (let i = 0; i < headers.length; i++) {
@@ -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, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.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,6 +20,7 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 const serverVersion = packageJson.version;
 export class RoamServer {
     constructor() {
+        // console.log('RoamServer: Constructor started.');
         try {
             this.graph = initializeGraph({
                 token: API_TOKEN,
@@ -41,6 +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.');
     }
     // Refactored to accept a Server instance
     setupRequestHandlers(mcpServer) {
@@ -48,10 +50,25 @@ export class RoamServer {
         mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: Object.values(toolSchemas),
         }));
+        // List available resources
+        mcpServer.setRequestHandler(ListResourcesRequestSchema, async () => {
+            const resources = []; // No resources, as cheatsheet is now a tool
+            return { resources };
+        });
+        // Access resource - no resources handled directly here anymore
+        mcpServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            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);
@@ -168,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}`);
                 }
@@ -182,41 +206,65 @@ export class RoamServer {
         });
     }
     async run() {
+        // console.log('RoamServer: run() method started.');
         try {
+            // 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...');
             this.setupRequestHandlers(stdioMcpServer);
+            // 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...');
             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...');
             this.setupRequestHandlers(httpMcpServer);
+            // 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.');
             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' }));
@@ -225,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

@@ -2,7 +2,7 @@
 export const toolSchemas = {
     roam_add_todo: {
         name: 'roam_add_todo',
-        description: 'Add a list of todo items as individual blocks to today\'s daily page in Roam. Each item becomes its own actionable block with todo status.\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).',
+        description: 'Add a list of todo items as individual blocks to today\'s daily page in Roam. Each item becomes its own actionable block with todo status.\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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -20,7 +20,7 @@ export const toolSchemas = {
     },
     roam_fetch_page_by_title: {
         name: 'roam_fetch_page_by_title',
-        description: 'Fetch page by title, defaults to raw JSON string.',
+        description: 'Fetch page by title. Returns content in the specified format.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -40,7 +40,7 @@ export const toolSchemas = {
     },
     roam_create_page: {
         name: 'roam_create_page',
-        description: 'Create new standalone page in Roam with optional content using explicit nesting levels and headings (H1-H3). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.',
+        description: 'Create new standalone page in Roam with optional content using explicit nesting levels and headings (H1-H3). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -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',
+        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: {
@@ -90,11 +90,11 @@ export const toolSchemas = {
                 },
                 block_text_uid: {
                     type: 'string',
-                    description: 'The text content or UID of the block to nest the outline under (UID is preferred for accuracy). If blank, content is nested directly under the page.'
+                    description: 'The text content or UID of the block to nest the outline under (UID is preferred for accuracy). If blank, content is nested directly under the page (or the default daily page if page_title_uid is also blank).'
                 },
                 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
                             },
@@ -129,7 +129,7 @@ export const toolSchemas = {
     },
     roam_import_markdown: {
         name: 'roam_import_markdown',
-        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.',
+        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -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,9 +322,18 @@ 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).',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -364,7 +373,7 @@ export const toolSchemas = {
     },
     roam_datomic_query: {
         name: 'roam_datomic_query',
-        description: 'Execute a custom Datomic query on the Roam graph beyond the available search tools. This provides direct access to Roam\'s query engine for advanced data retrieval. Note: Roam graph is case-sensitive.\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
+        description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. Note: Roam graph is case-sensitive.\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -385,7 +394,7 @@ export const toolSchemas = {
     },
     roam_process_batch_actions: {
         name: 'roam_process_batch_actions',
-        description: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order. For creating nested blocks, you can use a temporary client-side UID in a parent block and refer to it in a child block within the same batch. For actions on existing blocks, a valid block UID is required.',
+        description: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order. For creating nested blocks, you can use a temporary client-side UID in a parent block and refer to it in a child block within the same batch. For actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with `((UID))` syntax, is supported within the `string` property for `create-block` and `update-block` actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like `roam_fetch_page_by_title` or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, `roam_create_outline` is often more suitable.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -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.1",
+  "version": "0.32.0",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -28,13 +28,18 @@
     "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.0.0",
+    "@modelcontextprotocol/sdk": "^1.13.2",
     "@roam-research/roam-api-sdk": "^0.10.0",
     "dotenv": "^16.4.7"
   },