roam-research-mcp 1.4.0 → 2.4.0

package/build/cli/commands/search.js

@@ -0,0 +1,240 @@
+import { Command } from 'commander';
+import { SearchOperations } from '../../tools/operations/search/index.js';
+import { formatSearchResults, printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+/**
+ * Normalize a tag by stripping #, [[, ]] wrappers
+ */
+function normalizeTag(tag) {
+    return tag.replace(/^#?\[?\[?/, '').replace(/\]?\]?$/, '');
+}
+/**
+ * Check if content contains a tag (handles #tag, [[tag]], #[[tag]] formats)
+ */
+function contentHasTag(content, tag) {
+    const normalized = normalizeTag(tag);
+    return (content.includes(`[[${normalized}]]`) ||
+        content.includes(`#${normalized}`) ||
+        content.includes(`#[[${normalized}]]`));
+}
+export function createSearchCommand() {
+    return new Command('search')
+        .description('Search blocks by text, tags, Datalog queries, or within specific pages')
+        .argument('[terms...]', 'Search terms (multiple terms use AND logic)')
+        .option('--tag <tag>', 'Filter by tag (repeatable, comma-separated). Default: AND logic', (val, prev) => {
+        // Support both comma-separated and multiple flags
+        const tags = val.split(',').map(t => t.trim()).filter(Boolean);
+        return prev ? [...prev, ...tags] : tags;
+    }, [])
+        .option('--any', 'Use OR logic for multiple tags (default is AND)')
+        .option('--negtag <tag>', 'Exclude blocks with tag (repeatable, comma-separated)', (val, prev) => {
+        const tags = val.split(',').map(t => t.trim()).filter(Boolean);
+        return prev ? [...prev, ...tags] : tags;
+    }, [])
+        .option('--page <title>', 'Scope search to a specific page')
+        .option('-i, --case-insensitive', 'Case-insensitive search')
+        .option('-n, --limit <n>', 'Limit number of results (default: 20)', '20')
+        .option('--json', 'Output as JSON')
+        .option('--debug', 'Show query metadata')
+        .option('-g, --graph <name>', 'Target graph key (for multi-graph mode)')
+        .option('-q, --query <datalog>', 'Raw Datalog query (bypasses other search options)')
+        .option('--inputs <json>', 'JSON array of inputs for Datalog query')
+        .option('--regex <pattern>', 'Client-side regex filter on Datalog results')
+        .option('--regex-flags <flags>', 'Regex flags (e.g., "i" for case-insensitive)')
+        .addHelpText('after', `
+Examples:
+  # Text search
+  roam search "meeting notes"               # Find blocks containing text
+  roam search api integration               # Multiple terms (AND logic)
+  roam search "bug fix" -i                  # Case-insensitive search
+
+  # Tag search
+  roam search --tag TODO                    # All blocks with #TODO
+  roam search --tag "[[Project Alpha]]"     # Blocks with page reference
+  roam search --tag work --page "January 3rd, 2026"  # Tag on specific page
+
+  # Multiple tags
+  roam search --tag TODO --tag urgent       # Blocks with BOTH tags (AND)
+  roam search --tag "TODO,urgent,blocked"   # Comma-separated (AND)
+  roam search --tag TODO --tag urgent --any # Blocks with ANY tag (OR)
+
+  # Exclude tags
+  roam search --tag TODO --negtag done      # TODOs excluding #done
+  roam search --tag TODO --negtag "someday,maybe"  # Exclude multiple
+
+  # Combined filters
+  roam search urgent --tag TODO             # Text + tag filter
+  roam search "review" --page "Work"        # Search within page
+
+  # Output options
+  roam search "design" -n 50                # Limit to 50 results
+  roam search "api" --json                  # JSON output
+
+  # Datalog queries (advanced)
+  roam search -q '[:find ?title :where [?e :node/title ?title]]'
+  roam search -q '[:find ?s :in $ ?term :where [?b :block/string ?s] [(clojure.string/includes? ?s ?term)]]' --inputs '["TODO"]'
+  roam search -q '[:find ?uid ?s :where [?b :block/uid ?uid] [?b :block/string ?s]]' --regex "meeting" --regex-flags "i"
+
+Datalog tips:
+  Common attributes: :node/title, :block/string, :block/uid, :block/page, :block/children
+  Predicates: clojure.string/includes?, clojure.string/starts-with?, <, >, =
+`)
+        .action(async (terms, options) => {
+        try {
+            const graph = resolveGraph(options, false);
+            const limit = parseInt(options.limit || '20', 10);
+            const outputOptions = {
+                json: options.json,
+                debug: options.debug
+            };
+            if (options.debug) {
+                printDebug('Search terms', terms);
+                printDebug('Graph', options.graph || 'default');
+                printDebug('Options', options);
+            }
+            const searchOps = new SearchOperations(graph);
+            // Datalog query mode (bypasses other search options)
+            // See for query construction - Roam_Research_Datalog_Cheatsheet.md
+            if (options.query) {
+                // Parse inputs if provided
+                let inputs;
+                if (options.inputs) {
+                    try {
+                        inputs = JSON.parse(options.inputs);
+                        if (!Array.isArray(inputs)) {
+                            exitWithError('--inputs must be a JSON array');
+                        }
+                    }
+                    catch {
+                        exitWithError('Invalid JSON in --inputs');
+                    }
+                }
+                if (options.debug) {
+                    printDebug('Datalog query', options.query);
+                    printDebug('Inputs', inputs || 'none');
+                    printDebug('Regex filter', options.regex || 'none');
+                }
+                const result = await searchOps.executeDatomicQuery({
+                    query: options.query,
+                    inputs,
+                    regexFilter: options.regex,
+                    regexFlags: options.regexFlags
+                });
+                if (!result.success) {
+                    exitWithError(result.message || 'Query failed');
+                }
+                // Apply limit and format output
+                const limitedMatches = result.matches.slice(0, limit);
+                if (options.json) {
+                    // For JSON output, parse the content back to objects
+                    const parsed = limitedMatches.map(m => {
+                        try {
+                            return JSON.parse(m.content);
+                        }
+                        catch {
+                            return m.content;
+                        }
+                    });
+                    console.log(JSON.stringify(parsed, null, 2));
+                }
+                else {
+                    // For text output, show raw results
+                    if (limitedMatches.length === 0) {
+                        console.log('No results found.');
+                    }
+                    else {
+                        console.log(`Found ${result.matches.length} results${result.matches.length > limit ? ` (showing first ${limit})` : ''}:\n`);
+                        for (const match of limitedMatches) {
+                            console.log(match.content);
+                        }
+                    }
+                }
+                return;
+            }
+            // Determine search type based on options
+            const tags = options.tag || [];
+            if (tags.length > 0 && terms.length === 0) {
+                // Tag-only search
+                const normalizedTags = tags.map(normalizeTag);
+                const useOrLogic = options.any || false;
+                if (options.debug) {
+                    printDebug('Tag search', {
+                        tags: normalizedTags,
+                        logic: useOrLogic ? 'OR' : 'AND',
+                        page: options.page
+                    });
+                }
+                // Search for first tag, then filter by additional tags
+                const result = await searchOps.searchForTag(normalizedTags[0], options.page);
+                let matches = result.matches;
+                // Apply multi-tag filter if more than one tag
+                if (normalizedTags.length > 1) {
+                    matches = matches.filter(m => {
+                        if (useOrLogic) {
+                            // OR: has at least one tag
+                            return normalizedTags.some(tag => contentHasTag(m.content, tag));
+                        }
+                        else {
+                            // AND: has all tags
+                            return normalizedTags.every(tag => contentHasTag(m.content, tag));
+                        }
+                    });
+                }
+                // Apply negtag filter (exclude blocks with any of these tags)
+                const negTags = options.negtag || [];
+                if (negTags.length > 0) {
+                    const normalizedNegTags = negTags.map(normalizeTag);
+                    matches = matches.filter(m => !normalizedNegTags.some(tag => contentHasTag(m.content, tag)));
+                }
+                const limitedMatches = matches.slice(0, limit);
+                console.log(formatSearchResults(limitedMatches, outputOptions));
+            }
+            else if (terms.length > 0) {
+                // Text search (with optional tag filter)
+                const searchText = terms.join(' ');
+                if (options.debug) {
+                    printDebug('Text search', { text: searchText, page: options.page, tag: options.tag });
+                }
+                const result = await searchOps.searchByText({
+                    text: searchText,
+                    page_title_uid: options.page
+                });
+                // Apply client-side filters
+                let matches = result.matches;
+                // Case-insensitive filter if requested
+                if (options.caseInsensitive) {
+                    const lowerSearchText = searchText.toLowerCase();
+                    matches = matches.filter(m => m.content.toLowerCase().includes(lowerSearchText));
+                }
+                // Tag filter if provided
+                if (tags.length > 0) {
+                    const normalizedTags = tags.map(normalizeTag);
+                    const useOrLogic = options.any || false;
+                    matches = matches.filter(m => {
+                        if (useOrLogic) {
+                            return normalizedTags.some(tag => contentHasTag(m.content, tag));
+                        }
+                        else {
+                            return normalizedTags.every(tag => contentHasTag(m.content, tag));
+                        }
+                    });
+                }
+                // Negtag filter (exclude blocks with any of these tags)
+                const negTags = options.negtag || [];
+                if (negTags.length > 0) {
+                    const normalizedNegTags = negTags.map(normalizeTag);
+                    matches = matches.filter(m => !normalizedNegTags.some(tag => contentHasTag(m.content, tag)));
+                }
+                // Apply limit
+                console.log(formatSearchResults(matches.slice(0, limit), outputOptions));
+            }
+            else {
+                exitWithError('Please provide search terms or use --tag to search by tag');
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/status.js

@@ -0,0 +1,91 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getRegistry } from '../utils/graph.js';
+import { q } from '@roam-research/roam-api-sdk';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read package.json to get the version
+const packageJsonPath = join(__dirname, '../../../package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+const version = packageJson.version;
+export function createStatusCommand() {
+    return new Command('status')
+        .description('Show available graphs and connection status')
+        .option('--ping', 'Test connection to each graph')
+        .option('--json', 'Output as JSON')
+        .addHelpText('after', `
+Examples:
+  # Show available graphs
+  roam status
+
+  # Test connectivity to all graphs
+  roam status --ping
+
+  # JSON output for scripting
+  roam status --json
+`)
+        .action(async (options) => {
+        try {
+            const registry = getRegistry();
+            const graphKeys = registry.getAvailableGraphs();
+            const statuses = [];
+            for (const key of graphKeys) {
+                const config = registry.getConfig(key);
+                const isDefault = key === registry.defaultKey;
+                const isProtected = !!config.write_key;
+                const status = {
+                    name: key,
+                    default: isDefault,
+                    protected: isProtected,
+                };
+                if (isProtected) {
+                    status.writeKey = config.write_key;
+                }
+                if (options.ping) {
+                    try {
+                        const graph = registry.getGraph(key);
+                        // Simple query to test connection - just find any entity
+                        await q(graph, '[:find ?e . :where [?e :db/id]]', []);
+                        status.connected = true;
+                    }
+                    catch (error) {
+                        status.connected = false;
+                        status.error = error instanceof Error ? error.message : String(error);
+                    }
+                }
+                statuses.push(status);
+            }
+            if (options.json) {
+                console.log(JSON.stringify({
+                    version,
+                    graphs: statuses,
+                }, null, 2));
+                return;
+            }
+            // Pretty print
+            console.log(`Roam Research MCP v${version}\n`);
+            console.log('Graphs:');
+            for (const status of statuses) {
+                const defaultTag = status.default ? ' (default)' : '';
+                const protectedTag = status.protected ? ' [protected]' : '';
+                let connectionStatus = '';
+                if (options.ping) {
+                    connectionStatus = status.connected
+                        ? '  ✓ connected'
+                        : `  ✗ ${status.error || 'connection failed'}`;
+                }
+                console.log(`  • ${status.name}${defaultTag}${protectedTag}${connectionStatus}`);
+            }
+            if (statuses.some(s => s.protected)) {
+                console.log('\nWrite-protected graphs require --write-key flag for modifications.');
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Error: ${message}`);
+            process.exit(1);
+        }
+    });
+}

package/build/cli/commands/update.js

@@ -0,0 +1,151 @@
+import { Command } from 'commander';
+import { BatchOperations } from '../../tools/operations/batch.js';
+import { parseMarkdownHeadingLevel } from '../../markdown-utils.js';
+import { printDebug, exitWithError } from '../utils/output.js';
+import { resolveGraph } from '../utils/graph.js';
+// Patterns for TODO/DONE markers (both {{TODO}} and {{[[TODO]]}} formats)
+const TODO_PATTERN = /\{\{(\[\[)?TODO(\]\])?\}\}\s*/g;
+const DONE_PATTERN = /\{\{(\[\[)?DONE(\]\])?\}\}\s*/g;
+const ANY_STATUS_PATTERN = /\{\{(\[\[)?(TODO|DONE)(\]\])?\}\}\s*/g;
+/**
+ * Apply TODO/DONE status to content
+ * - If target status marker exists, no change needed
+ * - If opposite status exists, replace it
+ * - If no status exists, prepend
+ */
+function applyStatus(content, status) {
+    const marker = `{{[[${status}]]}} `;
+    const hasStatus = status === 'TODO'
+        ? TODO_PATTERN.test(content)
+        : DONE_PATTERN.test(content);
+    // Reset regex lastIndex
+    TODO_PATTERN.lastIndex = 0;
+    DONE_PATTERN.lastIndex = 0;
+    if (hasStatus) {
+        return content; // Already has the target status
+    }
+    // Check for opposite status and replace
+    const oppositePattern = status === 'TODO' ? DONE_PATTERN : TODO_PATTERN;
+    if (oppositePattern.test(content)) {
+        oppositePattern.lastIndex = 0;
+        return content.replace(oppositePattern, marker);
+    }
+    // No status exists, prepend
+    return marker + content;
+}
+/**
+ * Remove any TODO/DONE status from content
+ */
+function clearStatus(content) {
+    return content.replace(ANY_STATUS_PATTERN, '').trim();
+}
+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')
+        .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)')
+        .option('-T, --todo', 'Set as TODO (replaces DONE if present, prepends if none)')
+        .option('-D, --done', 'Set as DONE (replaces TODO if present, prepends if none)')
+        .option('--clear-status', 'Remove TODO/DONE marker')
+        .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
+        .option('--write-key <key>', 'Write confirmation key (non-default graphs)')
+        .option('--debug', 'Show debug information')
+        .addHelpText('after', `
+Examples:
+  # Basic update
+  roam update abc123def "New content"         # Update block text
+  roam update "((abc123def))" "New content"   # UID with wrapper
+
+  # Heading updates
+  roam update abc123def "# Main Title"        # Auto-detect H1, strip #
+  roam update abc123def "Title" -H 2          # Explicit H2
+  roam update abc123def "Plain text" -H 0     # Remove heading
+
+  # Block state
+  roam update abc123def "Content" -o          # Expand block
+  roam update abc123def "Content" -c          # Collapse block
+
+  # TODO/DONE status
+  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
+`)
+        .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;
+            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;
+                }
+            }
+            else {
+                // Auto-detect heading from content
+                const { heading_level, content: stripped } = parseMarkdownHeadingLevel(content);
+                if (heading_level > 0) {
+                    headingLevel = heading_level;
+                    finalContent = stripped;
+                }
+            }
+            // Handle open/closed state
+            let openState;
+            if (options.open) {
+                openState = true;
+            }
+            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('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',
+                    uid: blockUid,
+                    string: finalContent,
+                    ...(headingLevel !== undefined && { heading: headingLevel }),
+                    ...(openState !== undefined && { open: openState })
+                }]);
+            if (result.success) {
+                console.log(`Updated block ${blockUid}`);
+            }
+            else {
+                const errorMsg = typeof result.error === 'string'
+                    ? result.error
+                    : result.error?.message || 'Unknown error';
+                exitWithError(`Failed to update block: ${errorMsg}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/roam.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createGetCommand } from './commands/get.js';
+import { createSearchCommand } from './commands/search.js';
+import { createSaveCommand } from './commands/save.js';
+import { createRefsCommand } from './commands/refs.js';
+import { createUpdateCommand } from './commands/update.js';
+import { createBatchCommand } from './commands/batch.js';
+import { createRenameCommand } from './commands/rename.js';
+import { createStatusCommand } from './commands/status.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read package.json to get the version
+const packageJsonPath = join(__dirname, '../../package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+const cliVersion = packageJson.version;
+const program = new Command();
+program
+    .name('roam')
+    .description('CLI for Roam Research')
+    .version(cliVersion);
+// Register subcommands
+program.addCommand(createGetCommand());
+program.addCommand(createSearchCommand());
+program.addCommand(createSaveCommand());
+program.addCommand(createRefsCommand());
+program.addCommand(createUpdateCommand());
+program.addCommand(createBatchCommand());
+program.addCommand(createRenameCommand());
+program.addCommand(createStatusCommand());
+// Parse arguments
+program.parse();

package/build/cli/utils/graph.js

@@ -0,0 +1,56 @@
+/**
+ * CLI graph resolution utilities for multi-graph support
+ */
+import { createRegistryFromEnv } from '../../config/graph-registry.js';
+import { validateEnvironment } from '../../config/environment.js';
+let registry = null;
+/**
+ * Get or create the GraphRegistry singleton
+ */
+export function getRegistry() {
+    if (!registry) {
+        validateEnvironment();
+        registry = createRegistryFromEnv();
+    }
+    return registry;
+}
+/**
+ * Resolve a Graph instance for CLI use
+ * Validates write access for write operations
+ *
+ * @param options - CLI options containing graph and writeKey
+ * @param isWriteOp - Whether this is a write operation
+ */
+export function resolveGraph(options, isWriteOp = false) {
+    const reg = getRegistry();
+    if (isWriteOp) {
+        // For write operations, validate write access
+        const graphKey = options.graph ?? reg.defaultKey;
+        if (!reg.isWriteAllowed(graphKey, options.writeKey)) {
+            const config = reg.getConfig(graphKey);
+            if (config?.write_key) {
+                throw new Error(`Write to "${graphKey}" graph requires --write-key confirmation.\n` +
+                    `Use: --write-key "${config.write_key}"`);
+            }
+        }
+    }
+    return reg.getGraph(options.graph);
+}
+/**
+ * Get available graph names for help text
+ */
+export function getAvailableGraphs() {
+    return getRegistry().getAvailableGraphs();
+}
+/**
+ * Get the default graph key
+ */
+export function getDefaultGraphKey() {
+    return getRegistry().defaultKey;
+}
+/**
+ * Check if running in multi-graph mode
+ */
+export function isMultiGraphMode() {
+    return getRegistry().isMultiGraph;
+}