roam-research-mcp 1.4.0 → 1.6.0

package/README.md

@@ -7,7 +7,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)
 
-A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. It supports standard input/output (stdio) and HTTP Stream communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
+A Model Context Protocol (MCP) server and standalone CLI that provides comprehensive access to Roam Research's API functionality. The MCP server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface, while the CLI (`roam`) lets you fetch, search, and import content directly from the command line. Supports standard input/output (stdio) and HTTP Stream communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
 
 <a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://glama.ai/mcp/servers/fzfznyaflu/badge" alt="Roam Research MCP server" /></a>
 <a href="https://mseep.ai/app/2b3pro-roam-research-mcp"><img width="380" height="200" src="https://mseep.net/pr/2b3pro-roam-research-mcp-badge.png" alt="MseeP.ai Security Assessment Badge" /></a>
@@ -83,21 +83,129 @@ Alternatively, if you have a `.env` file in the project root (which is copied in
 docker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp
 ```
 
-## Standalone CLI: roam-import
+## Standalone CLI: `roam`
 
-A standalone command-line tool for importing markdown content directly into Roam Research, without running the MCP server.
+A standalone command-line tool for interacting with Roam Research directly, without running the MCP server. Provides four subcommands: `get`, `search`, `save`, and `refs`.
 
-### Usage
+### Installation
+
+After building the project, make the command globally available:
+
+```bash
+npm link
+```
+
+Or run directly without linking:
+
+```bash
+node build/cli/roam.js <command> [options]
+```
+
+### Requirements
+
+Same environment variables as the MCP server:
+- `ROAM_API_TOKEN`: Your Roam Research API token
+- `ROAM_GRAPH_NAME`: Your Roam graph name
+
+Configure via `.env` file in the project root or set as environment variables.
+
+---
+
+### `roam get` - Fetch pages or blocks
+
+Fetch content from Roam and output as markdown or JSON.
 
 ```bash
-# From a file
-cat document.md | roam-import "Meeting Notes"
+# Fetch a page by title
+roam get "Daily Notes"
+
+# Fetch a block by UID
+roam get "((AbCdEfGhI))"
+roam get AbCdEfGhI
+
+# Output as JSON
+roam get "Daily Notes" --json
+
+# Control child depth (default: 4)
+roam get "Daily Notes" --depth 2
+
+# Flatten hierarchy
+roam get "Daily Notes" --flat
+
+# Debug mode
+roam get "Daily Notes" --debug
+```
+
+**Options:**
+- `--json` - Output as JSON instead of markdown
+- `--depth <n>` - Child levels to fetch (default: 4)
+- `--refs <n>` - Block ref expansion depth (default: 1)
+- `--flat` - Flatten hierarchy to single-level list
+- `--debug` - Show query metadata
+
+---
+
+### `roam search` - Search content
+
+Search for blocks containing text or tags.
+
+```bash
+# Full-text search
+roam search "keyword"
+
+# Multiple terms (AND logic)
+roam search "term1" "term2"
 
-# From clipboard (macOS)
-pbpaste | roam-import "Ideas"
+# Tag-only search
+roam search --tag "[[Project]]"
+roam search --tag "#TODO"
+
+# Text + tag filter
+roam search "meeting" --tag "[[Work]]"
+
+# Scope to a specific page
+roam search "task" --page "Daily Notes"
+
+# Case-insensitive search
+roam search "keyword" -i
+
+# Limit results (default: 20)
+roam search "keyword" -n 50
+
+# Output as JSON
+roam search "keyword" --json
+```
+
+**Options:**
+- `--tag <tag>` - Filter by tag (e.g., `#TODO` or `[[Project]]`)
+- `--page <title>` - Scope search to a specific page
+- `-i, --case-insensitive` - Case-insensitive search
+- `-n, --limit <n>` - Limit number of results (default: 20)
+- `--json` - Output as JSON
+- `--debug` - Show query metadata
+
+---
+
+### `roam save` - Import markdown
+
+Import markdown content to Roam, creating or updating pages.
+
+```bash
+# From a file (title derived from filename)
+roam save document.md
+
+# With explicit title
+roam save document.md --title "Meeting Notes"
+
+# Update existing page with smart diff (preserves block UIDs)
+roam save document.md --update
+
+# From stdin (requires --title)
+cat notes.md | roam save --title "Quick Notes"
+pbpaste | roam save --title "Clipboard Content"
 
 # From here-doc
-roam-import "Quick Note" << EOF
+roam save --title "Quick Note" << EOF
 # Heading
 - Item 1
 - Item 2
@@ -105,34 +213,68 @@ roam-import "Quick Note" << EOF
 EOF
 ```
 
-### Features
+**Options:**
+- `--title <title>` - Page title (defaults to filename without `.md`)
+- `--update` - Update existing page using smart diff (preserves block UIDs)
+- `--debug` - Show debug information
 
-- Reads markdown from stdin
+**Features:**
 - Creates a new page with the specified title (or appends to existing page)
 - Automatically links the new page from today's daily page
-- Converts standard markdown to Roam-flavored markdown (bold, italic, highlights, tasks, code blocks)
+- Converts standard markdown to Roam-flavored markdown
+- Smart diff mode (`--update`) preserves block UIDs for existing content
 
-### Installation
+---
 
-After building the project, make the command globally available:
+### `roam refs` - Find references
+
+Find blocks that reference a page or block (backlinks).
 
 ```bash
-npm link
-```
+# Find references to a page
+roam refs "Project Alpha"
+roam refs "December 30th, 2025"
 
-Or run directly without linking:
+# Find references to a tag
+roam refs "#TODO"
+roam refs "[[Meeting Notes]]"
 
-```bash
-cat document.md | node build/cli/import-markdown.js "Page Title"
+# Find references to a block
+roam refs "((AbCdEfGhI))"
+
+# Limit results
+roam refs "My Page" -n 100
+
+# Output as JSON (for LLM/programmatic use)
+roam refs "My Page" --json
+
+# Raw output (for piping)
+roam refs "My Page" --raw
 ```
 
-### Requirements
+**Options:**
+- `-n, --limit <n>` - Limit number of results (default: 50)
+- `--json` - Output as JSON array
+- `--raw` - Output raw UID + content lines (no grouping)
+- `--debug` - Show query metadata
 
-Same environment variables as the MCP server:
-- `ROAM_API_TOKEN`: Your Roam Research API token
-- `ROAM_GRAPH_NAME`: Your Roam graph name
+**Output Formats:**
 
-Configure via `.env` file in the project root or set as environment variables.
+Default output groups results by page:
+```
+[[Reading List: Inbox]]
+  tiTqNBvYA   Date Captured:: [[December 30th, 2025]]
+
+[[Week 53, 2025]]
+  g0ur1z7Bs   [Sun 28]([[December 28th, 2025]]) | [Mon 29](...
+```
+
+JSON output for programmatic use:
+```json
+[
+  {"uid": "tiTqNBvYA", "content": "Date Captured:: [[December 30th, 2025]]", "page": "Reading List: Inbox"}
+]
+```
 
 ---
 
@@ -167,7 +309,7 @@ The server provides powerful tools for interacting with Roam Research:
 5. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
 6. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
 7. `roam_create_outline`: Add a structured outline to an existing page or block, with support for `children_view_type`. Best for simpler, sequential outlines. For complex nesting (e.g., tables), consider `roam_process_batch_actions`. If `page_title_uid` and `block_text_uid` are both blank, content defaults to the daily page. (Internally uses `roam_process_batch_actions`.)
-8. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
+8. `roam_search_block_refs`: Search for block references within a page or across the entire graph. Now supports `title` parameter to find blocks referencing a page title using `:block/refs` (captures `[[page]]` and `#tag` links semantically).
 9. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
 10. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight), with pagination and sorting options.
 11. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page. This tool supports pagination via the `limit` and `offset` parameters.

