roam-research-mcp 0.25.0 → 0.25.3

package/build/server/roam-server.js

@@ -17,7 +17,7 @@ export class RoamServer {
         this.toolHandlers = new ToolHandlers(this.graph);
         this.server = new Server({
             name: 'roam-research',
-            version: '0.25.0',
+            version: '0.25.3',
         }, {
             capabilities: {
                 tools: {
@@ -81,8 +81,8 @@ export class RoamServer {
                         };
                     }
                     case 'roam_create_block': {
-                        const { content, page_uid, title } = request.params.arguments;
-                        const result = await this.toolHandlers.createBlock(content, page_uid, title);
+                        const { content, page_uid, title, heading } = request.params.arguments;
+                        const result = await this.toolHandlers.createBlock(content, page_uid, title, heading);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };

package/build/tools/operations/blocks.js

@@ -1,4 +1,4 @@
-import { q, createBlock as createRoamBlock, updateBlock as updateRoamBlock, batchActions, createPage } from '@roam-research/roam-api-sdk';
+import { q, updateBlock as updateRoamBlock, batchActions, createPage } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { parseMarkdown, convertToRoamActions, convertToRoamMarkdown } from '../../markdown-utils.js';
@@ -7,7 +7,7 @@ export class BlockOperations {
     constructor(graph) {
         this.graph = graph;
     }
-    async createBlock(content, page_uid, title) {
+    async createBlock(content, page_uid, title, heading) {
         // If page_uid provided, use it directly
         let targetPageUid = page_uid;
         // If no page_uid but title provided, search for page by title
@@ -68,9 +68,44 @@ export class BlockOperations {
         try {
             // If the content has multiple lines or is a table, use nested import
             if (content.includes('\n')) {
-                // Parse and import the nested content
-                const convertedContent = convertToRoamMarkdown(content);
-                const nodes = parseMarkdown(convertedContent);
+                let nodes;
+                // If heading parameter is provided, manually construct nodes to preserve heading
+                if (heading) {
+                    const lines = content.split('\n');
+                    const firstLine = lines[0].trim();
+                    const remainingLines = lines.slice(1);
+                    // Create the first node with heading formatting
+                    const firstNode = {
+                        content: firstLine,
+                        level: 0,
+                        heading_level: heading,
+                        children: []
+                    };
+                    // If there are remaining lines, parse them as children or siblings
+                    if (remainingLines.length > 0 && remainingLines.some(line => line.trim())) {
+                        const remainingContent = remainingLines.join('\n');
+                        const convertedRemainingContent = convertToRoamMarkdown(remainingContent);
+                        const remainingNodes = parseMarkdown(convertedRemainingContent);
+                        // Add remaining nodes as siblings to the first node
+                        nodes = [firstNode, ...remainingNodes];
+                    }
+                    else {
+                        nodes = [firstNode];
+                    }
+                }
+                else {
+                    // 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
                 const result = await batchActions(this.graph, {
@@ -88,27 +123,26 @@ export class BlockOperations {
                 };
             }
             else {
-                // For non-table content, create a simple block
-                await createRoamBlock(this.graph, {
-                    action: 'create-block',
-                    location: {
-                        "parent-uid": targetPageUid,
-                        "order": "last"
-                    },
-                    block: { string: content }
+                // For single block content, use the same convertToRoamActions approach that works in roam_create_page
+                const nodes = [{
+                        content: content,
+                        level: 0,
+                        ...(heading && typeof heading === 'number' && heading > 0 && { heading_level: heading }),
+                        children: []
+                    }];
+                if (!targetPageUid) {
+                    throw new McpError(ErrorCode.InternalError, 'targetPageUid is undefined');
+                }
+                const actions = convertToRoamActions(nodes, targetPageUid, 'last');
+                // Execute batch actions to create the block
+                const result = await batchActions(this.graph, {
+                    action: 'batch-actions',
+                    actions
                 });
-                // Get the block's UID
-                const findBlockQuery = `[:find ?uid
-                               :in $ ?parent ?string
-                               :where [?b :block/uid ?uid]
-                                     [?b :block/string ?string]
-                                     [?b :block/parents ?p]
-                                     [?p :block/uid ?parent]]`;
-                const blockResults = await q(this.graph, findBlockQuery, [targetPageUid, content]);
-                if (!blockResults || blockResults.length === 0) {
-                    throw new Error('Could not find created block');
+                if (!result) {
+                    throw new Error('Failed to create block');
                 }
-                const blockUid = blockResults[0][0];
+                const blockUid = result.created_uids?.[0];
                 return {
                     success: true,
                     block_uid: blockUid,

package/build/tools/operations/pages.js

@@ -87,6 +87,7 @@ export class PageOperations {
                 const nodes = content.map(block => ({
                     content: block.text,
                     level: block.level,
+                    ...(block.heading && { heading_level: block.heading }),
                     children: []
                 }));
                 // Create hierarchical structure based on levels
@@ -171,6 +172,21 @@ export class PageOperations {
         if (!blocks || blocks.length === 0) {
             return `${title} (no content found)`;
         }
+        // Get heading information for blocks that have it
+        const headingsQuery = `[:find ?block-uid ?heading
+                          :in $ % ?page-title
+                          :where [?page :node/title ?page-title]
+                                 [?block :block/uid ?block-uid]
+                                 [?block :block/heading ?heading]
+                                 (ancestor ?block ?page)]`;
+        const headings = await q(this.graph, headingsQuery, [ancestorRule, title]);
+        // Create a map of block UIDs to heading levels
+        const headingMap = new Map();
+        if (headings) {
+            for (const [blockUid, heading] of headings) {
+                headingMap.set(blockUid, heading);
+            }
+        }
         // Create a map of all blocks
         const blockMap = new Map();
         const rootBlocks = [];
@@ -181,6 +197,7 @@ export class PageOperations {
                 uid: blockUid,
                 string: resolvedString,
                 order: order,
+                heading: headingMap.get(blockUid) || null,
                 children: []
             };
             blockMap.set(blockUid, block);
@@ -213,7 +230,17 @@ export class PageOperations {
         const toMarkdown = (blocks, level = 0) => {
             return blocks.map(block => {
                 const indent = '  '.repeat(level);
-                let md = `${indent}- ${block.string}`;
+                let md;
+                // Check block heading level and format accordingly
+                if (block.heading && block.heading > 0) {
+                    // Format as heading with appropriate number of hashtags
+                    const hashtags = '#'.repeat(block.heading);
+                    md = `${indent}${hashtags} ${block.string}`;
+                }
+                else {
+                    // No heading, use bullet point (current behavior)
+                    md = `${indent}- ${block.string}`;
+                }
                 if (block.children.length > 0) {
                     md += '\n' + toMarkdown(block.children, level + 1);
                 }

package/build/tools/schemas.js

@@ -34,7 +34,7 @@ export const toolSchemas = {
     },
     roam_create_page: {
         name: 'roam_create_page',
-        description: 'Create a new standalone page in Roam with optional content using explicit nesting levels. 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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -57,6 +57,12 @@ export const toolSchemas = {
                                 description: 'Indentation level (1-10, where 1 is top level)',
                                 minimum: 1,
                                 maximum: 10
+                            },
+                            heading: {
+                                type: 'integer',
+                                description: 'Optional: Heading formatting for this block (1-3)',
+                                minimum: 1,
+                                maximum: 3
                             }
                         },
                         required: ['text', 'level']
@@ -68,7 +74,7 @@ export const toolSchemas = {
     },
     roam_create_block: {
         name: 'roam_create_block',
-        description: 'Add a new block to an existing Roam page. If no page specified, adds to today\'s daily note. Best for capturing immediate thoughts, additions to discussions, or content that doesn\'t warrant its own page. Can specify page by title or UID.\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 new block to an existing Roam page. If no page specified, adds to today\'s daily note. Best for capturing immediate thoughts, additions to discussions, or content that doesn\'t warrant its own page. Can specify page by title or UID.\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).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -84,6 +90,12 @@ export const toolSchemas = {
                     type: 'string',
                     description: 'Optional: Title of the page to add block to (defaults to today\'s date if neither page_uid nor title provided)',
                 },
+                heading: {
+                    type: 'integer',
+                    description: 'Optional: Heading formatting for this block (1-3)',
+                    minimum: 1,
+                    maximum: 3
+                }
             },
             required: ['content'],
         },

package/build/tools/tool-handlers.js

@@ -33,8 +33,8 @@ export class ToolHandlers {
         return this.pageOps.fetchPageByTitle(title);
     }
     // Block Operations
-    async createBlock(content, page_uid, title) {
-        return this.blockOps.createBlock(content, page_uid, title);
+    async createBlock(content, page_uid, title, heading) {
+        return this.blockOps.createBlock(content, page_uid, title, heading);
     }
     async updateBlock(block_uid, content, transform) {
         return this.blockOps.updateBlock(block_uid, content, transform);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.25.0",
+  "version": "0.25.3",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {