roam-research-mcp 1.0.0 → 1.4.0

package/build/shared/validation.js

@@ -0,0 +1,268 @@
+/**
+ * Shared validation functions for Roam MCP tools.
+ * Provides consistent validation across all write operations.
+ */
+// Regex to match UID placeholders like {{uid:parent1}}, {{uid:section-a}}, etc.
+const UID_PLACEHOLDER_REGEX = /^\{\{uid:[^}]+\}\}$/;
+/**
+ * Validates a block string content.
+ * @param str The string to validate
+ * @param allowEmpty If true, allows empty strings (for intentional blank blocks)
+ * @returns Error message if invalid, null if valid
+ */
+export function validateBlockString(str, allowEmpty = false) {
+    if (str === undefined || str === null) {
+        return 'string is required';
+    }
+    // Only reject truly empty strings '', not whitespace-only strings like ' '
+    // Whitespace-only strings are valid in Roam (e.g., empty table cells)
+    if (!allowEmpty && typeof str === 'string' && str === '') {
+        return 'string cannot be empty (use " " for intentional whitespace)';
+    }
+    return null;
+}
+/**
+ * Validates a Roam UID.
+ * UIDs must be either:
+ * - 9 alphanumeric characters (standard Roam UID)
+ * - A placeholder like {{uid:name}}
+ * @param uid The UID to validate
+ * @param required If true, UID is required
+ * @returns Error message if invalid, null if valid
+ */
+export function validateUid(uid, required = true) {
+    if (!uid) {
+        return required ? 'uid is required' : null;
+    }
+    // Check if it's a placeholder
+    if (UID_PLACEHOLDER_REGEX.test(uid)) {
+        return null;
+    }
+    // Check if it's a valid Roam UID (9 alphanumeric characters)
+    if (!/^[a-zA-Z0-9_-]{9}$/.test(uid)) {
+        return 'uid must be 9 alphanumeric characters or a {{uid:name}} placeholder';
+    }
+    return null;
+}
+/**
+ * Validates an outline level.
+ * @param level The level to validate
+ * @returns Error message if invalid, null if valid
+ */
+export function validateOutlineLevel(level) {
+    if (level === undefined || level === null) {
+        return 'level is required';
+    }
+    if (!Number.isInteger(level) || level < 1 || level > 10) {
+        return 'level must be an integer between 1 and 10';
+    }
+    return null;
+}
+/**
+ * Validates a location object for block creation/movement.
+ * @param location The location object to validate
+ * @returns Error message if invalid, null if valid
+ */
+export function validateLocation(location) {
+    if (!location) {
+        return 'location is required';
+    }
+    if (!location['parent-uid']) {
+        return 'location.parent-uid is required';
+    }
+    const uidError = validateUid(location['parent-uid'], true);
+    if (uidError) {
+        return `location.parent-uid: ${uidError}`;
+    }
+    return null;
+}
+/**
+ * Validates a heading level.
+ * @param heading The heading level to validate
+ * @returns Error message if invalid, null if valid
+ */
+export function validateHeading(heading) {
+    if (heading === undefined || heading === null || heading === 0) {
+        return null; // Heading is optional
+    }
+    if (!Number.isInteger(heading) || heading < 1 || heading > 3) {
+        return 'heading must be 1, 2, or 3';
+    }
+    return null;
+}
+/**
+ * Validates all batch actions before execution.
+ * @param actions Array of batch actions to validate
+ * @returns ValidationResult with errors if any
+ */
+export function validateBatchActions(actions) {
+    const errors = [];
+    if (!Array.isArray(actions)) {
+        errors.push({
+            field: 'actions',
+            message: 'actions must be an array'
+        });
+        return { valid: false, errors };
+    }
+    if (actions.length === 0) {
+        errors.push({
+            field: 'actions',
+            message: 'actions array cannot be empty'
+        });
+        return { valid: false, errors };
+    }
+    // Track defined placeholders for forward-reference validation
+    const definedPlaceholders = new Set();
+    for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        // Validate action type
+        if (!action.action) {
+            errors.push({
+                actionIndex: i,
+                field: 'action',
+                message: 'action type is required',
+                expected: 'create-block | update-block | move-block | delete-block'
+            });
+            continue;
+        }
+        const validActions = ['create-block', 'update-block', 'move-block', 'delete-block'];
+        if (!validActions.includes(action.action)) {
+            errors.push({
+                actionIndex: i,
+                field: 'action',
+                message: `invalid action type: ${action.action}`,
+                expected: 'create-block | update-block | move-block | delete-block',
+                received: action.action
+            });
+            continue;
+        }
+        // Track placeholder definitions
+        if (action.uid && UID_PLACEHOLDER_REGEX.test(action.uid)) {
+            const placeholderMatch = action.uid.match(/\{\{uid:([^}]+)\}\}/);
+            if (placeholderMatch) {
+                definedPlaceholders.add(placeholderMatch[1]);
+            }
+        }
+        // Validate based on action type
+        switch (action.action) {
+            case 'create-block': {
+                // create-block requires string and location
+                const stringError = validateBlockString(action.string);
+                if (stringError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'string',
+                        message: stringError
+                    });
+                }
+                const locationError = validateLocation(action.location);
+                if (locationError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'location',
+                        message: locationError
+                    });
+                }
+                // Check for forward-reference to undefined placeholder
+                if (action.location?.['parent-uid']) {
+                    const parentUid = action.location['parent-uid'];
+                    const placeholderMatch = parentUid.match(/\{\{uid:([^}]+)\}\}/);
+                    if (placeholderMatch && !definedPlaceholders.has(placeholderMatch[1])) {
+                        errors.push({
+                            actionIndex: i,
+                            field: 'location.parent-uid',
+                            message: `Placeholder {{uid:${placeholderMatch[1]}}} referenced before definition`
+                        });
+                    }
+                }
+                const headingError = validateHeading(action.heading);
+                if (headingError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'heading',
+                        message: headingError
+                    });
+                }
+                break;
+            }
+            case 'update-block': {
+                // update-block requires uid
+                const uidError = validateUid(action.uid);
+                if (uidError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'uid',
+                        message: uidError
+                    });
+                }
+                // string is optional for update but if provided, validate it
+                if (action.string !== undefined) {
+                    const stringError = validateBlockString(action.string);
+                    if (stringError) {
+                        errors.push({
+                            actionIndex: i,
+                            field: 'string',
+                            message: stringError
+                        });
+                    }
+                }
+                const headingError = validateHeading(action.heading);
+                if (headingError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'heading',
+                        message: headingError
+                    });
+                }
+                break;
+            }
+            case 'move-block': {
+                // move-block requires uid and location
+                const uidError = validateUid(action.uid);
+                if (uidError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'uid',
+                        message: uidError
+                    });
+                }
+                const locationError = validateLocation(action.location);
+                if (locationError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'location',
+                        message: locationError
+                    });
+                }
+                break;
+            }
+            case 'delete-block': {
+                // delete-block requires uid
+                const uidError = validateUid(action.uid);
+                if (uidError) {
+                    errors.push({
+                        actionIndex: i,
+                        field: 'uid',
+                        message: uidError
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors
+    };
+}
+/**
+ * Formats validation errors into a human-readable string.
+ */
+export function formatValidationErrors(errors) {
+    return errors
+        .map(err => {
+        const prefix = err.actionIndex !== undefined ? `Action ${err.actionIndex}: ` : '';
+        return `${prefix}[${err.field}] ${err.message}`;
+    })
+        .join('; ');
+}

package/build/tools/operations/batch.js

@@ -1,10 +1,133 @@
 import { batchActions as roamBatchActions } from '@roam-research/roam-api-sdk';
+import { generateBlockUid } from '../../markdown-utils.js';
+import { validateBatchActions, formatValidationErrors } from '../../shared/validation.js';
+import { isRateLimitError, createRateLimitError } from '../../shared/errors.js';
+// Regex to match UID placeholders like {{uid:parent1}}, {{uid:section-a}}, etc.
+const UID_PLACEHOLDER_REGEX = /\{\{uid:([^}]+)\}\}/g;
+const DEFAULT_RATE_LIMIT_CONFIG = {
+    maxRetries: 3,
+    initialDelayMs: 1000,
+    maxDelayMs: 60000,
+    backoffMultiplier: 2
+};
+/**
+ * Sleep for a specified number of milliseconds.
+ */
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
 export class BatchOperations {
-    constructor(graph) {
+    constructor(graph, rateLimitConfig) {
         this.graph = graph;
+        this.rateLimitConfig = { ...DEFAULT_RATE_LIMIT_CONFIG, ...rateLimitConfig };
+    }
+    /**
+     * Finds all unique UID placeholders in the actions and generates real UIDs for them.
+     * Returns a map of placeholder name → generated UID.
+     */
+    generateUidMap(actions) {
+        const placeholders = new Set();
+        const actionsJson = JSON.stringify(actions);
+        let match;
+        // Reset regex lastIndex to ensure fresh matching
+        UID_PLACEHOLDER_REGEX.lastIndex = 0;
+        while ((match = UID_PLACEHOLDER_REGEX.exec(actionsJson)) !== null) {
+            placeholders.add(match[1]); // The placeholder name (e.g., "parent1")
+        }
+        const uidMap = {};
+        for (const placeholder of placeholders) {
+            uidMap[placeholder] = generateBlockUid();
+        }
+        return uidMap;
+    }
+    /**
+     * Replaces all {{uid:*}} placeholders in a string with their generated UIDs.
+     */
+    replacePlaceholders(value, uidMap) {
+        return value.replace(UID_PLACEHOLDER_REGEX, (_, name) => {
+            return uidMap[name] || _; // Return original if not found (shouldn't happen)
+        });
+    }
+    /**
+     * Recursively replaces placeholders in an object/array.
+     */
+    replacePlaceholdersInObject(obj, uidMap) {
+        if (typeof obj === 'string') {
+            return this.replacePlaceholders(obj, uidMap);
+        }
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.replacePlaceholdersInObject(item, uidMap));
+        }
+        if (obj && typeof obj === 'object') {
+            const result = {};
+            for (const key of Object.keys(obj)) {
+                result[key] = this.replacePlaceholdersInObject(obj[key], uidMap);
+            }
+            return result;
+        }
+        return obj;
+    }
+    /**
+     * Executes the batch operation with retry logic for rate limiting.
+     */
+    async executeWithRetry(batchActions) {
+        let lastError;
+        let delay = this.rateLimitConfig.initialDelayMs;
+        for (let attempt = 0; attempt <= this.rateLimitConfig.maxRetries; attempt++) {
+            try {
+                await roamBatchActions(this.graph, { actions: batchActions });
+                return;
+            }
+            catch (error) {
+                if (!isRateLimitError(error)) {
+                    throw error;
+                }
+                lastError = error;
+                if (attempt < this.rateLimitConfig.maxRetries) {
+                    const waitTime = Math.min(delay, this.rateLimitConfig.maxDelayMs);
+                    console.log(`[batch] Rate limited, retrying in ${waitTime}ms (attempt ${attempt + 1}/${this.rateLimitConfig.maxRetries})`);
+                    await sleep(waitTime);
+                    delay *= this.rateLimitConfig.backoffMultiplier;
+                }
+            }
+        }
+        // Throw with rate limit context after all retries exhausted
+        const rateLimitError = new Error(`Rate limit exceeded after ${this.rateLimitConfig.maxRetries} retries. ` +
+            `Last error: ${lastError?.message || 'Unknown error'}. ` +
+            `Retry after ${this.rateLimitConfig.maxDelayMs}ms.`);
+        rateLimitError.isRateLimit = true;
+        rateLimitError.retryAfterMs = this.rateLimitConfig.maxDelayMs;
+        throw rateLimitError;
     }
     async processBatch(actions) {
-        const batchActions = actions.map(action => {
+        // Step 0: Pre-validate all actions before any execution
+        const validationResult = validateBatchActions(actions);
+        if (!validationResult.valid) {
+            return {
+                success: false,
+                error: {
+                    code: 'VALIDATION_ERROR',
+                    message: formatValidationErrors(validationResult.errors),
+                    details: validationResult.errors.length > 0 ? {
+                        action_index: validationResult.errors[0].actionIndex,
+                        field: validationResult.errors[0].field,
+                        expected: validationResult.errors[0].expected,
+                        received: validationResult.errors[0].received
+                    } : undefined
+                },
+                validation_passed: false,
+                actions_attempted: 0
+            };
+        }
+        // Step 1: Generate UIDs for all placeholders
+        const uidMap = this.generateUidMap(actions);
+        const hasPlaceholders = Object.keys(uidMap).length > 0;
+        // Step 2: Replace placeholders with real UIDs
+        const processedActions = hasPlaceholders
+            ? this.replacePlaceholdersInObject(actions, uidMap)
+            : actions;
+        // Step 3: Convert to Roam batch actions format
+        const batchActions = processedActions.map((action) => {
             const { action: actionType, ...rest } = action;
             const roamAction = { action: actionType };
             if (rest.location) {
@@ -32,6 +155,45 @@ export class BatchOperations {
             }
             return roamAction;
         });
-        return await roamBatchActions(this.graph, { actions: batchActions });
+        try {
+            await this.executeWithRetry(batchActions);
+            // SUCCESS: Return uid_map only on success
+            const result = {
+                success: true,
+                validation_passed: true,
+                actions_attempted: batchActions.length
+            };
+            if (hasPlaceholders) {
+                result.uid_map = uidMap;
+            }
+            return result;
+        }
+        catch (error) {
+            // FAILURE: Do NOT return uid_map - blocks don't exist
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Check if it's a rate limit error
+            if (isRateLimitError(error) || error.isRateLimit) {
+                return {
+                    success: false,
+                    error: createRateLimitError(error.retryAfterMs),
+                    validation_passed: true,
+                    actions_attempted: batchActions.length
+                    // No uid_map - nothing was committed
+                };
+            }
+            return {
+                success: false,
+                error: {
+                    code: 'TRANSACTION_FAILED',
+                    message: errorMessage,
+                    recovery: {
+                        suggestion: 'Check the error message and retry with corrected actions'
+                    }
+                },
+                validation_passed: true,
+                actions_attempted: batchActions.length
+                // No uid_map - nothing was committed (or we can't verify what was)
+            };
+        }
     }
 }

package/build/tools/operations/memory.js

@@ -3,6 +3,7 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { formatRoamDate } from '../../utils/helpers.js';
 import { resolveRefs } from '../helpers/refs.js';
 import { SearchOperations } from './search/index.js';
+import { pageUidCache } from '../../cache/page-uid-cache.js';
 export class MemoryOperations {
     constructor(graph) {
         this.graph = graph;
@@ -12,29 +13,38 @@ export class MemoryOperations {
         // Get today's date
         const today = new Date();
         const dateStr = formatRoamDate(today);
-        // Try to find today's page
-        const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
-        const findResults = await q(this.graph, findQuery, [dateStr]);
         let pageUid;
-        if (findResults && findResults.length > 0) {
-            pageUid = findResults[0][0];
+        // Check cache first for today's page
+        const cachedUid = pageUidCache.get(dateStr);
+        if (cachedUid) {
+            pageUid = cachedUid;
         }
         else {
-            // Create today's page if it doesn't exist
-            try {
-                await createPage(this.graph, {
-                    action: 'create-page',
-                    page: { title: dateStr }
-                });
-                // Get the new page's UID
-                const results = await q(this.graph, findQuery, [dateStr]);
-                if (!results || results.length === 0) {
-                    throw new McpError(ErrorCode.InternalError, 'Could not find created today\'s page');
-                }
-                pageUid = results[0][0];
+            // Try to find today's page
+            const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+            const findResults = await q(this.graph, findQuery, [dateStr]);
+            if (findResults && findResults.length > 0) {
+                pageUid = findResults[0][0];
+                pageUidCache.set(dateStr, pageUid);
             }
-            catch (error) {
-                throw new McpError(ErrorCode.InternalError, 'Failed to create today\'s page');
+            else {
+                // Create today's page if it doesn't exist
+                try {
+                    await createPage(this.graph, {
+                        action: 'create-page',
+                        page: { title: dateStr }
+                    });
+                    // Get the new page's UID
+                    const results = await q(this.graph, findQuery, [dateStr]);
+                    if (!results || results.length === 0) {
+                        throw new McpError(ErrorCode.InternalError, 'Could not find created today\'s page');
+                    }
+                    pageUid = results[0][0];
+                    pageUidCache.onPageCreated(dateStr, pageUid);
+                }
+                catch (error) {
+                    throw new McpError(ErrorCode.InternalError, 'Failed to create today\'s page');
+                }
             }
         }
         // Get memories tag from environment