roam-research-mcp 2.18.0 → 2.19.1

package/README.md

@@ -46,6 +46,12 @@ roam search --namespace "Convention"    # Finds all Convention/* pages
 # Fetch a page by title
 roam get "Roam Research"
 
+# Fetch daily pages using any date format (auto-normalized)
+roam get today                          # Today's daily page
+roam get 2026-03-21                     # ISO date → "March 21st, 2026"
+roam get "03/21/2026"                   # US date → "March 21st, 2026"
+roam get "March 21"                     # Named (assumes current year)
+
 # Fetch a block with ancestors (parent chain to page root)
 roam get abc123def -a              # Block + children + ancestors
 roam get abc123def -a -d 0         # Ancestors only, no children

package/build/Roam_Markdown_Cheatsheet.md

@@ -184,6 +184,12 @@ CREATING:
 ├─ Memory → roam_remember
 └─ Todos → roam_add_todo
 
+NESTING (roam_import_markdown): nests by BOTH indentation AND markdown heading
+level — content and deeper headings fold under their heading (## under #, ### under
+##). Use it for heading-structured docs. roam_create_page nests ONLY by explicit
+per-item `level` integers, so heading-structured markdown sent to create_page
+imports flat. Don't use `---` dividers; they become horizontal-rule blocks.
+
 SEARCHING:
 ├─ By tag → roam_search_for_tag
 ├─ By text → roam_search_by_text

package/build/cli/batch/resolver.js

@@ -45,6 +45,21 @@ export async function resolveDailyPageUid(graph) {
     const dailyTitle = getDailyPageTitle();
     return resolvePageUid(graph, dailyTitle);
 }
+/**
+ * Check if a string looks like a valid Roam UID (not a page title)
+ */
+export function isUidFormat(ref) {
+    // 9 alphanumeric characters (standard block UID)
+    if (/^[a-zA-Z0-9_-]{9}$/.test(ref))
+        return true;
+    // MM-DD-YYYY daily page UID
+    if (/^\d{2}-\d{2}-\d{4}$/.test(ref))
+        return true;
+    // Placeholder {{name}}
+    if (/^\{\{[^}]+\}\}$/.test(ref))
+        return true;
+    return false;
+}
 /**
  * Collect all unique page titles that need resolution from commands
  */
