roam-research-mcp 2.4.0 → 2.4.3

package/build/cli/commands/update.js

@@ -1,8 +1,10 @@
 import { Command } from 'commander';
 import { BatchOperations } from '../../tools/operations/batch.js';
+import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
 import { parseMarkdownHeadingLevel } from '../../markdown-utils.js';
 import { printDebug, exitWithError } from '../utils/output.js';
 import { resolveGraph } from '../utils/graph.js';
+import { readStdin } from '../utils/input.js';
 // Patterns for TODO/DONE markers (both {{TODO}} and {{[[TODO]]}} formats)
 const TODO_PATTERN = /\{\{(\[\[)?TODO(\]\])?\}\}\s*/g;
 const DONE_PATTERN = /\{\{(\[\[)?DONE(\]\])?\}\}\s*/g;
@@ -43,7 +45,7 @@ export function createUpdateCommand() {
     return new Command('update')
         .description('Update block content, heading, open/closed state, or TODO/DONE status')
         .argument('<uid>', 'Block UID to update (accepts ((uid)) wrapper)')
-        .argument('<content>', 'New content. Use # prefix for heading: "# Title" sets H1')
+        .argument('[content]', 'New content. Use # prefix for heading: "# Title" sets H1. Reads from stdin if "-" or omitted (when piped).')
         .option('-H, --heading <level>', 'Set heading level (1-3), or 0 to remove')
         .option('-o, --open', 'Expand block (show children)')
         .option('-c, --closed', 'Collapse block (hide children)')
@@ -72,30 +74,82 @@ Examples:
   roam update abc123def "Task" -T             # Set as TODO
   roam update abc123def "Task" -D             # Mark as DONE
   roam update abc123def "Task" --clear-status # Remove status marker
+
+  # Stdin / Partial Updates
+  echo "New text" | roam update abc123def     # Pipe content
+  roam update abc123def -T                    # Add TODO (fetches existing text)
+  roam update abc123def -o                    # Expand block (keeps text)
 `)
         .action(async (uid, content, options) => {
         try {
             // Strip (( )) wrapper if present
             const blockUid = uid.replace(/^\(\(|\)\)$/g, '');
-            // Detect heading from content unless explicitly set
-            let finalContent = content;
+            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();
+            }
+            // 2. Identify if we need to fetch existing content
+            const isStatusUpdate = options.todo || options.done || options.clearStatus;
+            const isHeadingUpdate = options.heading !== undefined;
+            const isStateUpdate = options.open || options.closed;
+            if (finalContent === undefined) {
+                if (isStatusUpdate) {
+                    // Must fetch to apply status safely
+                    const blockRetrieval = new BlockRetrievalOperations(graph);
+                    const block = await blockRetrieval.fetchBlockWithChildren(blockUid, 0);
+                    if (!block) {
+                        exitWithError(`Block ${blockUid} not found`);
+                    }
+                    finalContent = block.string;
+                }
+                else if (!isHeadingUpdate && !isStateUpdate) {
+                    exitWithError('No content or update options provided.');
+                }
+            }
+            // 3. Process content if we have it
             let headingLevel;
-            if (options.heading !== undefined) {
-                // Explicit heading option takes precedence
-                const level = parseInt(options.heading, 10);
-                if (level >= 0 && level <= 3) {
-                    headingLevel = level === 0 ? undefined : level;
-                    // Still strip # prefix if present for consistency
-                    const { content: stripped } = parseMarkdownHeadingLevel(content);
-                    finalContent = stripped;
+            if (finalContent !== undefined) {
+                // Handle explicit heading option
+                if (options.heading !== undefined) {
+                    const level = parseInt(options.heading, 10);
+                    if (level >= 0 && level <= 3) {
+                        headingLevel = level === 0 ? undefined : level;
+                        const { content: stripped } = parseMarkdownHeadingLevel(finalContent);
+                        finalContent = stripped;
+                    }
+                }
+                else {
+                    // Auto-detect heading from content
+                    const { heading_level, content: stripped } = parseMarkdownHeadingLevel(finalContent);
+                    if (heading_level > 0) {
+                        headingLevel = heading_level;
+                        finalContent = stripped;
+                    }
+                }
+                // Handle TODO/DONE status
+                if (options.clearStatus) {
+                    finalContent = clearStatus(finalContent);
+                }
+                else if (options.todo) {
+                    finalContent = applyStatus(finalContent, 'TODO');
+                }
+                else if (options.done) {
+                    finalContent = applyStatus(finalContent, 'DONE');
                 }
             }
             else {
-                // Auto-detect heading from content
-                const { heading_level, content: stripped } = parseMarkdownHeadingLevel(content);
-                if (heading_level > 0) {
-                    headingLevel = heading_level;
-                    finalContent = stripped;
+                // No content update, just metadata
+                if (options.heading !== undefined) {
+                    const level = parseInt(options.heading, 10);
+                    if (level >= 0 && level <= 3) {
+                        headingLevel = level === 0 ? undefined : level;
+                    }
                 }
             }
             // Handle open/closed state
@@ -106,25 +160,14 @@ Examples:
             else if (options.closed) {
                 openState = false;
             }
-            // Handle TODO/DONE status
-            if (options.clearStatus) {
-                finalContent = clearStatus(finalContent);
-            }
-            else if (options.todo) {
-                finalContent = applyStatus(finalContent, 'TODO');
-            }
-            else if (options.done) {
-                finalContent = applyStatus(finalContent, 'DONE');
-            }
             if (options.debug) {
                 printDebug('Block UID', blockUid);
                 printDebug('Graph', options.graph || 'default');
-                printDebug('Content', finalContent);
+                printDebug('Content', finalContent !== undefined ? finalContent : '(no change)');
                 printDebug('Heading level', headingLevel ?? 'none');
                 printDebug('Open state', openState ?? 'unchanged');
                 printDebug('Status', options.todo ? 'TODO' : options.done ? 'DONE' : options.clearStatus ? 'cleared' : 'unchanged');
             }
-            const graph = resolveGraph(options, true); // This is a write operation
             const batchOps = new BatchOperations(graph);
             const result = await batchOps.processBatch([{
                     action: 'update-block',

package/build/cli/utils/input.js

@@ -0,0 +1,10 @@
+/**
+ * Read all input from stdin
+ */
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}

package/build/server/roam-server.js

@@ -120,8 +120,8 @@ export class RoamServer {
                         };
                     }
                     case 'roam_remember': {
-                        const { memory, categories, heading, parent_uid } = cleanedArgs;
-                        const result = await toolHandlers.remember(memory, categories, heading, parent_uid);
+                        const { memory, categories, heading, parent_uid, include_memories_tag } = cleanedArgs;
+                        const result = await toolHandlers.remember(memory, categories, heading, parent_uid, include_memories_tag);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };

package/build/tools/operations/memory.js

@@ -10,7 +10,7 @@ export class MemoryOperations {
         this.graph = graph;
         this.searchOps = new SearchOperations(graph);
     }
-    async remember(memory, categories, heading, parent_uid) {
+    async remember(memory, categories, heading, parent_uid, include_memories_tag = true) {
         // Get today's date
         const today = new Date();
         const dateStr = formatRoamDate(today);
@@ -91,17 +91,21 @@ export class MemoryOperations {
             targetParentUid = pageUid;
         }
         // Get memories tag from environment
-        const memoriesTag = process.env.MEMORIES_TAG;
-        if (!memoriesTag) {
-            throw new McpError(ErrorCode.InternalError, 'MEMORIES_TAG environment variable not set');
+        let memoriesTag;
+        if (include_memories_tag) {
+            memoriesTag = process.env.MEMORIES_TAG;
+            if (!memoriesTag) {
+                throw new McpError(ErrorCode.InternalError, 'MEMORIES_TAG environment variable not set');
+            }
         }
         // Format categories as Roam tags if provided
         const categoryTags = categories?.map(cat => {
             // Handle multi-word categories
             return cat.includes(' ') ? `#[[${cat}]]` : `#${cat}`;
-        }).join(' ') || '';
+        }) ?? [];
         // Create block with memory, then all tags together at the end
