roam-research-mcp 1.6.0 → 2.4.3

package/README.md

@@ -1,13 +1,13 @@
-![](./roam-research-mcp-image.jpeg)
+![Roam Research MCP + CLI](./roam-research-mcp-header.png)
 
-# Roam Research MCP Server
+# Roam Research MCP + CLI
 
 [![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)
-[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![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 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 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 multi-graph configurations, write protection, standard input/output (stdio) and HTTP Stream communication. (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>
@@ -85,7 +85,9 @@ docker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp
 
 ## Standalone CLI: `roam`
 
-A standalone command-line tool for interacting with Roam Research directly, without running the MCP server. Provides four subcommands: `get`, `search`, `save`, and `refs`.
+A standalone command-line tool for interacting with Roam Research directly, without running the MCP server. Provides eight subcommands: `get`, `search`, `save`, `refs`, `update`, `batch`, `rename`, and `status`.
+
+All content creation, update, and retrieval commands support **standard input (stdin) piping**, allowing for powerful automation workflows (e.g., `cat notes.md | roam save`, `roam search "query" | roam get`).
 
 ### Installation
 
@@ -111,7 +113,7 @@ Configure via `.env` file in the project root or set as environment variables.
 
 ---
 
-### `roam get` - Fetch pages or blocks
+### `roam get` - Fetch pages, blocks, or TODOs
 
 Fetch content from Roam and output as markdown or JSON.
 
@@ -132,6 +134,18 @@ roam get "Daily Notes" --depth 2
 # Flatten hierarchy
 roam get "Daily Notes" --flat
 
+# Fetch TODO items
+roam get --todo
+
+# Fetch DONE items
+roam get --done
+
+# Filter TODOs by page
+roam get --todo -p "January 2nd, 2026"
+
+# Include/exclude filter
+roam get --todo -i "urgent,important" -e "someday"
+
 # Debug mode
 roam get "Daily Notes" --debug
 ```
@@ -141,6 +155,11 @@ roam get "Daily Notes" --debug
 - `--depth <n>` - Child levels to fetch (default: 4)
 - `--refs <n>` - Block ref expansion depth (default: 1)
 - `--flat` - Flatten hierarchy to single-level list
+- `--todo` - Fetch TODO items
+- `--done` - Fetch DONE items
+- `-p, --page <title>` - Filter TODOs/DONEs by page title
+- `-i, --include <terms>` - Include only items containing these terms (comma-separated)
+- `-e, --exclude <terms>` - Exclude items containing these terms (comma-separated)
 - `--debug` - Show query metadata
 
 ---
@@ -186,9 +205,9 @@ roam search "keyword" --json
 
 ---
 
-### `roam save` - Import markdown
+### `roam save` - Import markdown or create TODOs
 
-Import markdown content to Roam, creating or updating pages.
+Import markdown content to Roam, creating or updating pages, or add TODO items.
 
 ```bash
 # From a file (title derived from filename)
@@ -211,11 +230,21 @@ roam save --title "Quick Note" << EOF
 - Item 2
   - Nested item
 EOF
+
+# Create a TODO item on today's daily page
+roam save --todo "Buy groceries"
+
+# Create multiple TODOs from stdin (newline-separated)
+echo -e "Task 1\nTask 2\nTask 3" | roam save --todo
+
+# Pipe TODO list from file
+cat todos.txt | roam save --todo
 ```
 
 **Options:**
 - `--title <title>` - Page title (defaults to filename without `.md`)
 - `--update` - Update existing page using smart diff (preserves block UIDs)
+- `-t, --todo [text]` - Add a TODO item to today's daily page (text or stdin)
 - `--debug` - Show debug information
 
 **Features:**
@@ -223,6 +252,7 @@ EOF
 - Automatically links the new page from today's daily page
 - Converts standard markdown to Roam-flavored markdown
 - Smart diff mode (`--update`) preserves block UIDs for existing content
+- TODO mode creates `{{[[TODO]]}}` items on the daily page
 
 ---
 
@@ -278,6 +308,103 @@ JSON output for programmatic use:
 
 ---
 
+### `roam batch` - Execute multiple operations in one API call
+
+Execute multiple operations in a single batch API call to reduce rate limiting issues.
+
+```bash
+# From a JSON file
+roam batch commands.json
+
+# From stdin
+cat commands.json | roam batch
+
+# Dry run (validate without executing)
+roam batch --dry-run commands.json
+
+# With debug output
+roam batch --debug commands.json
+```
+
+**Command Format:**
+
+Input is a JSON array of command objects:
+
+```json
+[
+  { "command": "create", "params": { "text": "Parent block", "parent": "pageUid", "as": "p1" } },
+  { "command": "create", "params": { "text": "Child block", "parent": "{{p1}}" } },
+  { "command": "todo", "params": { "text": "Task item" } },
+  { "command": "codeblock", "params": { "parent": "{{p1}}", "language": "ts", "code": "const x = 1;" } }
+]
+```
+
+**Supported Commands:**
+
+| Command | Description |
+|---------|-------------|
+| `create` | Create a block |
+| `update` | Update block content |
+| `delete` | Delete a block |
+| `move` | Move block to new location |
+| `todo` | Create TODO item |
+| `table` | Create table structure |
+| `outline` | Create nested outline |
+| `remember` | Create tagged memory |
+| `page` | Create page with content |
+| `codeblock` | Create code block |
+
+**Features:**
+
+- Placeholder references (`{{name}}`) for cross-command dependencies
+- Automatic page title → UID resolution
+- Daily page auto-resolution for `todo` and `remember`
+- Level-based hierarchy for `outline` command
+- `--dry-run` mode for validation
+
+**Options:**
+- `--dry-run` - Validate and show planned actions without executing
+- `--debug` - Show debug information
+- `-g, --graph <name>` - Target graph (multi-graph mode)
+- `--write-key <key>` - Write confirmation key
+
+See [docs/batch-cli-spec.md](docs/batch-cli-spec.md) for full specification.
+
+---
+
+### `roam status` - Show available graphs
+
+Display configured graphs and their connection status.
+
+```bash
+# Show available graphs
+roam status
+
+# Test connectivity to all graphs
+roam status --ping
+
+# Output as JSON
+roam status --json
+```
+
+**Example Output:**
+
+```
+Roam Research MCP v2.4.0
+
+Graphs:
+  • personal (default)  ✓ connected
+  • work [protected]    ✓ connected
+
+Write-protected graphs require --write-key flag for modifications.
+```
+
+**Options:**
+- `--ping` - Test connection to each graph
+- `--json` - Output as JSON for scripting
+
+---
+
 ## To Test
 
 Run [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build using the provided npm script:
@@ -304,7 +431,7 @@ 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 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.
+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. Automatically adds a "Processed: [[date]]" block at the end of the page linking to today's daily 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`.)
@@ -316,12 +443,13 @@ The server provides powerful tools for interacting with Roam Research:
 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`.)
+15. `roam_remember`: Add a memory or piece of information to remember. Supports optional `heading` parameter to nest under a specific heading on the daily page (created if missing), or `parent_uid` to nest under a specific block. Use `include_memories_tag: false` to omit the MEMORIES_TAG. (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.
+21. `roam_move_block`: Move a block to a new location (different parent or position). Convenience wrapper around `roam_process_batch_actions` for single block moves. Parameters: `block_uid` (required), `parent_uid` (required), `order` (optional, defaults to "last").
 
 **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`:
@@ -462,9 +590,13 @@ The tool will match existing blocks by content, update changed text, add new blo
    - Create a new token
 
 2. Configure the environment variables:
-   You have two options for configuring the required environment variables:
 
-   Option 1: Using a .env file (Recommended for development)
+   ### Single Graph Mode (Default)
+
+   For most users with one Roam graph, use the simple configuration:
+
+   **Option 1: Using a .env file (Recommended for development)**
+
    Create a `.env` file in the roam-research directory:
 
    ```
@@ -475,7 +607,8 @@ The tool will match existing blocks by content, update changed text, add new blo
    HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication
    ```
 
-   Option 2: Using MCP settings (Alternative method)
+   **Option 2: Using MCP settings (Alternative method)**
+
    Add the configuration to your MCP settings file. Note that you may need to update the `args` to `["/path/to/roam-research-mcp/build/index.js"]` if you are running the server directly.
 
    - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
@@ -501,6 +634,62 @@ The tool will match existing blocks by content, update changed text, add new blo
 
    Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.
 
+   ---
+
+   ### Multi-Graph Mode (v2.0.0+)
+
+   For users with multiple Roam graphs, you can configure a single MCP server instance to connect to all of them. This is more token-efficient than running multiple server instances.
+
+   **Configuration:**
+
+   ```json
+   ROAM_GRAPHS="{\"personal\":{\"token\":\"roam-graph-token-xxx\",\"graph\":\"my-personal-graph\"},\"work\":{\"token\":\"roam-graph-token-yyy\",\"graph\":\"company-graph\",\"write_key\":\"confirm-work-write\"}}"
+   ROAM_DEFAULT_GRAPH=personal
+   ```
+
+   | Field | Required | Description |
+   |-------|----------|-------------|
+   | `token` | Yes | Roam API token for this graph |
+   | `graph` | Yes | Roam graph name |
+   | `write_key` | No | Required confirmation string for writes to non-default graphs |
+
+   **Usage in Tools:**
+
+   All tools accept optional `graph` and `write_key` parameters:
+
+   ```json
+   {
+     "title": "My Page",
+     "graph": "work",
+     "write_key": "confirm-work-write"
+   }
+   ```
+
+   - **Read operations**: Can target any graph using the `graph` parameter
+   - **Write operations on default graph**: Work without additional parameters
+   - **Write operations on non-default graphs**: Require the `write_key` if configured
+
+   **CLI Usage:**
+
+   All CLI commands support the `-g, --graph` flag:
+
+   ```bash
+   # Read from work graph
+   roam get "Meeting Notes" -g work
+
+   # Write to work graph (requires --write-key if configured)
+   roam save notes.md -g work --write-key "confirm-work-write"
+   ```
+
+   **Safety Model:**
+
+   The `write_key` serves as a confirmation gate (not a secret) to prevent accidental writes to non-default graphs. When a write is attempted without the required key, the error message reveals the expected key:
+
+   ```
+   Write to "work" graph requires write_key confirmation.
+   Provide write_key: "confirm-work-write" to proceed.
+   ```
+
 3. Build the server (make sure you're in the root directory of the MCP):
 
    Note: Customize 'Roam_Markdown_Cheatsheet.md' with any notes and preferences specific to your graph BEFORE building.