roam-research-mcp 0.12.3 → 0.17.0

package/README.md

@@ -6,6 +6,8 @@
 
 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.
 
+<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>
+
 ## Installation
 
 You can install the package globally:
@@ -25,13 +27,19 @@ npm run build
 
 ## Features
 
-The server provides five powerful tools for interacting with Roam Research:
+The server provides eleven powerful tools for interacting with Roam Research:
 
 1. `roam_fetch_page_by_title`: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep
 2. `roam_create_page`: Create new pages with optional content
 3. `roam_create_block`: Create new blocks in a page (defaults to today's daily page)
 4. `roam_import_markdown`: Import nested markdown content under specific blocks
 5. `roam_add_todo`: Add multiple todo items to today's daily page with checkbox syntax
+6. `roam_create_outline`: Create hierarchical outlines with proper nesting and structure
+7. `roam_search_block_refs`: Search for block references within pages or across the graph
+8. `roam_search_hierarchy`: Navigate and search through block parent-child relationships
+9. `find_pages_modified_today`: Find all pages that have been modified since midnight today
+10. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page
+11. `roam_update_block`: Update block content with direct text or pattern-based transformations
 
 ## Setup
 
@@ -158,6 +166,59 @@ Returns:
 }
 ```
 
+### Create Outline
+
+Create a hierarchical outline with proper nesting and structure:
+
+```typescript
+use_mcp_tool roam-research roam_create_outline {
+  "outline": [
+    {
+      "text": "I. Top Level",
+      "level": 1
+    },
+    {
+      "text": "A. Second Level",
+      "level": 2
+    },
+    {
+      "text": "1. Third Level",
+      "level": 3
+    }
+  ],
+  "page_title_uid": "optional-target-page",
+  "block_text_uid": "optional-header-text"
+}
+```
+
+Features:
+
+- Create complex outlines with up to 10 levels of nesting
+- Validate outline structure and content
+- Maintain proper parent-child relationships
+- Optional header block for the outline
+- Defaults to today's daily page if no page specified
+- Efficient batch operations for creating blocks
+
+Parameters:
+
+- `outline`: Array of outline items, each with:
+  - `text`: Content of the outline item (required)
+  - `level`: Nesting level (1-10, required)
+- `page_title_uid`: Target page title or UID (optional, defaults to today's page)
+- `block_text_uid`: Header text for the outline (optional)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "page_uid": "target-page-uid",
+  "parent_uid": "header-block-uid",
+  "created_uids": ["uid1", "uid2", ...]
+}
+```
+
 ### Add Todo Items
 
 Add one or more todo items to today's daily page:
@@ -224,6 +285,212 @@ Parameters:
 - `parent_string`: Exact string content of the parent block (must provide either page_uid or page_title)
 - `order`: Where to add the content ("first" or "last", defaults to "first")
 