package/build/cli/commands/get.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { API_TOKEN, GRAPH_NAME } from '../../config/environment.js';
+import { PageOperations } from '../../tools/operations/pages.js';
+import { BlockRetrievalOperations } from '../../tools/operations/block-retrieval.js';
+import { formatPageOutput, formatBlockOutput, printDebug, exitWithError } from '../utils/output.js';
+// Block UID pattern: 9 alphanumeric characters, optionally wrapped in (( ))
+const BLOCK_UID_PATTERN = /^(?:\(\()?([a-zA-Z0-9_-]{9})(?:\)\))?$/;
+export function createGetCommand() {
+    return new Command('get')
+        .description('Fetch a page or block from Roam')
+        .argument('<target>', 'Page title or block UID (e.g., "Page Title" or "((AbCdEfGhI))")')
+        .option('--json', 'Output as JSON instead of markdown')
+        .option('--depth <n>', 'Child levels to fetch (default: 4)', '4')
+        .option('--refs <n>', 'Block ref expansion depth (default: 1)', '1')
+        .option('--flat', 'Flatten hierarchy to single-level list')
+        .option('--debug', 'Show query metadata')
+        .action(async (target, options) => {
+        try {
+            const graph = initializeGraph({
+                token: API_TOKEN,
+                graph: GRAPH_NAME
+            });
+            const depth = parseInt(options.depth || '4', 10);
+            const outputOptions = {
+                json: options.json,
+                flat: options.flat,
+                debug: options.debug
+            };
+            if (options.debug) {
+                printDebug('Target', target);
+                printDebug('Options', { depth, refs: options.refs, ...outputOptions });
+            }
+            // Check if target is a block UID
+            const uidMatch = target.match(BLOCK_UID_PATTERN);
+            if (uidMatch) {
+                // Fetch block by UID
+                const blockUid = uidMatch[1];
+                if (options.debug) {
+                    printDebug('Fetching block', { uid: blockUid, depth });
+                }
+                const blockOps = new BlockRetrievalOperations(graph);
+                const block = await blockOps.fetchBlockWithChildren(blockUid, depth);
+                if (!block) {
+                    exitWithError(`Block with UID "${blockUid}" not found`);
+                }
+                console.log(formatBlockOutput(block, outputOptions));
+            }
+            else {
+                // Fetch page by title
+                if (options.debug) {
+                    printDebug('Fetching page', { title: target, depth });
+                }
+                const pageOps = new PageOperations(graph);
+                const result = await pageOps.fetchPageByTitle(target, 'raw');
+                // Parse the raw result
+                let blocks;
+                if (typeof result === 'string') {
+                    try {
+                        blocks = JSON.parse(result);
+                    }
+                    catch {
+                        // Result is already formatted as string (e.g., "Page Title (no content found)")
+                        console.log(result);
+                        return;
+                    }
+                }
+                else {
+                    blocks = result;
+                }
+                console.log(formatPageOutput(target, blocks, outputOptions));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/refs.js

@@ -0,0 +1,122 @@
+import { Command } from 'commander';
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { API_TOKEN, GRAPH_NAME } from '../../config/environment.js';
+import { SearchOperations } from '../../tools/operations/search/index.js';
+import { printDebug, exitWithError } from '../utils/output.js';
+/**
+ * Format results grouped by page (default output)
+ */
+function formatGrouped(matches, maxContentLength = 60) {
+    if (matches.length === 0) {
+        return 'No references found.';
+    }
+    // Group by page title
+    const byPage = new Map();
+    for (const match of matches) {
+        const pageTitle = match.page_title || 'Unknown Page';
+        if (!byPage.has(pageTitle)) {
+            byPage.set(pageTitle, []);
+        }
+        byPage.get(pageTitle).push(match);
+    }
+    // Format output
+    const lines = [];
+    for (const [pageTitle, pageMatches] of byPage) {
+        lines.push(`[[${pageTitle}]]`);
+        for (const match of pageMatches) {
+            const truncated = match.content.length > maxContentLength
+                ? match.content.slice(0, maxContentLength) + '...'
+                : match.content;
+            lines.push(`  ${match.block_uid}   ${truncated}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+/**
+ * Format results as raw lines (UID + content)
+ */
+function formatRaw(matches, maxContentLength = 60) {
+    if (matches.length === 0) {
+        return 'No references found.';
+    }
+    return matches
+        .map(match => {
+        const truncated = match.content.length > maxContentLength
+            ? match.content.slice(0, maxContentLength) + '...'
+            : match.content;
+        return `${match.block_uid}   ${truncated}`;
+    })
+        .join('\n');
+}
+/**
+ * Parse identifier to determine if it's a block UID or page title
+ */
+function parseIdentifier(identifier) {
+    // Check for ((uid)) format
+    const blockRefMatch = identifier.match(/^\(\(([^)]+)\)\)$/);
+    if (blockRefMatch) {
+        return { block_uid: blockRefMatch[1] };
+    }
+    // Check for [[page]] or #[[page]] format - extract page title
+    const pageRefMatch = identifier.match(/^#?\[\[(.+)\]\]$/);
+    if (pageRefMatch) {
+        return { title: pageRefMatch[1] };
+    }
+    // Check for #tag format
+    if (identifier.startsWith('#')) {
+        return { title: identifier.slice(1) };
+    }
+    // Default: treat as page title
+    return { title: identifier };
+}
+export function createRefsCommand() {
+    return new Command('refs')
+        .description('Find blocks referencing a page or block')
+        .argument('<identifier>', 'Page title or block UID (use ((uid)) for block refs)')
+        .option('-n, --limit <n>', 'Limit number of results', '50')
+        .option('--json', 'Output as JSON array')
+        .option('--raw', 'Output raw UID + content lines (no grouping)')
+        .option('--debug', 'Show query metadata')
+        .action(async (identifier, options) => {
+        try {
+            const graph = initializeGraph({
+                token: API_TOKEN,
+                graph: GRAPH_NAME
+            });
+            const limit = parseInt(options.limit || '50', 10);
+            const { block_uid, title } = parseIdentifier(identifier);
+            if (options.debug) {
+                printDebug('Identifier', identifier);
+                printDebug('Parsed', { block_uid, title });
+                printDebug('Options', options);
+            }
+            const searchOps = new SearchOperations(graph);
+            const result = await searchOps.searchBlockRefs({ block_uid, title });
+            if (options.debug) {
+                printDebug('Total matches', result.matches.length);
+            }
+            // Apply limit
+            const limitedMatches = result.matches.slice(0, limit);
+            // Format output
+            if (options.json) {
+                const jsonOutput = limitedMatches.map(m => ({
+                    uid: m.block_uid,
+                    content: m.content,
+                    page: m.page_title
+                }));
+                console.log(JSON.stringify(jsonOutput, null, 2));
+            }
+            else if (options.raw) {
+                console.log(formatRaw(limitedMatches));
+            }
+            else {
+                console.log(formatGrouped(limitedMatches));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/save.js

@@ -0,0 +1,121 @@
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { basename } from 'path';
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { API_TOKEN, GRAPH_NAME } from '../../config/environment.js';
+import { PageOperations } from '../../tools/operations/pages.js';
+import { parseMarkdown } from '../../markdown-utils.js';
+import { printDebug, exitWithError } from '../utils/output.js';
+/**
+ * Flatten nested MarkdownNode[] to flat array with absolute levels
+ */
+function flattenNodes(nodes, baseLevel = 1) {
+    const result = [];
+    for (const node of nodes) {
+        result.push({
+            text: node.content,
+            level: baseLevel,
+            ...(node.heading_level && { heading: node.heading_level })
+        });
+        if (node.children.length > 0) {
+            result.push(...flattenNodes(node.children, baseLevel + 1));
+        }
+    }
+    return result;
+}
+/**
+ * Read all input from stdin
+ */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+export function createSaveCommand() {
+    return new Command('save')
+        .description('Import markdown to Roam')
+        .argument('[file]', 'Markdown file to import (or pipe content to stdin)')
+        .option('--title <title>', 'Page title (defaults to filename without .md)')
+        .option('--update', 'Update existing page using smart diff')
+        .option('--debug', 'Show debug information')
+        .action(async (file, options) => {
+        try {
+            let markdownContent;
+            let pageTitle;
+            if (file) {
+                // Read from file
+                try {
+                    markdownContent = readFileSync(file, 'utf-8');
+                }
+                catch (err) {
+                    exitWithError(`Could not read file: ${file}`);
+                }
+                // Derive title from filename if not provided
+                pageTitle = options.title || basename(file, '.md');
+            }
+            else {
+                // Read from stdin
+                if (process.stdin.isTTY) {
+                    exitWithError('No file specified and no input piped. Use: roam save <file.md> or cat file.md | roam save --title "Title"');
+                }
+                if (!options.title) {
+                    exitWithError('--title is required when piping from stdin');
+                }
+                markdownContent = await readStdin();
+                pageTitle = options.title;
+            }
+            if (!markdownContent.trim()) {
+                exitWithError('Empty content received');
+            }
+            if (options.debug) {
+                printDebug('Page title', pageTitle);
+                printDebug('Content length', markdownContent.length);
+                printDebug('Update mode', options.update || false);
+            }
+            const graph = initializeGraph({
+                token: API_TOKEN,
+                graph: GRAPH_NAME
+            });
+            const pageOps = new PageOperations(graph);
+            if (options.update) {
+                // Use smart diff to update existing page
+                const result = await pageOps.updatePageMarkdown(pageTitle, markdownContent, false // not dry run
+                );
+                if (result.success) {
+                    console.log(`Updated page '${pageTitle}'`);
+                    console.log(`  ${result.summary}`);
+                    if (result.preservedUids.length > 0) {
+                        console.log(`  Preserved ${result.preservedUids.length} block UID(s)`);
+                    }
+                }
+                else {
+                    exitWithError(`Failed to update page '${pageTitle}'`);
+                }
+            }
+            else {
+                // Create new page (or add content to existing empty page)
+                const nodes = parseMarkdown(markdownContent);
+                const contentBlocks = flattenNodes(nodes);
+                if (contentBlocks.length === 0) {
+                    exitWithError('No content blocks parsed from input');
+                }
+                if (options.debug) {
+                    printDebug('Parsed blocks', contentBlocks.length);
+                }
+                const result = await pageOps.createPage(pageTitle, contentBlocks);
+                if (result.success) {
+                    console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
+                }
+                else {
+                    exitWithError(`Failed to create page '${pageTitle}'`);
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            exitWithError(message);
+        }
+    });
+}

package/build/cli/commands/search.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { API_TOKEN, GRAPH_NAME } from '../../config/environment.js';
+import { SearchOperations } from '../../tools/operations/search/index.js';
+import { formatSearchResults, printDebug, exitWithError } from '../utils/output.js';
+export function createSearchCommand() {
+    return new Command('search')
+        .description('Search for content in Roam')
+        .argument('[terms...]', 'Search terms (multiple terms use AND logic)')
+        .option('--tag <tag>', 'Filter by tag (e.g., "#TODO" or "[[Project]]")')
+        .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')
+        .action(async (terms, options) => {
+        try {
+            const graph = initializeGraph({
+                token: API_TOKEN,
+                graph: GRAPH_NAME
+            });
+            const limit = parseInt(options.limit || '20', 10);
+            const outputOptions = {
+                json: options.json,
+                debug: options.debug
+            };
+            if (options.debug) {
+                printDebug('Search terms', terms);
+                printDebug('Options', options);
+            }
+            const searchOps = new SearchOperations(graph);
+            // Determine search type based on options
+            if (options.tag && terms.length === 0) {
+                // Tag-only search
+                const tagName = options.tag.replace(/^#?\[?\[?/, '').replace(/\]?\]?$/, '');
+                if (options.debug) {
+                    printDebug('Tag search', { tag: tagName, page: options.page });
+                }
+                const result = await searchOps.searchForTag(tagName, options.page);
+                const limitedMatches = result.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 (options.tag) {
+                    const tagPattern = options.tag.replace(/^#?\[?\[?/, '').replace(/\]?\]?$/, '');
+                    matches = matches.filter(m => m.content.includes(`[[${tagPattern}]]`) ||
+                        m.content.includes(`#${tagPattern}`) ||
+                        m.content.includes(`#[[${tagPattern}]]`));
+                }
+                // 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/roam.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { createGetCommand } from './commands/get.js';
+import { createSearchCommand } from './commands/search.js';
+import { createSaveCommand } from './commands/save.js';
+import { createRefsCommand } from './commands/refs.js';
+const program = new Command();
+program
+    .name('roam')
+    .description('CLI for Roam Research')
+    .version('1.6.0');
+// Register subcommands
+program.addCommand(createGetCommand());
+program.addCommand(createSearchCommand());
+program.addCommand(createSaveCommand());
+program.addCommand(createRefsCommand());
+// Parse arguments
+program.parse();

package/build/cli/utils/output.js

@@ -0,0 +1,88 @@
+/**
+ * Convert RoamBlock hierarchy to markdown with proper indentation
+ */
+export function blocksToMarkdown(blocks, level = 0) {
+    return blocks
+        .map(block => {
+        const indent = '  '.repeat(level);
+        let md;
+        // Check block heading level and format accordingly
+        if (block.heading && block.heading > 0) {
+            const hashtags = '#'.repeat(block.heading);
+            md = `${indent}${hashtags} ${block.string}`;
+        }
+        else {
+            md = `${indent}- ${block.string}`;
+        }
+        if (block.children && block.children.length > 0) {
+            md += '\n' + blocksToMarkdown(block.children, level + 1);
+        }
+        return md;
+    })
+        .join('\n');
+}
+/**
+ * Flatten block hierarchy to single-level list
+ */
+export function flattenBlocks(blocks, result = []) {
+    for (const block of blocks) {
+        result.push({ ...block, children: [] });
+        if (block.children && block.children.length > 0) {
+            flattenBlocks(block.children, result);
+        }
+    }
+    return result;
+}
+/**
+ * Format page content for output
+ */
+export function formatPageOutput(title, blocks, options) {
+    if (options.json) {
+        const data = options.flat ? flattenBlocks(blocks) : blocks;
+        return JSON.stringify({ title, children: data }, null, 2);
+    }
+    const displayBlocks = options.flat ? flattenBlocks(blocks) : blocks;
+    return `# ${title}\n\n${blocksToMarkdown(displayBlocks)}`;
+}
+/**
+ * Format block content for output
+ */
+export function formatBlockOutput(block, options) {
+    if (options.json) {
+        const data = options.flat ? flattenBlocks([block]) : block;
+        return JSON.stringify(data, null, 2);
+    }
+    const displayBlocks = options.flat ? flattenBlocks([block]) : [block];
+    return blocksToMarkdown(displayBlocks);
+}
+/**
+ * Format search results for output
+ */
+export function formatSearchResults(results, options) {
+    if (options.json) {
+        return JSON.stringify(results, null, 2);
+    }
+    if (results.length === 0) {
+        return 'No results found.';
+    }
+    let output = `Found ${results.length} result(s):\n\n`;
+    results.forEach((result, index) => {
+        const pageInfo = result.page_title ? ` (${result.page_title})` : '';
+        output += `[${index + 1}] ${result.block_uid}${pageInfo}\n`;
+        output += `    ${result.content}\n\n`;
+    });
+    return output.trim();
+}
+/**
+ * Print debug information
+ */
+export function printDebug(label, data) {
+    console.error(`[DEBUG] ${label}:`, JSON.stringify(data, null, 2));
+}
+/**
+ * Print error message and exit
+ */
+export function exitWithError(message, code = 1) {
+    console.error(`Error: ${message}`);
+    process.exit(code);
+}

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

@@ -8,17 +8,42 @@ export class BlockRefSearchHandler extends BaseSearchHandler {
         this.params = params;
     }
     async execute() {
-        const { block_uid, page_title_uid } = this.params;
+        const { block_uid, title, page_title_uid } = this.params;
         // Get target page UID if provided
         let targetPageUid;
         if (page_title_uid) {
             targetPageUid = await SearchUtils.findPageByTitleOrUid(this.graph, page_title_uid);
         }
-        // Build query based on whether we're searching for references to a specific block
-        // or all block references within a page/graph
+        // Build query based on whether we're searching for references to a specific block,
+        // a page title, or all block references within a page/graph
         let queryStr;
         let queryParams;
-        if (block_uid) {
+        if (title) {
+            // Search for references to a page by title using :block/refs
+            if (targetPageUid) {
+                queryStr = `[:find ?block-uid ?block-str
+                    :in $ ?target-title ?page-uid
+                    :where [?target :node/title ?target-title]
+                           [?p :block/uid ?page-uid]
+                           [?b :block/page ?p]
+                           [?b :block/refs ?target]
+                           [?b :block/string ?block-str]
+                           [?b :block/uid ?block-uid]]`;
+                queryParams = [title, targetPageUid];
+            }
+            else {
+                queryStr = `[:find ?block-uid ?block-str ?page-title
+                    :in $ ?target-title
+                    :where [?target :node/title ?target-title]
+                           [?b :block/refs ?target]
+                           [?b :block/string ?block-str]
+                           [?b :block/uid ?block-uid]
+                           [?b :block/page ?p]
+                           [?p :node/title ?page-title]]`;
+                queryParams = [title];
+            }
+        }
+        else if (block_uid) {
             // Search for references to a specific block
             if (targetPageUid) {
                 queryStr = `[:find ?block-uid ?block-str
@@ -69,9 +94,11 @@ export class BlockRefSearchHandler extends BaseSearchHandler {
             const resolvedContent = await resolveRefs(this.graph, content);
             return [uid, resolvedContent, pageTitle];
         }));
-        const searchDescription = block_uid
-            ? `referencing block ((${block_uid}))`
-            : 'containing block references';
+        const searchDescription = title
+            ? `referencing [[${title}]]`
+            : block_uid
+                ? `referencing block ((${block_uid}))`
+                : 'containing block references';
         return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
     }
 }

package/build/tools/schemas.js

@@ -259,13 +259,17 @@ export const toolSchemas = {
     },
     roam_search_block_refs: {
         name: 'roam_search_block_refs',
-        description: 'Search for block references within a page or across the entire graph. Can search for references to a specific block or find all block references.',
+        description: 'Search for block references within a page or across the entire graph. Can search for references to a specific block, a page title, or find all block references.',
         inputSchema: {
             type: 'object',
             properties: {
                 block_uid: {
                     type: 'string',
-                    description: 'Optional: UID of the block to find references to'
+                    description: 'Optional: UID of the block to find references to (searches for ((uid)) patterns in text)'
+                },
+                title: {
+                    type: 'string',
+                    description: 'Optional: Page title to find references to (uses :block/refs for [[page]] and #tag links)'
                 },
                 page_title_uid: {
                     type: 'string',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -23,13 +23,13 @@
   "type": "module",
   "bin": {
     "roam-research-mcp": "build/index.js",
-    "roam-import": "build/cli/import-markdown.js"
+    "roam": "build/cli/roam.js"
   },
   "files": [
     "build"
   ],
   "scripts": {
-    "build": "echo \"Using custom instructions: .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md\" && tsc && cat Roam_Markdown_Cheatsheet.md .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md > build/Roam_Markdown_Cheatsheet.md && chmod 755 build/index.js build/cli/import-markdown.js",
+    "build": "echo \"Using custom instructions: .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md\" && tsc && cat Roam_Markdown_Cheatsheet.md .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md > build/Roam_Markdown_Cheatsheet.md && chmod 755 build/index.js build/cli/roam.js",
     "clean": "rm -rf build",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
@@ -44,6 +44,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.13.2",
     "@roam-research/roam-api-sdk": "^0.10.0",
+    "commander": "^14.0.2",
     "dotenv": "^16.4.7"
   },
   "devDependencies": {

package/build/cli/import-markdown.js

@@ -1,98 +0,0 @@
-#!/usr/bin/env node
-import { initializeGraph } from '@roam-research/roam-api-sdk';
-import { API_TOKEN, GRAPH_NAME } from '../config/environment.js';
-import { PageOperations } from '../tools/operations/pages.js';
-import { parseMarkdown } from '../markdown-utils.js';
-/**
- * Flatten nested MarkdownNode[] to flat array with absolute levels
- */
-function flattenNodes(nodes, baseLevel = 1) {
-    const result = [];
-    for (const node of nodes) {
-        result.push({
-            text: node.content,
-            level: baseLevel,
-            ...(node.heading_level && { heading: node.heading_level })
-        });
-        if (node.children.length > 0) {
-            result.push(...flattenNodes(node.children, baseLevel + 1));
-        }
-    }
-    return result;
-}
-/**
- * Read all input from stdin
- */
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(chunk);
-    }
-    return Buffer.concat(chunks).toString('utf-8');
-}
-/**
- * Show usage help
- */
-function showUsage() {
-    console.error('Usage: roam-import <page-title>');
-    console.error('');
-    console.error('Reads markdown from stdin and imports to Roam Research.');
-    console.error('');
-    console.error('Examples:');
-    console.error('  cat document.md | roam-import "Meeting Notes"');
-    console.error('  pbpaste | roam-import "Ideas"');
-    console.error('  echo "- Item 1\\n- Item 2" | roam-import "Quick Note"');
-    console.error('');
-    console.error('Environment variables required:');
-    console.error('  ROAM_API_TOKEN   Your Roam Research API token');
-    console.error('  ROAM_GRAPH_NAME  Your Roam graph name');
-}
-async function main() {
-    // Parse CLI arguments
-    const args = process.argv.slice(2);
-    const pageTitle = args[0];
-    if (!pageTitle || pageTitle === '--help' || pageTitle === '-h') {
-        showUsage();
-        process.exit(pageTitle ? 0 : 1);
-    }
-    // Check if stdin is a TTY (no input piped)
-    if (process.stdin.isTTY) {
-        console.error('Error: No input received. Pipe markdown content to this command.');
-        console.error('');
-        showUsage();
-        process.exit(1);
-    }
-    // Read markdown from stdin
-    const markdownContent = await readStdin();
-    if (!markdownContent.trim()) {
-        console.error('Error: Empty input received.');
-        process.exit(1);
-    }
-    // Initialize Roam graph
-    const graph = initializeGraph({
-        token: API_TOKEN,
-        graph: GRAPH_NAME
-    });
-    // Parse markdown to nodes
-    const nodes = parseMarkdown(markdownContent);
-    // Flatten nested structure to content blocks
-    const contentBlocks = flattenNodes(nodes);
-    if (contentBlocks.length === 0) {
-        console.error('Error: No content blocks parsed from input.');
-        process.exit(1);
-    }
-    // Create page with content
-    const pageOps = new PageOperations(graph);
-    const result = await pageOps.createPage(pageTitle, contentBlocks);
-    if (result.success) {
-        console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
-    }
-    else {
-        console.error(`Failed to create page '${pageTitle}'`);
-        process.exit(1);
-    }
-}
-main().catch((error) => {
-    console.error(`Error: ${error.message}`);
-    process.exit(1);
-});