roam-research-mcp 1.0.0 → 1.4.0

package/README.md

@@ -83,6 +83,59 @@ 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
+
+A standalone command-line tool for importing markdown content directly into Roam Research, without running the MCP server.
+
+### Usage
+
+```bash
+# From a file
+cat document.md | roam-import "Meeting Notes"
+
+# From clipboard (macOS)
+pbpaste | roam-import "Ideas"
+
+# From here-doc
+roam-import "Quick Note" << EOF
+# Heading
+- Item 1
+- Item 2
+  - Nested item
+EOF
+```
+
+### Features
+
+- Reads markdown from stdin
+- 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)
+
+### Installation
+
+After building the project, make the command globally available:
+
+```bash
+npm link
+```
+
+Or run directly without linking:
+
+```bash
+cat document.md | node build/cli/import-markdown.js "Page Title"
+```
+
+### 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.
+
+---
+
 ## To Test
 
 Run [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build using the provided npm script:
@@ -109,22 +162,24 @@ The server provides powerful tools for interacting with Roam Research:
 
 1. `roam_fetch_page_by_title`: Fetch page content by title. Returns content in the specified format.
 2. `roam_fetch_block_with_children`: Fetch a block by its UID along with its hierarchical children down to a specified depth. Automatically handles `((UID))` formatting.
-3. `roam_create_page`: Create new pages with optional content and headings. Now creates a block on the daily page linking to the newly created page.
-4. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
-5. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
-6. `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`.)
-7. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
-8. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
-9. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight), with pagination and sorting options.
-10. `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.
-11. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
-12. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
-13. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby or exclude blocks with a specific tag. This tool supports pagination via the `limit` and `offset` parameters.
-14. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
-15. `roam_recall`: Retrieve all stored memories.
-16. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. Now supports client-side regex filtering for enhanced post-query processing. Optimal for complex filtering (including regex), highly complex boolean logic, arbitrary sorting criteria, and proximity search.
-17. `roam_markdown_cheatsheet`: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if `CUSTOM_INSTRUCTIONS_PATH` environment variable is set.
-18. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
+3. `roam_create_page`: Create new pages with optional content and headings. **Now supports mixed content types** - content array can include both text blocks and tables in a single call using `{type: "table", headers, rows}` format. Creates a block on the daily page linking to the newly created page.
+4. `roam_create_table`: Create a properly formatted Roam table with specified headers and rows. Abstracts Roam's complex nested table structure, validates row/column consistency, and handles empty cells automatically.
+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.
+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.
+12. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
+13. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
+14. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby or exclude blocks with a specific tag. This tool supports pagination via the `limit` and `offset` parameters.
+15. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
+16. `roam_recall`: Retrieve all stored memories.
+17. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. Now supports client-side regex filtering for enhanced post-query processing. Optimal for complex filtering (including regex), highly complex boolean logic, arbitrary sorting criteria, and proximity search.
+18. `roam_markdown_cheatsheet`: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if `CUSTOM_INSTRUCTIONS_PATH` environment variable is set.
+19. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. **Now includes pre-validation** that catches errors before API execution, with structured error responses and automatic rate limit retry with exponential backoff. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
+20. `roam_update_page_markdown`: Update an existing page with new markdown content using smart diff. **Preserves block UIDs** where possible, keeping references intact across the graph. Uses three-phase matching (exact text → normalized → position fallback) to generate minimal operations. Supports `dry_run` mode to preview changes. Ideal for syncing external markdown files, AI-assisted content updates, and batch modifications without losing block references.
 
 **Deprecated Tools**:
 The following tools have been deprecated as of `v0.36.2` in favor of the more powerful and flexible `roam_process_batch_actions`:
@@ -216,12 +271,44 @@ This demonstrates moving a block from one location to another and simultaneously
 
 ### Example 4: Making a Table
 
-This demonstrates moving a block from one location to another and simultaneously updating its content.
+This demonstrates creating a standalone table on a page.
 
 ```
 "In Roam, add a new table on the page "Fruity Tables" that compares four types of fruits: apples, oranges, grapes, and dates. Choose randomly four areas to compare."
 ```
 
+### Example 5: Creating a Page with Mixed Content (Text + Table)
+
+This demonstrates creating a new page with both text blocks and a table in a single call using `roam_create_page`.
+
+```
+"Create a new Roam page titled 'Product Comparison' with:
+- A heading 'Overview'
+- An introduction paragraph explaining the comparison
+- A comparison table with columns: Feature, Plan A, Plan B
+  - Rows: Price ($10, $20), Storage (10GB, 50GB), Support (Email, 24/7)
+- A conclusion section"
+```
+
+### Example 6: Updating a Page with Smart Diff
+
+This demonstrates updating an existing page while preserving block UIDs (and therefore block references across the graph).
+
+```
+"Update the 'Project Alpha Planning' page with this revised content, preserving block references:
+- Overview (keep existing UID)
+  - Updated Goals section
+  - Revised Scope with new details
+- Team Members
+  - John Doe (Senior Dev)
+  - Jane Smith (PM)
+  - New hire: Bob Wilson
+- Updated Timeline
+- Remove the old 'Deadlines' section"
+```
+
+The tool will match existing blocks by content, update changed text, add new blocks, and remove deleted ones - all while keeping UIDs stable for blocks that still exist.
+
 ---
 
 ## Setup