-        const blockContent = `${memory} ${categoryTags} ${memoriesTag}`.trim();
+        const tags = memoriesTag ? [...categoryTags, memoriesTag] : categoryTags;
+        const blockContent = [memory, ...tags].join(' ').trim();
         // Pre-generate UID so we can return it
         const blockUid = generateBlockUid();
         const actions = [{

package/build/tools/schemas.js

@@ -431,20 +431,20 @@ export const toolSchemas = {
     },
     roam_remember: {
         name: 'roam_remember',
-        description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories (unless include_memories_tag is false). \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: withMultiGraphParams({
                 memory: {
                     type: 'string',
-                    description: 'The memory detail or information to remember'
+                    description: 'The memory detail or information to remember. Add tags in `categories`.'
                 },
                 categories: {
                     type: 'array',
                     items: {
                         type: 'string'
                     },
-                    description: 'Optional categories to tag the memory with (will be converted to Roam tags)'
+                    description: 'Optional categories to tag the memory with (will be converted to Roam tags). Do not duplicate tags added in `memory` parameter.'
                 },
                 heading: {
                     type: 'string',
@@ -453,6 +453,11 @@ export const toolSchemas = {
                 parent_uid: {
                     type: 'string',
                     description: 'Optional UID of a specific block to nest the memory under. Takes precedence over heading parameter.'
+                },
+                include_memories_tag: {
+                    type: 'boolean',
+                    description: 'Whether to append the MEMORIES_TAG tag to the memory block.',
+                    default: true
                 }
             }),
             required: ['memory']

package/build/tools/tool-handlers.js

@@ -67,8 +67,8 @@ export class ToolHandlers {
         return handler.execute();
     }
     // Memory Operations
-    async remember(memory, categories, heading, parent_uid) {
-        return this.memoryOps.remember(memory, categories, heading, parent_uid);
+    async remember(memory, categories, heading, parent_uid, include_memories_tag) {
+        return this.memoryOps.remember(memory, categories, heading, parent_uid, include_memories_tag);
     }
     async recall(sort_by = 'newest', filter_tag) {
         return this.memoryOps.recall(sort_by, filter_tag);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "2.4.0",
+  "version": "2.4.3",
   "description": "MCP server and CLI for Roam Research",
   "private": false,
   "repository": {