roam-research-mcp 0.25.3 → 0.25.5

package/build/markdown-utils.js

@@ -176,39 +176,23 @@ function parseMarkdown(markdown) {
         // Calculate indentation level (2 spaces = 1 level)
         const indentation = line.match(/^\s*/)?.[0].length ?? 0;
         let level = Math.floor(indentation / 2);
-        // First check for headings
-        const { heading_level, content: headingContent } = parseMarkdownHeadingLevel(trimmedLine);
-        // Then handle bullet points if not a heading
-        let content;
-        if (heading_level > 0) {
-            content = headingContent; // Use clean heading content without # marks
-            level = 0; // Headings start at root level
-            stack.length = 1; // Reset stack but keep heading as parent
-            // Create heading node
-            const node = {
-                content,
-                level,
-                heading_level, // Store heading level in node
-                children: []
-            };
-            rootNodes.push(node);
-            stack[0] = node;
-            continue; // Skip to next line
-        }
-        // Handle non-heading content
+        let contentToParse;
         const bulletMatch = trimmedLine.match(/^(\s*)[-*+]\s+/);
         if (bulletMatch) {
-            // For bullet points, use the bullet's indentation for level
-            content = trimmedLine.substring(bulletMatch[0].length);
+            // If it's a bullet point, adjust level based on bullet indentation
             level = Math.floor(bulletMatch[1].length / 2);
+            contentToParse = trimmedLine.substring(bulletMatch[0].length); // Content after bullet
         }
         else {
-            content = trimmedLine;
+            contentToParse = trimmedLine; // No bullet, use trimmed line
         }
-        // Create regular node
+        // Now, from the content after bullet/initial indentation, check for heading
+        const { heading_level, content: finalContent } = parseMarkdownHeadingLevel(contentToParse);
+        // Create node
         const node = {
-            content,
-            level,
+            content: finalContent, // Use content after heading parsing
+            level, // Use level derived from bullet/indentation
+            ...(heading_level > 0 && { heading_level }),
             children: []
         };
         // Pop stack until we find the parent level

package/build/search/block-ref-search.js

@@ -3,7 +3,6 @@ import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
 import { resolveRefs } from '../tools/helpers/refs.js';
 export class BlockRefSearchHandler extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;

package/build/search/datomic-search.js

@@ -1,7 +1,6 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 export class DatomicSearchHandler extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;

package/build/search/hierarchy-search.js

@@ -3,7 +3,6 @@ import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
 import { resolveRefs } from '../tools/helpers/refs.js';
 export class HierarchySearchHandler extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;

package/build/search/status-search.js

@@ -3,7 +3,6 @@ import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
 import { resolveRefs } from '../tools/helpers/refs.js';
 export class StatusSearchHandler extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;

package/build/search/tag-search.js

@@ -3,7 +3,6 @@ import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
 import { resolveRefs } from '../tools/helpers/refs.js';
 export class TagSearchHandler extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;

package/build/search/text-search.js

@@ -3,7 +3,6 @@ import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
 import { resolveRefs } from '../tools/helpers/refs.js';
 export class TextSearchHandler extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;

package/build/search/types.js

@@ -1,6 +1,5 @@
 // Base class for all search handlers
 export class BaseSearchHandler {
-    graph;
     constructor(graph) {
         this.graph = graph;
     }

package/build/server/roam-server.js

@@ -6,9 +6,6 @@ import { API_TOKEN, GRAPH_NAME } from '../config/environment.js';
 import { toolSchemas } from '../tools/schemas.js';
 import { ToolHandlers } from '../tools/tool-handlers.js';
 export class RoamServer {
-    server;
-    toolHandlers;
-    graph;
     constructor() {
         this.graph = initializeGraph({
             token: API_TOKEN,
@@ -17,7 +14,7 @@ export class RoamServer {
         this.toolHandlers = new ToolHandlers(this.graph);
         this.server = new Server({
             name: 'roam-research',
-            version: '0.25.3',
+            version: '0.25.5',
         }, {
             capabilities: {
                 tools: {
@@ -67,8 +64,8 @@ export class RoamServer {
                         };
                     }
                     case 'roam_fetch_page_by_title': {
-                        const { title } = request.params.arguments;
-                        const content = await this.toolHandlers.fetchPageByTitle(title);
+                        const { title, format } = request.params.arguments;
+                        const content = await this.toolHandlers.fetchPageByTitle(title, format);
                         return {
                             content: [{ type: 'text', text: content }],
                         };

package/build/tools/operations/blocks.js

@@ -3,7 +3,6 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { parseMarkdown, convertToRoamActions, convertToRoamMarkdown } from '../../markdown-utils.js';
 export class BlockOperations {
-    graph;
     constructor(graph) {
         this.graph = graph;
     }

package/build/tools/operations/memory.js

@@ -4,8 +4,6 @@ import { formatRoamDate } from '../../utils/helpers.js';
 import { resolveRefs } from '../helpers/refs.js';
 import { SearchOperations } from './search/index.js';
 export class MemoryOperations {
-    graph;
-    searchOps;
     constructor(graph) {
         this.graph = graph;
         this.searchOps = new SearchOperations(graph);

package/build/tools/operations/outline.js

@@ -4,10 +4,24 @@ import { formatRoamDate } from '../../utils/helpers.js';
 import { capitalizeWords } from '../helpers/text.js';
 import { parseMarkdown, convertToRoamActions, convertToRoamMarkdown } from '../../markdown-utils.js';
 export class OutlineOperations {
-    graph;
     constructor(graph) {
         this.graph = graph;
     }
+    /**
+     * Creates an outline structure on a Roam Research page, optionally under a specific block.
+     *
+     * @param outline - An array of OutlineItem objects, each containing text and a level.
+     *                  Markdown heading syntax (#, ##, ###) in the text will be recognized
+     *                  and converted to Roam headings while preserving the outline's hierarchical
+     *                  structure based on indentation.
+     * @param page_title_uid - The title or UID of the page where the outline should be created.
+     *                         If not provided, today's daily page will be used.
+     * @param block_text_uid - Optional. The text content or UID of an existing block under which
+     *                         the outline should be inserted. If a text string is provided and
+     *                         no matching block is found, a new block with that text will be created
+     *                         on the page to serve as the parent. If a UID is provided and the block
+     *                         is not found, an error will be thrown.
+     */
     async createOutline(outline, page_title_uid, block_text_uid) {
         // Validate input
         if (!Array.isArray(outline) || outline.length === 0) {
@@ -210,6 +224,8 @@ export class OutlineOperations {
             const markdownContent = validOutline
                 .map(item => {
                 const indent = '  '.repeat(item.level - 1);
+                // If the item text starts with a markdown heading (e.g., #, ##, ###),
+                // treat it as a direct heading without adding a bullet or outline indentation.
                 return `${indent}- ${item.text?.trim()}`;
             })
                 .join('\n');

package/build/tools/operations/pages.js

@@ -4,7 +4,6 @@ import { capitalizeWords } from '../helpers/text.js';
 import { resolveRefs } from '../helpers/refs.js';
 import { convertToRoamActions } from '../../markdown-utils.js';
 export class PageOperations {
-    graph;
     constructor(graph) {
         this.graph = graph;
     }
@@ -38,7 +37,7 @@ export class PageOperations {
                 };
             }
             // Extract unique page titles
-            const uniquePages = [...new Set(results.map(([title]) => title))];
+            const uniquePages = Array.from(new Set(results.map(([title]) => title)));
             return {
                 success: true,
                 pages: uniquePages,
@@ -127,7 +126,7 @@ export class PageOperations {
         }
         return { success: true, uid: pageUid };
     }
-    async fetchPageByTitle(title) {
+    async fetchPageByTitle(title, format = 'raw') {
         if (!title) {
             throw new McpError(ErrorCode.InvalidRequest, 'title is required');
         }
@@ -170,6 +169,9 @@ export class PageOperations {
                                [?parent :block/uid ?parent-uid]]`;
         const blocks = await q(this.graph, blocksQuery, [ancestorRule, title]);
         if (!blocks || blocks.length === 0) {
+            if (format === 'raw') {
+                return [];
+            }
             return `${title} (no content found)`;
         }
         // Get heading information for blocks that have it
@@ -226,9 +228,13 @@ export class PageOperations {
             });
         };
         sortBlocks(rootBlocks);
+        if (format === 'raw') {
+            return JSON.stringify(rootBlocks);
+        }
         // Convert to markdown with proper nesting
         const toMarkdown = (blocks, level = 0) => {
-            return blocks.map(block => {
+            return blocks
+                .map(block => {
                 const indent = '  '.repeat(level);
                 let md;
                 // Check block heading level and format accordingly
@@ -245,7 +251,8 @@ export class PageOperations {
                     md += '\n' + toMarkdown(block.children, level + 1);
                 }
                 return md;
-            }).join('\n');
+            })
+                .join('\n');
         };
         return `# ${title}\n\n${toMarkdown(rootBlocks)}`;
     }

package/build/tools/operations/search/handlers.js

@@ -1,14 +1,12 @@
 import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler, DatomicSearchHandler, StatusSearchHandler } from '../../../search/index.js';
 // Base class for all search handlers
 export class BaseSearchHandler {
-    graph;
     constructor(graph) {
         this.graph = graph;
     }
 }
 // Tag search handler
 export class TagSearchHandlerImpl extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;
@@ -20,7 +18,6 @@ export class TagSearchHandlerImpl extends BaseSearchHandler {
 }
 // Block reference search handler
 export class BlockRefSearchHandlerImpl extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;
@@ -32,7 +29,6 @@ export class BlockRefSearchHandlerImpl extends BaseSearchHandler {
 }
 // Hierarchy search handler
 export class HierarchySearchHandlerImpl extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;
@@ -44,7 +40,6 @@ export class HierarchySearchHandlerImpl extends BaseSearchHandler {
 }
 // Text search handler
 export class TextSearchHandlerImpl extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;
@@ -56,7 +51,6 @@ export class TextSearchHandlerImpl extends BaseSearchHandler {
 }
 // Status search handler
 export class StatusSearchHandlerImpl extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;
@@ -68,7 +62,6 @@ export class StatusSearchHandlerImpl extends BaseSearchHandler {
 }
 // Datomic query handler
 export class DatomicSearchHandlerImpl extends BaseSearchHandler {
-    params;
     constructor(graph, params) {
         super(graph);
         this.params = params;

package/build/tools/operations/search/index.js

@@ -1,6 +1,5 @@
 import { TagSearchHandlerImpl, BlockRefSearchHandlerImpl, HierarchySearchHandlerImpl, TextSearchHandlerImpl, StatusSearchHandlerImpl } from './handlers.js';
 export class SearchOperations {
-    graph;
     constructor(graph) {
         this.graph = graph;
     }

package/build/tools/operations/todos.js

@@ -2,7 +2,6 @@ import { q, createBlock, createPage, batchActions } from '@roam-research/roam-ap
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 export class TodoOperations {
-    graph;
     constructor(graph) {
         this.graph = graph;
     }

package/build/tools/schemas.js

@@ -19,18 +19,21 @@ export const toolSchemas = {
         },
     },
     roam_fetch_page_by_title: {
-        name: 'roam_fetch_page_by_title',
-        description: 'Retrieve complete page contents by exact title, including all nested blocks and resolved block references. Use for accessing daily pages, reading and analyzing existing Roam pages.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                title: {
-                    type: 'string',
-                    description: 'Title of the page. For date pages, use ordinal date formats such as January 2nd, 2025',
-                },
+        description: 'Fetch page by title, defaults to raw JSON string.',
+        type: 'object',
+        properties: {
+            title: {
+                type: 'string',
+                description: 'Title of the page. For date pages, use ordinal date formats such as January 2nd, 2025'
             },
-            required: ['title'],
+            format: {
+                type: 'string',
+                enum: ['markdown', 'raw'],
+                default: 'raw',
+                description: "Format output as markdown or JSON. 'markdown' returns as string; 'raw' returns JSON string of the page's blocks"
+            }
         },
+        required: ['title']
     },
     roam_create_page: {
         name: 'roam_create_page',
@@ -112,7 +115,7 @@ export const toolSchemas = {
                 },
                 block_text_uid: {
                     type: 'string',
-                    description: 'A relevant title heading for the outline (or UID, if known) of the block under which outline content will be nested. If blank, content will be nested under the page title.'
+                    description: 'A relevant title heading for the outline (or UID, if known) of the block under which outline content will be nested. If blank, content will be nested directly under the page. This can be either the text content of the block or its UID.'
                 },
                 outline: {
                     type: 'array',
@@ -129,6 +132,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']
@@ -410,7 +419,7 @@ export const toolSchemas = {
                 scope: {
                     type: 'string',
                     enum: ['blocks', 'pages', 'both'],
-                    description: 'Whether to search blocks, pages, or both',
+                    description: 'Whether to search blocks, pages',
                 },
                 include_content: {
                     type: 'boolean',

package/build/tools/tool-handlers.js

@@ -6,13 +6,6 @@ import { TodoOperations } from './operations/todos.js';
 import { OutlineOperations } from './operations/outline.js';
 import { DatomicSearchHandlerImpl } from './operations/search/handlers.js';
 export class ToolHandlers {
-    graph;
-    pageOps;
-    blockOps;
-    searchOps;
-    memoryOps;
-    todoOps;
-    outlineOps;
     constructor(graph) {
         this.graph = graph;
         this.pageOps = new PageOperations(graph);
@@ -29,8 +22,8 @@ export class ToolHandlers {
     async createPage(title, content) {
         return this.pageOps.createPage(title, content);
     }
-    async fetchPageByTitle(title) {
-        return this.pageOps.fetchPageByTitle(title);
+    async fetchPageByTitle(title, format) {
+        return this.pageOps.fetchPageByTitle(title, format);
     }
     // Block Operations
     async createBlock(content, page_uid, title, heading) {

package/package.json

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