roam-research-mcp 0.36.0 → 1.3.2

package/README.md

@@ -7,18 +7,17 @@
 [![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), HTTP Stream, and Server-Sent Events (SSE) communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
+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 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>
 
 ## Installation and Usage
 
-This MCP server supports three primary communication methods:
+This MCP server supports two primary communication methods:
 
 1.  **Stdio (Standard Input/Output):** Ideal for local inter-process communication, command-line tools, and direct integration with applications running on the same machine. This is the default communication method when running the server directly.
 2.  **HTTP Stream:** Provides network-based communication, suitable for web-based clients, remote applications, or scenarios requiring real-time updates over HTTP. The HTTP Stream endpoint runs on port `8088` by default.
-3.  **SSE (Server-Sent Events):** A transport for legacy clients that require SSE. The SSE endpoint runs on port `8087` by default. (NOTE: ⚠️ DEPRECATED: The SSE Transport has been deprecated as of MCP specification version 2025-03-26. HTTP Stream Transport preferred.)
 
 ### Running with Stdio
 
@@ -41,16 +40,16 @@ npm start
 
 ### Running with HTTP Stream
 
-To run the server with HTTP Stream or SSE support, you can either:
+To run the server with HTTP Stream support, you can either:
 
-1.  **Use the default ports:** Run `npm start` after building (as shown above). The server will automatically listen on port `8088` for HTTP Stream and `8087` for SSE.
-2.  **Specify custom ports:** Set the `HTTP_STREAM_PORT` and/or `SSE_PORT` environment variables before starting the server.
+1.  **Use the default ports:** Run `npm start` after building (as shown above). The server will automatically listen on port `8088` for HTTP Stream.
+2.  **Specify custom ports:** Set the `HTTP_STREAM_PORT` environment variable before starting the server.
 
     ```bash
-    HTTP_STREAM_PORT=9000 SSE_PORT=9001 npm start
+    HTTP_STREAM_PORT=9000 npm start
     ```
 
-    Or, if using a `.env` file, add `HTTP_STREAM_PORT=9000` and/or `SSE_PORT=9001` to it.
+    Or, if using a `.env` file, add `HTTP_STREAM_PORT=9000` to it.
 
 ## Docker
 
@@ -66,16 +65,15 @@ docker build -t roam-research-mcp .
 
 ### Run the Docker Container
 
-To run the Docker container and map the necessary ports, you must also provide the required environment variables. Use the `-e` flag to pass `ROAM_API_TOKEN`, `ROAM_GRAPH_NAME`, and optionally `MEMORIES_TAG`, `HTTP_STREAM_PORT`, and `SSE_PORT`:
+To run the Docker container and map the necessary ports, you must also provide the required environment variables. Use the `-e` flag to pass `ROAM_API_TOKEN`, `ROAM_GRAPH_NAME`, and optionally `MEMORIES_TAG` and `HTTP_STREAM_PORT`:
 
 ```bash
-docker run -p 3000:3000 -p 8088:8088 -p 8087:8087 \
+docker run -p 3000:3000 -p 8088:8088 \
   -e ROAM_API_TOKEN="your-api-token" \
   -e ROAM_GRAPH_NAME="your-graph-name" \
   -e MEMORIES_TAG="#[[LLM/Memories]]" \
   -e CUSTOM_INSTRUCTIONS_PATH="/path/to/your/custom_instructions_file.md" \
   -e HTTP_STREAM_PORT="8088" \
-  -e SSE_PORT="8087" \
   roam-research-mcp
 ```
 
@@ -85,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:
@@ -111,25 +162,26 @@ 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).
-10. `roam_search_by_text`: Search for blocks containing specific text.
-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.
-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.
-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`.)
 
 **Deprecated Tools**:
-The following tools have been deprecated as of `v1.36.0` in favor of the more powerful and flexible `roam_process_batch_actions`:
+The following tools have been deprecated as of `v0.36.2` in favor of the more powerful and flexible `roam_process_batch_actions`:
 
 - `roam_create_block`: Use `roam_process_batch_actions` with the `create-block` action.
 - `roam_update_block`: Use `roam_process_batch_actions` with the `update-block` action.
@@ -176,20 +228,6 @@ Please note that while the `roam_process_batch_actions` tool can set block headi
 
 ---
 
-## Propose Improvements
-
-### Pagination for Search Tools
-
-The `roam_search_for_tag` and `roam_search_by_text` tools now support `limit` and `offset` parameters, enabling basic pagination. To achieve full, robust pagination (e.g., retrieving "page 2" of results), the client consuming these tools would need to:
-
-1.  Make an initial call with `limit` and `offset=0` to get the first set of results and the `total_count`.
-2.  Calculate the total number of pages based on `total_count` and the desired `limit`.
-3.  Make subsequent calls, incrementing the `offset` by `limit` for each "page" of results.
-
-Example: To get the second page of 10 results, the call would be `roam_search_by_text(text: "your query", limit: 10, offset: 10)`.
-
----
-
 ## Example Prompts
 
 Here are some examples of how to creatively use the Roam tool in an LLM to interact with your Roam graph, particularly leveraging `roam_process_batch_actions` for complex operations.
@@ -232,12 +270,25 @@ 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"
+```
+
 ---
 
 ## Setup
@@ -260,7 +311,6 @@ This demonstrates moving a block from one location to another and simultaneously
    MEMORIES_TAG='#[[LLM/Memories]]'
    CUSTOM_INSTRUCTIONS_PATH='/path/to/your/custom_instructions_file.md'
    HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication
-   SSE_PORT=8087 # Or your desired port for SSE communication
    ```
 
    Option 2: Using MCP settings (Alternative method)
@@ -280,8 +330,7 @@ This demonstrates moving a block from one location to another and simultaneously
            "ROAM_GRAPH_NAME": "your-graph-name",
            "MEMORIES_TAG": "#[[LLM/Memories]]",
            "CUSTOM_INSTRUCTIONS_PATH": "/path/to/your/custom_instructions_file.md",
-           "HTTP_STREAM_PORT": "8088",
-           "SSE_PORT": "8087"
+           "HTTP_STREAM_PORT": "8088"
          }
        }
      }