+### Search Block References
+
+Search for block references within pages or across the entire graph:
+
+```typescript
+use_mcp_tool roam-research roam_search_block_refs {
+  "block_uid": "optional-block-uid",
+  "page_title_uid": "optional-page-title-or-uid"
+}
+```
+
+Features:
+
+- Find all references to a specific block
+- Search for any block references within a page
+- Search across the entire graph
+- Supports both direct and indirect references
+- Includes block content and location context
+
+Parameters:
+
+- `block_uid`: UID of the block to find references to (optional)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "referenced-block-uid",
+      "content": "Block content with ((reference))",
+      "page_title": "Page containing reference"
+    }
+  ],
+  "message": "Found N block(s) referencing..."
+}
+```
+
+### Search By Text
+
+Search for blocks containing specific text across all pages or within a specific page:
+
+```typescript
+use_mcp_tool roam-research roam_search_by_text {
+  "text": "search text",
+  "page_title_uid": "optional-page-title-or-uid",
+  "case_sensitive": false
+}
+```
+
+Features:
+
+- Search for any text across all blocks in the graph
+- Optional page-scoped search
+- Case-sensitive or case-insensitive search
+- Returns block content with page context
+- Efficient text matching using Datalog queries
+
+Parameters:
+
+- `text`: The text to search for (required)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+- `case_sensitive`: Whether to perform a case-sensitive search (optional, default: false)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "matching-block-uid",
+      "content": "Block content containing search text",
+      "page_title": "Page containing block"
+    }
+  ],
+  "message": "Found N block(s) containing \"search text\""
+}
+```
+
+### Update Block Content
+
+Update a block's content using either direct text replacement or pattern-based transformations:
+
+```typescript
+use_mcp_tool roam-research roam_update_block {
+  "block_uid": "target-block-uid",
+  "content": "New block content"
+}
+```
+
+Or use pattern-based transformation:
+
+```typescript
+use_mcp_tool roam-research roam_update_block {
+  "block_uid": "target-block-uid",
+  "transform_pattern": {
+    "find": "\\bPython\\b",
+    "replace": "[[Python]]",
+    "global": true
+  }
+}
+```
+
+Features:
+
+- Two update modes:
+  - Direct content replacement
+  - Pattern-based transformation using regex
+- Verify block existence before updating
+- Return updated content in response
+- Support for global or single-match replacements
+- Preserve block relationships and metadata
+
+Parameters:
+
+- `block_uid`: UID of the block to update (required)
+- `content`: New content for the block (if using direct replacement)
+- `transform_pattern`: Pattern for transforming existing content:
+  - `find`: Text or regex pattern to find
+  - `replace`: Text to replace with
+  - `global`: Whether to replace all occurrences (default: true)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "content": "Updated block content"
+}
+```
+
+### Find Pages Modified Today
+
+Find all pages that have been modified since midnight today:
+
+```typescript
+use_mcp_tool roam-research find_pages_modified_today {}
+```
+
+Features:
+
+- Tracks all modifications made to pages since midnight
+- Detects changes at any level in the block hierarchy
+- Returns unique list of modified page titles
+- Includes count of modified pages
+- No parameters required
+
+Returns:
+
+```json
+{
+  "success": true,
+  "pages": ["Page 1", "Page 2"],
+  "message": "Found 2 page(s) modified today"
+}
+```
+
+### Search Block Hierarchy
+
+Navigate and search through block parent-child relationships:
+
+```typescript
+use_mcp_tool roam-research roam_search_hierarchy {
+  "parent_uid": "optional-parent-block-uid",
+  "child_uid": "optional-child-block-uid",
+  "page_title_uid": "optional-page-title-or-uid",
+  "max_depth": 3
+}
+```
+
+Features:
+
+- Search up or down the block hierarchy
+- Find children of a specific block
+- Find parents of a specific block
+- Configure search depth (1-10 levels)
+- Optional page scope filtering
+- Includes depth information for each result
+
+Parameters:
+
+- `parent_uid`: UID of the block to find children of (required if searching down)
+- `child_uid`: UID of the block to find parents of (required if searching up)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+- `max_depth`: How many levels deep to search (optional, default: 1, max: 10)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "related-block-uid",
+      "content": "Block content",
+      "depth": 2,
+      "page_title": "Page containing block"
+    }
+  ],
+  "message": "Found N block(s) as children/parents..."
+}
+```
+
 ## Error Handling
 
 The server provides comprehensive error handling for common scenarios:
@@ -240,6 +507,7 @@ The server provides comprehensive error handling for common scenarios:
   - Block not found by string match
   - Invalid markdown format
   - Missing required parameters
+  - Invalid outline structure or content
 
 Each error response includes:
 
@@ -259,6 +527,7 @@ The server is built with TypeScript and includes:
 - Daily page integration
 - Detailed debug logging
 - Efficient batch operations
+- Hierarchical outline creation
 
 To modify or extend the server:
 

package/build/config/environment.js

@@ -0,0 +1,44 @@
+import * as dotenv from 'dotenv';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+// Get the project root from the script path
+const scriptPath = process.argv[1]; // Full path to the running script
+const projectRoot = dirname(dirname(scriptPath)); // Go up two levels from build/index.js
+// Try to load .env from project root
+const envPath = join(projectRoot, '.env');
+if (existsSync(envPath)) {
+    dotenv.config({ path: envPath });
+}
+// Required environment variables
+const API_TOKEN = process.env.ROAM_API_TOKEN;
+const GRAPH_NAME = process.env.ROAM_GRAPH_NAME;
+// Validate environment variables
+if (!API_TOKEN || !GRAPH_NAME) {
+    const missingVars = [];
+    if (!API_TOKEN)
+        missingVars.push('ROAM_API_TOKEN');
+    if (!GRAPH_NAME)
+        missingVars.push('ROAM_GRAPH_NAME');
+    throw new Error(`Missing required environment variables: ${missingVars.join(', ')}\n\n` +
+        'Please configure these variables either:\n' +
+        '1. In your MCP settings file:\n' +
+        '   - For Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json\n' +
+        '   - For Claude: ~/Library/Application Support/Claude/claude_desktop_config.json\n\n' +
+        '   Example configuration:\n' +
+        '   {\n' +
+        '     "mcpServers": {\n' +
+        '       "roam-research": {\n' +
+        '         "command": "node",\n' +
+        '         "args": ["/path/to/roam-research/build/index.js"],\n' +
+        '         "env": {\n' +
+        '           "ROAM_API_TOKEN": "your-api-token",\n' +
+        '           "ROAM_GRAPH_NAME": "your-graph-name"\n' +
+        '         }\n' +
+        '       }\n' +
+        '     }\n' +
+        '   }\n\n' +
+        '2. Or in a .env file in the roam-research directory:\n' +
+        '   ROAM_API_TOKEN=your-api-token\n' +
+        '   ROAM_GRAPH_NAME=your-graph-name');
+}
+export { API_TOKEN, GRAPH_NAME };