@@ -56,6 +71,13 @@ export function collectPageTitles(commands) {
         if ('page' in params && typeof params.page === 'string') {
             titles.add(params.page);
         }
+        // Commands that can have 'parent' param — if it looks like a page title, resolve it
+        if ('parent' in params && typeof params.parent === 'string') {
+            const parent = params.parent;
+            if (!isUidFormat(parent)) {
+                titles.add(parent);
+            }
+        }
         // Remember command can have heading that needs parent page resolution
         // But heading lookup is handled separately
         // Todo/remember without explicit page need daily page
@@ -126,8 +148,13 @@ export function resolveParentRef(ref, context) {
     if (context.pageUids.has(ref)) {
         return context.pageUids.get(ref);
     }
-    // Assume it's a direct UID
-    return ref;
+    // If it looks like a UID, return as-is
+    if (isUidFormat(ref)) {
+        return ref;
+    }
+    // Not a UID and not resolved — this is a page title that wasn't collected/resolved
+    // Return null so callers can handle it (should not happen if collectPageTitles is correct)
+    return null;
 }
 /**
  * Generate a placeholder UID for tracking

package/build/cli/batch/translator.js

@@ -39,7 +39,10 @@ export function translateCommand(command, context) {
 function getParentUid(params, context) {
     // Direct parent UID or placeholder
     if (params.parent) {
-        return resolveParentRef(params.parent, context) || params.parent;
+        const resolved = resolveParentRef(params.parent, context);
+        if (resolved)
+            return resolved;
+        throw new Error(`Parent "${params.parent}" could not be resolved to a UID. Page may not exist.`);
     }
     // Page UID
     if (params.pageUid) {

package/build/cli/commands/batch.js

@@ -227,7 +227,7 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                 return;
             }
             const graph = resolveGraph(options, true);
-            // Phase 1: Collect and resolve page titles
+            // Phase 1: Collect and resolve page titles (from 'page' AND 'parent' params)
             const context = createResolutionContext();
             const pageTitles = collectPageTitles(commands);
             if (pageTitles.size > 0) {
@@ -238,10 +238,25 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                 for (const [title, uid] of resolved) {
                     context.pageUids.set(title, uid);
                 }
-                // Check for unresolved pages
+                // Auto-create unresolved pages (e.g., parent: "Page Title" for a page that doesn't exist yet)
                 const unresolved = Array.from(pageTitles).filter(t => !context.pageUids.has(t));
                 if (unresolved.length > 0) {
-                    exitWithError(`Page(s) not found: ${unresolved.map(t => `"${t}"`).join(', ')}`);
+                    if (options.debug) {
+                        printDebug('Auto-creating pages', unresolved);
+                    }
+                    const pageOps = new PageOperations(graph);
+                    for (const title of unresolved) {
+                        const result = await pageOps.createPage(title);
+                        if (result.success && result.uid) {
+                            context.pageUids.set(title, result.uid);
+                            if (options.debug) {
+                                printDebug(`Auto-created "${title}"`, result.uid);
+                            }
+                        }
+                        else {
+                            exitWithError(`Failed to create page "${title}"`);
+                        }
+                    }
                 }
                 if (options.debug) {
                     printDebug('Resolved pages', Object.fromEntries(context.pageUids));

package/build/cli/commands/update.js

@@ -15,7 +15,7 @@ const ANY_STATUS_PATTERN = /\{\{(\[\[)?(TODO|DONE)(\]\])?\}\}\s*/g;
  * - If opposite status exists, replace it
  * - If no status exists, prepend
  */
-function applyStatus(content, status) {
+export function applyStatus(content, status) {
     const marker = `{{[[${status}]]}} `;
     const hasStatus = status === 'TODO'
         ? TODO_PATTERN.test(content)
@@ -38,9 +38,30 @@ function applyStatus(content, status) {
 /**
  * Remove any TODO/DONE status from content
  */
-function clearStatus(content) {
+export function clearStatus(content) {
     return content.replace(ANY_STATUS_PATTERN, '').trim();
 }
+/**
+ * Resolve the "new text" for an update from the positional content arg and stdin.
+ *
+ * Returns `undefined` when no real text was supplied — INCLUDING the case where
+ * stdin was readable but empty. A subprocess invoked without a stdin pipe (e.g.
+ * `Bun.spawn(['roam', 'update', uid, '--done'])`) has stdin = /dev/null: non-TTY,
+ * but empty. The caller treats `undefined` as "leave the existing block text and
+ * only apply metadata/status changes". Returning `''` here would make a status-only
+ * update erase the block (it would skip the fetch-existing-text path and prepend the
+ * marker to an empty string). See update.test.ts.
+ */
+export async function resolveUpdateContent(contentArg, readPipedStdin, stdinIsTTY) {
+    if (contentArg && contentArg !== '-') {
+        return contentArg;
+    }
+    if (contentArg === '-' || (!contentArg && !stdinIsTTY)) {
+        const piped = (await readPipedStdin()).trim();
+        return piped.length > 0 ? piped : undefined;
+    }
+    return undefined;
+}
 export function createUpdateCommand() {
     return new Command('update')
         .description('Update block content, heading, open/closed state, or TODO/DONE status')
@@ -85,15 +106,12 @@ Examples:
             // Strip (( )) wrapper if present
             const blockUid = uid.replace(/^\(\(|\)\)$/g, '');
             const graph = resolveGraph(options, true); // This is a write operation
-            let finalContent;
-            // 1. Determine new content from args or stdin
-            if (content && content !== '-') {
-                finalContent = content;
-            }
-            else if (content === '-' || (!content && !process.stdin.isTTY)) {
-                finalContent = await readStdin();
-                finalContent = finalContent.trim();
-            }
+            // 1. Determine new content from args or stdin.
+            //    Empty/whitespace stdin resolves to `undefined` (not ''), so a
+            //    status-only update like `roam update <uid> --done` from a subprocess
+            //    falls through to the fetch-existing-text path below instead of
+            //    erasing the block. See resolveUpdateContent + update.test.ts.
+            let finalContent = await resolveUpdateContent(content, readStdin, Boolean(process.stdin.isTTY));
             // 2. Identify if we need to fetch existing content
             const isStatusUpdate = options.todo || options.done || options.clearStatus;
             const isHeadingUpdate = options.heading !== undefined;

package/build/cli/commands/update.test.js

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { resolveUpdateContent, applyStatus, clearStatus } from './update.js';
+/**
+ * Regression: `roam update <uid> --done` (and --todo / --clear-status) invoked as a
+ * subprocess used to ERASE the block text, replacing it with a bare "{{[[DONE]]}} ".
+ *
+ * Cause: a subprocess has stdin = /dev/null, which is non-TTY but empty. The old
+ * code read stdin and stored the empty string as the new content. Because '' !== undefined,
+ * the "fetch existing block text" path was skipped, and applyStatus prepended the
+ * marker to an empty string. The fix maps empty stdin to `undefined`.
+ */
+describe('resolveUpdateContent — empty stdin must not become content', () => {
+    it('maps empty stdin (subprocess /dev/null) to undefined, not ""', async () => {
+        const result = await resolveUpdateContent(undefined, async () => '', false);
+        expect(result).toBeUndefined(); // undefined => caller fetches existing text; '' would erase the block
+    });
+    it('treats whitespace-only stdin as no content', async () => {
+        const result = await resolveUpdateContent(undefined, async () => '  \n\t ', false);
+        expect(result).toBeUndefined();
+    });
+    it('uses real piped stdin content when present', async () => {
+        const result = await resolveUpdateContent(undefined, async () => 'piped text', false);
+        expect(result).toBe('piped text');
+    });
+    it('prefers an explicit content argument over stdin', async () => {
+        const result = await resolveUpdateContent('explicit', async () => 'piped', false);
+        expect(result).toBe('explicit');
+    });
+    it('does not read stdin from an interactive TTY when no content arg given', async () => {
+        let read = false;
+        const result = await resolveUpdateContent(undefined, async () => { read = true; return 'x'; }, true);
+        expect(result).toBeUndefined();
+        expect(read).toBe(false);
+    });
+    it('reads stdin when content arg is the explicit "-" sentinel, even on a TTY', async () => {
+        const result = await resolveUpdateContent('-', async () => 'from dash', true);
+        expect(result).toBe('from dash');
+    });
+    it('explicit "-" with empty stdin still resolves to undefined (does not erase)', async () => {
+        const result = await resolveUpdateContent('-', async () => '', true);
+        expect(result).toBeUndefined();
+    });
+});
+describe('applyStatus — find-replace preserves block text', () => {
+    it('converts an existing {{[[TODO]]}} marker to DONE in place, keeping text', () => {
+        expect(applyStatus('{{[[TODO]]}} Buy milk', 'DONE')).toBe('{{[[DONE]]}} Buy milk');
+    });
+    it('supports the {{TODO}} (non-page-ref) marker form', () => {
+        expect(applyStatus('{{TODO}} Buy milk', 'DONE')).toBe('{{[[DONE]]}} Buy milk');
+    });
+    it('prepends DONE when no marker is present, keeping the text', () => {
+        expect(applyStatus('Buy milk', 'DONE')).toBe('{{[[DONE]]}} Buy milk');
+    });
+    it('is a no-op when the target status is already present', () => {
+        expect(applyStatus('{{[[DONE]]}} Buy milk', 'DONE')).toBe('{{[[DONE]]}} Buy milk');
+    });
+    it('converts DONE back to TODO in place', () => {
+        expect(applyStatus('{{[[DONE]]}} Buy milk', 'TODO')).toBe('{{[[TODO]]}} Buy milk');
+    });
+    it('documents the failure mode: empty content + DONE yields a bare marker — which is exactly why resolveUpdateContent must not pass ""', () => {
+        expect(applyStatus('', 'DONE')).toBe('{{[[DONE]]}} ');
+    });
+});
+describe('clearStatus', () => {
+    it('removes a TODO/DONE marker and trims, keeping the text', () => {
+        expect(clearStatus('{{[[DONE]]}} Buy milk')).toBe('Buy milk');
+        expect(clearStatus('{{TODO}} Buy milk')).toBe('Buy milk');
+    });
+});

package/build/markdown-utils.js

@@ -363,6 +363,40 @@ export function generateBlockUid() {
     }
     return uid;
 }
+/**
+ * Reorganise a parsed markdown node list into a "section tree" based on heading
+ * levels: each heading (e.g. ##) becomes a parent, and the blocks that follow it
+ * nest under it until a heading of equal-or-higher level closes the section;
+ * deeper headings (###) nest further. Blocks before the first heading — and
+ * inputs with no headings at all — are returned unchanged, so indentation-only
+ * markdown and intentional flat lists are unaffected.
+ *
+ * This fixes flush-left, heading-structured markdown (e.g. report skeletons)
+ * that would otherwise import as a flat list of root-level siblings, because
+ * neither indentation-based nesting nor explicit levels capture the document
+ * outline encoded in the heading syntax.
+ */
+function nestUnderHeadings(nodes) {
+    const result = [];
+    const stack = []; // currently-open heading nodes, shallow → deep
+    for (const original of nodes) {
+        // Recurse first so headings appearing inside indented structure nest too
+        const node = { ...original, children: nestUnderHeadings(original.children) };
+        const level = node.heading_level ?? 0;
+        if (level > 0) {
+            // A heading at the same or shallower level closes open equal/deeper sections
+            while (stack.length > 0 && (stack[stack.length - 1].heading_level ?? 0) >= level) {
+                stack.pop();
+            }
+        }
+        // Attach under the deepest open heading, or at root when no section is open
+        (stack.length > 0 ? stack[stack.length - 1].children : result).push(node);
+        if (level > 0) {
+            stack.push(node);
+        }
+    }
+    return result;
+}
 function convertNodesToBlocks(nodes) {
     return nodes.map(node => ({
         uid: generateBlockUid(),
@@ -372,9 +406,7 @@ function convertNodesToBlocks(nodes) {
         children: convertNodesToBlocks(node.children)
     }));
 }
-function convertToRoamActions(nodes, parentUid, order = 'last') {
-    // First convert nodes to blocks with UIDs
-    const blocks = convertNodesToBlocks(nodes);
+function buildActionsFromBlocks(blocks, parentUid, order = 'last') {
     const actions = [];
     // Helper function to recursively create actions
     function createBlockActions(blocks, parentUid, order) {
@@ -405,6 +437,20 @@ function convertToRoamActions(nodes, parentUid, order = 'last') {
     createBlockActions(blocks, parentUid, order);
     return actions;
 }
+function convertToRoamActions(nodes, parentUid, order = 'last') {
+    // First convert nodes to blocks with UIDs
+    return buildActionsFromBlocks(convertNodesToBlocks(nodes), parentUid, order);
+}
+/**
+ * Like convertToRoamActions, but also returns the minted block tree (with the
+ * same client-generated UIDs used in the actions). Lets callers report exactly
+ * what was created WITHOUT a post-write re-query — Roam's write API does not
+ * echo back transacted UIDs, and we already know them because we minted them.
+ */
+function convertToRoamActionsWithBlocks(nodes, parentUid, order = 'last') {
+    const blocks = convertNodesToBlocks(nodes);
+    return { actions: buildActionsFromBlocks(blocks, parentUid, order), blocks };
+}
 /**
  * Converts markdown nodes to Roam batch actions, grouped by nesting level.
  * This ensures parent blocks exist before child blocks are created.
@@ -449,4 +495,4 @@ function convertToRoamActionsStaged(nodes, parentUid, order = 'last') {
     return actionsByLevel;
 }
 // Export public functions and types
-export { parseMarkdown, convertToRoamActions, convertToRoamActionsStaged, hasMarkdownTable, convertAllTables, convertToRoamMarkdown, parseMarkdownHeadingLevel };
+export { parseMarkdown, nestUnderHeadings, convertToRoamActions, convertToRoamActionsWithBlocks, convertToRoamActionsStaged, hasMarkdownTable, convertAllTables, convertToRoamMarkdown, parseMarkdownHeadingLevel };

package/build/markdown-utils.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseMarkdown, convertToRoamActions } from './markdown-utils.js';
+import { parseMarkdown, convertToRoamActions, convertToRoamActionsWithBlocks, nestUnderHeadings } from './markdown-utils.js';
 describe('markdown-utils', () => {
     describe('parseMarkdown - numbered lists', () => {
         it('should detect numbered list items and strip prefixes', () => {
@@ -122,4 +122,114 @@ And this--too`;
             expect(parentAction.block['children-view-type']).toBe('numbered');
         });
     });
+    describe('convertToRoamActionsWithBlocks', () => {
+        it('returns a minted block tree whose UIDs match the create-block actions, across 3 nested levels', () => {
+            const markdown = `- Level 1 — Alpha
+  - Level 2 — Alpha.1
+    - Level 3 — Alpha.1.a
+    - Level 3 — Alpha.1.b
+  - Level 2 — Alpha.2
+    - Level 3 — Alpha.2.a
+- Level 1 — Beta
+  - Level 2 — Beta.1
+    - Level 3 — Beta.1.a`;
+            const nodes = parseMarkdown(markdown);
+            const { actions, blocks } = convertToRoamActionsWithBlocks(nodes, 'PARENT123', 'last');
+            // 9 source bullets → more than the old VERIFICATION_THRESHOLD of 5
+            expect(actions.length).toBe(9);
+            // Collect every UID from the returned block tree
+            const treeUids = new Set();
+            const walk = (bs) => bs.forEach(b => { treeUids.add(b.uid); walk(b.children); });
+            walk(blocks);
+            // The tree UIDs must be exactly the action UIDs (no re-query, same minted ids)
+            const actionUids = actions.map(a => a.block.uid);
+            expect(treeUids.size).toBe(actions.length);
+            actionUids.forEach(uid => expect(treeUids.has(uid)).toBe(true));
+            // Nesting is preserved end-to-end
+            expect(blocks).toHaveLength(2);
+            expect(blocks[0].content).toBe('Level 1 — Alpha');
+            expect(blocks[0].children).toHaveLength(2); // Alpha.1, Alpha.2
+            expect(blocks[0].children[0].children).toHaveLength(2); // Alpha.1.a, Alpha.1.b
+            expect(blocks[1].children[0].children).toHaveLength(1); // Beta.1.a
+        });
+    });
+    describe('nestUnderHeadings', () => {
+        const node = (content, heading_level = 0, children = []) => ({ content, level: 1, heading_level, children });
+        it('nests content and deeper headings under their section heading', () => {
+            const flat = [
+                node('Section A', 2),
+                node('Body of A'),
+                node('Sub A1', 3),
+                node('Body of A1'),
+                node('Section B', 2),
+                node('Body of B'),
+            ];
+            const nested = nestUnderHeadings(flat);
+            // Two H2 sections at root
+            expect(nested).toHaveLength(2);
+            expect(nested[0].content).toBe('Section A');
+            // Section A absorbs its body AND the deeper H3 section
+            expect(nested[0].children.map(c => c.content)).toEqual(['Body of A', 'Sub A1']);
+            const subA1 = nested[0].children[1];
+            expect(subA1.heading_level).toBe(3);
+            expect(subA1.children.map(c => c.content)).toEqual(['Body of A1']);
+            expect(nested[1].content).toBe('Section B');
+            expect(nested[1].children.map(c => c.content)).toEqual(['Body of B']);
+        });
+        it('keeps content before the first heading at root', () => {
+            const flat = [
+                node('Date:: [[May 30th, 2026]]'),
+                node('Section A', 2),
+                node('Body'),
+            ];
+            const nested = nestUnderHeadings(flat);
+            expect(nested.map(c => c.content)).toEqual(['Date:: [[May 30th, 2026]]', 'Section A']);
+            expect(nested[1].children.map(c => c.content)).toEqual(['Body']);
+        });
+        it('treats same-level headings as siblings, deeper levels as nested', () => {
+            const flat = [
+                node('H2 first', 2),
+                node('H2 second', 2),
+            ];
+            const nested = nestUnderHeadings(flat);
+            expect(nested.map(c => c.content)).toEqual(['H2 first', 'H2 second']);
+            expect(nested[0].children).toHaveLength(0);
+        });
+        it('leaves heading-free indented structure unchanged (backward compatible)', () => {
+            const original = [
+                node('Parent', 0, [node('Child', 0, [node('Grandchild')])]),
+            ];
+            const nested = nestUnderHeadings(original);
+            expect(nested).toHaveLength(1);
+            expect(nested[0].content).toBe('Parent');
+            expect(nested[0].children).toHaveLength(1);
+            expect(nested[0].children[0].children.map(c => c.content)).toEqual(['Grandchild']);
+        });
+        it('end-to-end: flush-left heading markdown parses + nests into a section tree (reproduces the pilot-page bug input)', () => {
+            const markdown = [
+                '## TL;DR',
+                'continue InjectionGate',
+                '## Telemetry rollup',
+                '### Day-by-day',
+                '2026-05-25 — 293 calls',
+                '### By caller',
+                'AutoWorkCreation',
+                '## Recommendation',
+                'continue all',
+            ].join('\n');
+            const nested = nestUnderHeadings(parseMarkdown(markdown));
+            // Top level is exactly the three H2 sections — not nine flat siblings
+            expect(nested.map(n => n.content)).toEqual(['TL;DR', 'Telemetry rollup', 'Recommendation']);
+            expect(nested.every(n => n.heading_level === 2)).toBe(true);
+            // TL;DR holds its body line
+            expect(nested[0].children.map(c => c.content)).toEqual(['continue InjectionGate']);
+            // Telemetry holds two H3 subsections, each nesting its own body line
+            const telemetry = nested[1];
+            expect(telemetry.children.map(c => c.content)).toEqual(['Day-by-day', 'By caller']);
+            expect(telemetry.children[0].children.map(c => c.content)).toEqual(['2026-05-25 — 293 calls']);
+            expect(telemetry.children[1].children.map(c => c.content)).toEqual(['AutoWorkCreation']);
+            // Recommendation holds its body
+            expect(nested[2].children.map(c => c.content)).toEqual(['continue all']);
+        });
+    });
 });

package/build/search/utils.js

@@ -1,16 +1,26 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { q } from '@roam-research/roam-api-sdk';
+import { normalizeToRoamDate } from '../utils/helpers.js';
 export class SearchUtils {
     /**
-     * Find a page by title or UID
+     * Find a page by title or UID.
+     * Automatically normalizes date-like strings to Roam format.
      */
     static async findPageByTitleOrUid(graph, titleOrUid) {
-        // Try to find page by title
+        // Try to find page by title (original input first)
         const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
         const findResults = await q(graph, findQuery, [titleOrUid]);
         if (findResults && findResults.length > 0) {
             return findResults[0][0];
         }
+        // If input looks like a date, try normalized Roam format
+        const roamDate = normalizeToRoamDate(titleOrUid);
+        if (roamDate && roamDate !== titleOrUid) {
+            const dateResults = await q(graph, findQuery, [roamDate]);
+            if (dateResults && dateResults.length > 0) {
+                return dateResults[0][0];
+            }
+        }
         // Try as UID
         const uidQuery = `[:find ?uid :where [?e :block/uid "${titleOrUid}"] [?e :block/uid ?uid]]`;
         const uidResults = await q(graph, uidQuery, []);

package/build/tools/helpers/page-resolution.js

@@ -3,7 +3,7 @@
  */
 import { q, createPage } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
-import { formatRoamDate } from '../../utils/helpers.js';
+import { formatRoamDate, normalizeToRoamDate } from '../../utils/helpers.js';
 import { pageUidCache } from '../../cache/page-uid-cache.js';
 import { capitalizeWords } from './text.js';
 /**
@@ -15,8 +15,11 @@ export async function getPageUid(graph, title) {
     if (!title) {
         return null;
     }
+    // If the title looks like a date, normalize to Roam format
+    const roamDate = normalizeToRoamDate(title);
     const variations = [
         title,
+        ...(roamDate && roamDate !== title ? [roamDate] : []),
         capitalizeWords(title),
         title.toLowerCase()
     ];
@@ -79,8 +82,11 @@ export async function getOrCreateTodayPage(graph) {
  */
 export async function findOrCreatePage(graph, titleOrUid, options = {}) {
     const { maxRetries = 3, delayMs = 500 } = options;
+    // If the input looks like a date, normalize to Roam format
+    const roamDate = normalizeToRoamDate(titleOrUid);
     const variations = [
         titleOrUid,
+        ...(roamDate && roamDate !== titleOrUid ? [roamDate] : []),
         capitalizeWords(titleOrUid),
         titleOrUid.toLowerCase()
     ];

package/build/tools/operations/outline.js

@@ -3,10 +3,24 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { findOrCreatePage, getPageUid, getOrCreateTodayPage } from '../helpers/page-resolution.js';
 import { executeBatch } from '../helpers/batch-utils.js';
-import { parseMarkdown, convertToRoamActions, convertToRoamMarkdown } from '../../markdown-utils.js';
+import { parseMarkdown, nestUnderHeadings, convertToRoamActions, convertToRoamActionsWithBlocks, convertToRoamMarkdown } from '../../markdown-utils.js';
 import { executeStagedBatch } from '../../shared/staged-batch.js';
 // Threshold for skipping child fetch during verification
 const VERIFICATION_THRESHOLD = 5;
+/**
+ * Map the client-minted block tree (from convertToRoamActionsWithBlocks) into
+ * the NestedBlock shape returned to callers. No API calls — the UIDs are the
+ * ones we generated and sent in the create-block actions.
+ */
+function blockInfoToNestedBlocks(blocks, level = 0) {
+    return blocks.map((block, index) => ({
+        uid: block.uid,
+        text: block.content,
+        level,
+        order: index,
+        children: block.children.length > 0 ? blockInfoToNestedBlocks(block.children, level + 1) : undefined
+    }));
+}
 export class OutlineOperations {
     constructor(graph) {
         this.graph = graph;
@@ -140,35 +154,6 @@ export class OutlineOperations {
         }
     }
     ;
-    /**
-     * Recursively fetches a nested structure of blocks under a given root block UID.
-     */
-    async fetchNestedStructure(rootUid) {
-        const query = `[:find ?child-uid ?child-string ?child-order
-                    :in $ ?parent-uid
-                    :where
-                      [?parent :block/uid ?parent-uid]
-                      [?parent :block/children ?child]
-                      [?child :block/uid ?child-uid]
-                      [?child :block/string ?child-string]
-                      [?child :block/order ?child-order]]`;
-        const directChildrenResult = await q(this.graph, query, [rootUid]);
-        if (directChildrenResult.length === 0) {
-            return [];
-        }
-        const nestedBlocks = [];
-        for (const [childUid, childString, childOrder] of directChildrenResult) {
-            const children = await this.fetchNestedStructure(childUid);
-            nestedBlocks.push({
-                uid: childUid,
-                text: childString,
-                level: 0, // Level is not easily determined here, so we set it to 0
-                children: children,
-                order: childOrder
-            });
-        }
-        return nestedBlocks.sort((a, b) => a.order - b.order);
-    }
     /**
      * Creates an outline structure on a Roam Research page, optionally under a specific block.
      *
@@ -383,31 +368,24 @@ export class OutlineOperations {
         // Always use parseMarkdown for content with multiple lines or any markdown formatting
         const isMultilined = content.includes('\n');
         if (isMultilined) {
-            // Parse markdown into hierarchical structure
+            // Parse markdown into hierarchical structure, then nest by heading level so
+            // flush-left, heading-structured markdown (e.g. report skeletons) imports as
+            // a proper outline instead of a flat list of root-level siblings.
             const convertedContent = convertToRoamMarkdown(content);
-            const nodes = parseMarkdown(convertedContent);
-            // Convert markdown nodes to batch actions
-            const actions = convertToRoamActions(nodes, targetParentUid, order);
+            const nodes = nestUnderHeadings(parseMarkdown(convertedContent));
+            // Convert markdown nodes to batch actions, keeping the minted block tree.
+            // Roam's write API does not echo back transacted UIDs, so we report the
+            // UIDs we generated client-side rather than issuing a fragile post-write
+            // re-query (which was also skipped entirely past VERIFICATION_THRESHOLD,
+            // leaving created_uids empty for larger imports).
+            const { actions, blocks } = convertToRoamActionsWithBlocks(nodes, targetParentUid, order);
             // Execute batch actions to add content
             await executeBatch(this.graph, actions, 'import nested markdown content');
-            // Skip nested structure fetch for large imports to reduce API calls
-            const skipNestedFetch = actions.length > VERIFICATION_THRESHOLD;
-            if (skipNestedFetch) {
-                // Large import: return success with block count, skip recursive queries
-                return {
-                    success: true,
-                    page_uid: targetPageUid,
-                    parent_uid: targetParentUid,
-                    created_uids: []
-                };
-            }
-            // Small import: get all nested UIDs under the parent (current behavior)
-            const createdUids = await this.fetchNestedStructure(targetParentUid);
             return {
                 success: true,
                 page_uid: targetPageUid,
                 parent_uid: targetParentUid,
-                created_uids: createdUids
+                created_uids: blockInfoToNestedBlocks(blocks)
             };
         }
         else {

package/build/utils/helpers.js

@@ -55,9 +55,142 @@ export function sanitizeTagName(tag) {
     cleaned = cleaned.replace(/^\[\[/, '').replace(/\]\]$/, '');
     return cleaned.trim();
 }
+const MONTHS_LONG = [
+    'January', 'February', 'March', 'April', 'May', 'June',
+    'July', 'August', 'September', 'October', 'November', 'December'
+];
+const MONTHS_SHORT = {
+    jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5,
+    jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11
+};
 /**
- * Resolve relative date keywords to Roam date format.
- * Returns the original string if not a recognized keyword.
+ * Attempt to parse a string as a date and return Roam format ("March 21st, 2026").
+ * Returns null if the string doesn't look like a date.
+ *
+ * Handles:
+ *   - ISO:           2026-03-21
+ *   - US slash/dash:  03/21/2026, 3/21/2026, 03-21-2026
+ *   - Named:          March 21, 2026 / Mar 21, 2026 / March 21 2026
+ *   - Named w/ ord:   March 21st, 2026 (already correct — returned as-is)
+ *   - No year:        March 21 / Mar 21 (assumes current year)
+ *   - EU day-first:   21 March 2026 / 21 Mar 2026 / 21-Mar-2026 / 21 March
+ *   - Roam UID style: MM-DD-YYYY (daily page UIDs, also caught by US dash)
+ */
+export function normalizeToRoamDate(input) {
+    const s = input.trim();
+    if (!s)
+        return null;
+    let month;
+    let day;
+    let year;
+    // Already in Roam format? (e.g., "March 21st, 2026")
+    const roamFmt = /^([A-Z][a-z]+)\s+(\d{1,2})(st|nd|rd|th),\s*(\d{4})$/;
+    const roamMatch = s.match(roamFmt);
+    if (roamMatch) {
+        const mi = MONTHS_LONG.indexOf(roamMatch[1]);
+        if (mi !== -1)
+            return s; // already correct
+    }
+    // ISO: 2026-03-21
+    const iso = /^(\d{4})-(\d{1,2})-(\d{1,2})$/;
+    const isoMatch = s.match(iso);
+    if (isoMatch) {
+        year = parseInt(isoMatch[1]);
+        month = parseInt(isoMatch[2]) - 1;
+        day = parseInt(isoMatch[3]);
+    }
+    // Numeric slash or dash: 03/21/2026, 14/03/2025, 03-21-2026
+    // If first number > 12, it can't be a month → unambiguously EU (DD/MM/YYYY)
+    // Otherwise assume US (MM/DD/YYYY)
+    if (month === undefined) {
+        const numeric = /^(\d{1,2})[/-](\d{1,2})[/-](\d{4})$/;
+        const numMatch = s.match(numeric);
+        if (numMatch) {
+            const a = parseInt(numMatch[1]);
+            const b = parseInt(numMatch[2]);
+            year = parseInt(numMatch[3]);
+            if (a > 12 && b <= 12) {
+                // Unambiguously EU: DD/MM/YYYY (first number can't be a month)
+                day = a;
+                month = b - 1;
+            }
+            else {
+                // US default: MM/DD/YYYY
+                month = a - 1;
+                day = b;
+            }
+        }
+    }
+    // Named month with day and year: "March 21, 2026" / "Mar 21 2026"
+    if (month === undefined) {
+        const named = /^([A-Za-z]+)\s+(\d{1,2})(?:st|nd|rd|th)?,?\s*(\d{4})$/;
+        const namedMatch = s.match(named);
+        if (namedMatch) {
+            const mi = MONTHS_SHORT[namedMatch[1].toLowerCase().slice(0, 3)];
+            if (mi !== undefined) {
+                month = mi;
+                day = parseInt(namedMatch[2]);
+                year = parseInt(namedMatch[3]);
+            }
+        }
+    }
+    // EU day-first with named month and year: "21 March 2026" / "21 Mar 2026" / "21-Mar-2026"
+    if (month === undefined) {
+        const eu = /^(\d{1,2})[\s-]([A-Za-z]+)[\s-](\d{4})$/;
+        const euMatch = s.match(eu);
+        if (euMatch) {
+            const mi = MONTHS_SHORT[euMatch[2].toLowerCase().slice(0, 3)];
+            if (mi !== undefined) {
+                day = parseInt(euMatch[1]);
+                month = mi;
+                year = parseInt(euMatch[3]);
+            }
+        }
+    }
+    // EU day-first with named month, no year: "21 March" / "21 Mar"
+    if (month === undefined) {
+        const euNoYear = /^(\d{1,2})[\s-]([A-Za-z]+)$/;
+        const euNoYearMatch = s.match(euNoYear);
+        if (euNoYearMatch) {
+            const mi = MONTHS_SHORT[euNoYearMatch[2].toLowerCase().slice(0, 3)];
+            if (mi !== undefined) {
+                day = parseInt(euNoYearMatch[1]);
+                month = mi;
+                year = new Date().getFullYear();
+            }
+        }
+    }
+    // Named month with day, no year: "March 21" / "Mar 21"
+    if (month === undefined) {
+        const noYear = /^([A-Za-z]+)\s+(\d{1,2})(?:st|nd|rd|th)?$/;
+        const noYearMatch = s.match(noYear);
+        if (noYearMatch) {
+            const mi = MONTHS_SHORT[noYearMatch[1].toLowerCase().slice(0, 3)];
+            if (mi !== undefined) {
+                month = mi;
+                day = parseInt(noYearMatch[2]);
+                year = new Date().getFullYear();
+            }
+        }
+    }
+    // Validate parsed values
+    if (month === undefined || day === undefined || year === undefined)
+        return null;
+    if (month < 0 || month > 11)
+        return null;
+    if (day < 1 || day > 31)
+        return null;
+    if (year < 1900 || year > 2100)
+        return null;
+    // Extra validation: ensure the date is real (e.g., Feb 30 is invalid)
+    const dateObj = new Date(year, month, day);
+    if (dateObj.getMonth() !== month || dateObj.getDate() !== day)
+        return null;
+    return `${MONTHS_LONG[month]} ${day}${getOrdinalSuffix(day)}, ${year}`;
+}
+/**
+ * Resolve relative date keywords and common date formats to Roam date format.
+ * Returns the original string if not a recognized date pattern.
  */
 export function resolveRelativeDate(input) {
     const lower = input.toLowerCase().trim();
@@ -74,6 +207,6 @@ export function resolveRelativeDate(input) {
             tomorrow.setDate(today.getDate() + 1);
             return formatRoamDate(tomorrow);
         default:
-            return input;
+            return normalizeToRoamDate(input) ?? input;
     }
 }

package/build/utils/helpers.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { sanitizeTagName } from './helpers.js';
+import { sanitizeTagName, normalizeToRoamDate, resolveRelativeDate, formatRoamDate } from './helpers.js';
 describe('sanitizeTagName', () => {
     it('passes through bare tag names unchanged', () => {
         expect(sanitizeTagName('Type/Procedural')).toBe('Type/Procedural');
@@ -24,3 +24,130 @@ describe('sanitizeTagName', () => {
         expect(sanitizeTagName('#Memories')).toBe('Memories');
     });
 });
+describe('normalizeToRoamDate', () => {
+    it('returns null for non-date strings', () => {
+        expect(normalizeToRoamDate('My Page Title')).toBeNull();
+        expect(normalizeToRoamDate('abc123def')).toBeNull();
+        expect(normalizeToRoamDate('')).toBeNull();
+        expect(normalizeToRoamDate('hello')).toBeNull();
+    });
+    it('passes through already-correct Roam dates', () => {
+        expect(normalizeToRoamDate('March 21st, 2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('January 1st, 2024')).toBe('January 1st, 2024');
+        expect(normalizeToRoamDate('December 25th, 2025')).toBe('December 25th, 2025');
+        expect(normalizeToRoamDate('February 2nd, 2026')).toBe('February 2nd, 2026');
+        expect(normalizeToRoamDate('March 3rd, 2026')).toBe('March 3rd, 2026');
+    });
+    it('normalizes ISO dates (YYYY-MM-DD)', () => {
+        expect(normalizeToRoamDate('2026-03-21')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('2026-01-01')).toBe('January 1st, 2026');
+        expect(normalizeToRoamDate('2025-12-25')).toBe('December 25th, 2025');
+        expect(normalizeToRoamDate('2026-02-02')).toBe('February 2nd, 2026');
+        expect(normalizeToRoamDate('2026-03-03')).toBe('March 3rd, 2026');
+        expect(normalizeToRoamDate('2026-11-11')).toBe('November 11th, 2026');
+        expect(normalizeToRoamDate('2026-04-12')).toBe('April 12th, 2026');
+        expect(normalizeToRoamDate('2026-04-13')).toBe('April 13th, 2026');
+    });
+    it('normalizes US slash dates (MM/DD/YYYY)', () => {
+        expect(normalizeToRoamDate('03/21/2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('3/21/2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('12/25/2025')).toBe('December 25th, 2025');
+        expect(normalizeToRoamDate('1/1/2024')).toBe('January 1st, 2024');
+    });
+    it('detects unambiguous EU numeric dates (DD/MM/YYYY where DD > 12)', () => {
+        expect(normalizeToRoamDate('14/03/2025')).toBe('March 14th, 2025');
+        expect(normalizeToRoamDate('21/01/2026')).toBe('January 21st, 2026');
+        expect(normalizeToRoamDate('25/12/2025')).toBe('December 25th, 2025');
+        expect(normalizeToRoamDate('31/01/2026')).toBe('January 31st, 2026');
+        expect(normalizeToRoamDate('13/06/2026')).toBe('June 13th, 2026');
+    });
+    it('treats ambiguous numeric dates as US (MM/DD/YYYY when both ≤ 12)', () => {
+        // 03/04/2026 is ambiguous — defaults to US: March 4th
+        expect(normalizeToRoamDate('03/04/2026')).toBe('March 4th, 2026');
+        expect(normalizeToRoamDate('01/02/2026')).toBe('January 2nd, 2026');
+    });
+    it('normalizes US dash dates (MM-DD-YYYY)', () => {
+        expect(normalizeToRoamDate('03-21-2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('01-25-2026')).toBe('January 25th, 2026');
+    });
+    it('normalizes named month dates without ordinal', () => {
+        expect(normalizeToRoamDate('March 21, 2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('January 1, 2024')).toBe('January 1st, 2024');
+        expect(normalizeToRoamDate('December 25 2025')).toBe('December 25th, 2025');
+    });
+    it('normalizes abbreviated month names', () => {
+        expect(normalizeToRoamDate('Mar 21, 2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('Jan 1, 2024')).toBe('January 1st, 2024');
+        expect(normalizeToRoamDate('Dec 25, 2025')).toBe('December 25th, 2025');
+    });
+    it('normalizes named month with day only (no year, assumes current year)', () => {
+        const year = new Date().getFullYear();
+        expect(normalizeToRoamDate('March 21')).toBe(`March 21st, ${year}`);
+        expect(normalizeToRoamDate('Jan 1')).toBe(`January 1st, ${year}`);
+        expect(normalizeToRoamDate('Dec 25')).toBe(`December 25th, ${year}`);
+    });
+    it('handles named dates with existing ordinal suffix', () => {
+        expect(normalizeToRoamDate('March 21st, 2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('January 2nd, 2026')).toBe('January 2nd, 2026');
+        expect(normalizeToRoamDate('April 3rd 2026')).toBe('April 3rd, 2026');
+    });
+    it('normalizes EU day-first dates with named month', () => {
+        expect(normalizeToRoamDate('21 March 2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('21 Mar 2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('1 January 2024')).toBe('January 1st, 2024');
+        expect(normalizeToRoamDate('25 Dec 2025')).toBe('December 25th, 2025');
+        expect(normalizeToRoamDate('21-Mar-2026')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('2-Feb-2026')).toBe('February 2nd, 2026');
+    });
+    it('normalizes EU day-first dates without year (assumes current year)', () => {
+        const year = new Date().getFullYear();
+        expect(normalizeToRoamDate('21 March')).toBe(`March 21st, ${year}`);
+        expect(normalizeToRoamDate('21 Mar')).toBe(`March 21st, ${year}`);
+        expect(normalizeToRoamDate('1 Jan')).toBe(`January 1st, ${year}`);
+        expect(normalizeToRoamDate('25-Dec')).toBe(`December 25th, ${year}`);
+    });
+    it('rejects invalid dates', () => {
+        expect(normalizeToRoamDate('2026-02-30')).toBeNull(); // Feb 30 doesn't exist
+        expect(normalizeToRoamDate('2026-13-01')).toBeNull(); // Month 13
+        expect(normalizeToRoamDate('2026-00-01')).toBeNull(); // Month 0
+        expect(normalizeToRoamDate('13/32/2026')).toBeNull(); // Invalid month/day
+    });
+    it('handles all ordinal suffixes correctly', () => {
+        expect(normalizeToRoamDate('2026-03-01')).toBe('March 1st, 2026');
+        expect(normalizeToRoamDate('2026-03-02')).toBe('March 2nd, 2026');
+        expect(normalizeToRoamDate('2026-03-03')).toBe('March 3rd, 2026');
+        expect(normalizeToRoamDate('2026-03-04')).toBe('March 4th, 2026');
+        expect(normalizeToRoamDate('2026-03-11')).toBe('March 11th, 2026');
+        expect(normalizeToRoamDate('2026-03-12')).toBe('March 12th, 2026');
+        expect(normalizeToRoamDate('2026-03-13')).toBe('March 13th, 2026');
+        expect(normalizeToRoamDate('2026-03-21')).toBe('March 21st, 2026');
+        expect(normalizeToRoamDate('2026-03-22')).toBe('March 22nd, 2026');
+        expect(normalizeToRoamDate('2026-03-23')).toBe('March 23rd, 2026');
+        expect(normalizeToRoamDate('2026-03-31')).toBe('March 31st, 2026');
+    });
+});
+describe('resolveRelativeDate', () => {
+    it('resolves "today" to current date in Roam format', () => {
+        expect(resolveRelativeDate('today')).toBe(formatRoamDate(new Date()));
+    });
+    it('resolves "yesterday"', () => {
+        const y = new Date();
+        y.setDate(y.getDate() - 1);
+        expect(resolveRelativeDate('yesterday')).toBe(formatRoamDate(y));
+    });
+    it('resolves "tomorrow"', () => {
+        const t = new Date();
+        t.setDate(t.getDate() + 1);
+        expect(resolveRelativeDate('tomorrow')).toBe(formatRoamDate(t));
+    });
+    it('normalizes ISO dates via fallback', () => {
+        expect(resolveRelativeDate('2026-03-21')).toBe('March 21st, 2026');
+    });
+    it('normalizes slash dates via fallback', () => {
+        expect(resolveRelativeDate('03/21/2026')).toBe('March 21st, 2026');
+    });
+    it('returns non-date strings unchanged', () => {
+        expect(resolveRelativeDate('My Page')).toBe('My Page');
+        expect(resolveRelativeDate('Recipes')).toBe('Recipes');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "2.18.0",
+  "version": "2.19.1",
   "description": "MCP server and CLI for Roam Research",
   "private": false,
   "repository": {
@@ -56,4 +56,4 @@
     "typescript": "^5.3.3",
     "vitest": "^3.2.4"
   }
-}
+}