roam-research-mcp 0.22.1 → 0.23.1

package/README.md

@@ -5,7 +5,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. (A WORK-IN-PROGRESS)
+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 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>
 
@@ -28,7 +28,7 @@ npm run build
 
 ## Features
 
-The server provides fourteen powerful tools for interacting with Roam Research:
+The server provides 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
@@ -44,7 +44,8 @@ The server provides fourteen powerful tools for interacting with Roam Research:
 12. `roam_search_by_date`: Search for blocks and pages based on creation or modification dates
 13. `roam_search_for_tag`: Search for blocks containing specific tags with optional filtering by nearby tags
 14. `roam_remember`: Store and categorize memories or information with automatic tagging
-15. `roam_recall`: Recall memories of blocks marked with tag MEMORIES_TAG (see below) or blocks on page title of the same name.
+15. `roam_recall`: Recall memories of blocks marked with tag MEMORIES_TAG (see below) or blocks on page title of the same name
+16. `roam_datomic_query`: Execute custom Datalog queries on the Roam graph for advanced data retrieval and analysis
 
 ## Setup
 
@@ -64,7 +65,6 @@ The server provides fourteen powerful tools for interacting with Roam Research:
    ROAM_API_TOKEN=your-api-token
    ROAM_GRAPH_NAME=your-graph-name
    MEMORIES_TAG='#[[LLM/Memories]]'
-   PROFILE_PAGE='LLM/Profile' (not yet implemented)
    ```
 
    Option 2: Using MCP settings (Alternative method)
@@ -82,8 +82,7 @@ The server provides fourteen powerful tools for interacting with Roam Research:
          "env": {
            "ROAM_API_TOKEN": "your-api-token",
            "ROAM_GRAPH_NAME": "your-graph-name",
-           "MEMORIES_TAG": "#[[LLM/Memories]]",
-           "PROFILE_PAGE": "LLM/Profile"
+           "MEMORIES_TAG": "#[[LLM/Memories]]"
          }
        }
      }
@@ -567,6 +566,85 @@ Returns:
 }
 ```
 
+### Execute Datomic Queries
+
+Execute custom Datalog queries on your Roam graph for advanced data retrieval and analysis:
+
+```typescript
+use_mcp_tool roam-research roam_datomic_query {
+  "query": "[:find (count ?p)\n :where [?p :node/title]]",
+  "inputs": []
+}
+```
+
+Features:
+
+- Direct access to Roam's query engine
+- Support for all Datalog query features:
+  - Complex pattern matching
+  - Aggregation functions (count, sum, max, min, avg, distinct)
+  - String operations (includes?, starts-with?, ends-with?)
+  - Logical operations (<, >, <=, >=, =, not=)
+  - Rules for recursive queries
+- Case-sensitive and case-insensitive search capabilities
+- Efficient querying across the entire graph
+
+Parameters:
+
+- `query`: The Datalog query to execute (required)
+- `inputs`: Optional array of input parameters for the query
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "content": "[result data]",
+      "block_uid": "",
+      "page_title": ""
+    }
+  ],
+  "message": "Query executed successfully. Found N results."
+}
+```
+
+Example Queries:
+
+1. Count all pages:
+
+```clojure
+[:find (count ?p)
+ :where [?p :node/title]]
+```
+
+2. Case-insensitive text search:
+
+```clojure
+[:find ?string ?title
+ :where
+ [?b :block/string ?string]
+ [(clojure.string/lower-case ?string) ?lower]
+ [(clojure.string/includes? ?lower "search term")]
+ [?b :block/page ?p]
+ [?p :node/title ?title]]
+```
+
+3. Find blocks modified after a date:
+
+```clojure
+[:find ?block_ref ?string
+ :in $ ?start_of_day
+ :where
+ [?b :edit/time ?time]
+ [(> ?time ?start_of_day)]
+ [?b :block/uid ?block_ref]
+ [?b :block/string ?string]]
+```
+
+See Roam_Research_Datalog_Cheatsheet.md for more query examples and syntax documentation.
+
 ### Search Block Hierarchy
 
 Navigate and search through block parent-child relationships:

package/build/search/datomic-search.js

@@ -0,0 +1,31 @@
+import { q } from '@roam-research/roam-api-sdk';
+import { BaseSearchHandler } from './types.js';
+export class DatomicSearchHandler extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        try {
+            // Execute the datomic query using the Roam API
+            const results = await q(this.graph, this.params.query, this.params.inputs || []);
+            return {
+                success: true,
+                matches: results.map(result => ({
+                    content: JSON.stringify(result),
+                    block_uid: '', // Datomic queries may not always return block UIDs
+                    page_title: '' // Datomic queries may not always return page titles
+                })),
+                message: `Query executed successfully. Found ${results.length} results.`
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                matches: [],
+                message: `Failed to execute query: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+}

package/build/search/index.js

@@ -5,3 +5,4 @@ export * from './status-search.js';
 export * from './block-ref-search.js';
 export * from './hierarchy-search.js';
 export * from './text-search.js';
+export * from './datomic-search.js';

package/build/server/roam-server.js

@@ -37,7 +37,8 @@ export class RoamServer {
                     roam_search_by_text: {},
                     roam_update_block: {},
                     roam_update_blocks: {},
-                    roam_search_by_date: {}
+                    roam_search_by_date: {},
+                    roam_datomic_query: {}
                 },
             },
         });
@@ -184,6 +185,13 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
+                    case 'roam_datomic_query': {
+                        const { query, inputs } = request.params.arguments;
+                        const result = await this.toolHandlers.executeDatomicQuery({ query, inputs });
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }

package/build/tools/operations/memory.js

@@ -68,9 +68,9 @@ export class MemoryOperations {
     }
     async recall() {
         // Get memories tag from environment
-        const memoriesTag = process.env.MEMORIES_TAG;
+        var memoriesTag = process.env.MEMORIES_TAG;
         if (!memoriesTag) {
-            throw new McpError(ErrorCode.InternalError, 'MEMORIES_TAG environment variable not set');
+            memoriesTag = "Memories";
         }
         // Extract the tag text, removing any formatting
         const tagText = memoriesTag

package/build/tools/operations/outline.js

@@ -54,20 +54,14 @@ export class OutlineOperations {
                 }
                 // If still not found and this is the first retry, try to create the page
                 if (retry === 0) {
-                    try {
-                        await createPage(this.graph, {
-                            action: 'create-page',
-                            page: { title: titleOrUid }
-                        });
-                        // Wait a bit and continue to next retry to check if page was created
-                        await new Promise(resolve => setTimeout(resolve, delayMs));
-                        continue;
-                    }
-                    catch (error) {
-                        console.error('Error creating page:', error);
-                        // Continue to next retry
-                        continue;
-                    }
+                    const success = await createPage(this.graph, {
+                        action: 'create-page',
+                        page: { title: titleOrUid }
+                    });
+                    // Even if createPage returns false, the page might still have been created
+                    // Wait a bit and continue to next retry
+                    await new Promise(resolve => setTimeout(resolve, delayMs));
+                    continue;
                 }
                 if (retry < maxRetries - 1) {
                     await new Promise(resolve => setTimeout(resolve, delayMs));
@@ -78,23 +72,21 @@ export class OutlineOperations {
         // Get or create the target page
         const targetPageUid = await findOrCreatePage(page_title_uid || formatRoamDate(new Date()));
         // Helper function to find block with improved relationship checks
-        const findBlockWithRetry = async (pageUid, blockString, maxRetries = 5, initialDelay = 1000, case_sensitive = false) => {
+        const findBlockWithRetry = async (pageUid, blockString, maxRetries = 5, initialDelay = 1000) => {
             // Try multiple query strategies
             const queries = [
                 // Strategy 1: Direct page and string match
                 `[:find ?b-uid ?order
           :where [?p :block/uid "${pageUid}"]
                  [?b :block/page ?p]
-                 [?b :block/string ?block-str]
-                 [(${case_sensitive ? '=' : 'clojure.string/equals-ignore-case'} ?block-str "${blockString}")]
+                 [?b :block/string "${blockString}"]
                  [?b :block/order ?order]
                  [?b :block/uid ?b-uid]]`,
                 // Strategy 2: Parent-child relationship
                 `[:find ?b-uid ?order
           :where [?p :block/uid "${pageUid}"]
                  [?b :block/parents ?p]
-                 [?b :block/string ?block-str]
-                 [(${case_sensitive ? '=' : 'clojure.string/equals-ignore-case'} ?block-str "${blockString}")]
+                 [?b :block/string "${blockString}"]
                  [?b :block/order ?order]
                  [?b :block/uid ?b-uid]]`,
                 // Strategy 3: Broader page relationship
@@ -102,8 +94,7 @@ export class OutlineOperations {
           :where [?p :block/uid "${pageUid}"]
                  [?b :block/page ?page]
                  [?p :block/page ?page]
-                 [?b :block/string ?block-str]
-                 [(${case_sensitive ? '=' : 'clojure.string/equals-ignore-case'} ?block-str "${blockString}")]
+                 [?b :block/string "${blockString}"]
                  [?b :block/order ?order]
                  [?b :block/uid ?b-uid]]`
             ];
@@ -125,7 +116,7 @@ export class OutlineOperations {
             throw new McpError(ErrorCode.InternalError, `Failed to find block "${blockString}" under page "${pageUid}" after trying multiple strategies`);
         };
         // Helper function to create and verify block with improved error handling
-        const createAndVerifyBlock = async (content, parentUid, maxRetries = 5, initialDelay = 1000, isRetry = false, case_sensitive = false) => {
+        const createAndVerifyBlock = async (content, parentUid, maxRetries = 5, initialDelay = 1000, isRetry = false) => {
             try {
                 // Initial delay before any operations
                 if (!isRetry) {
@@ -133,25 +124,25 @@ export class OutlineOperations {
                 }
                 for (let retry = 0; retry < maxRetries; retry++) {
                     console.log(`Attempt ${retry + 1}/${maxRetries} to create block "${content}" under "${parentUid}"`);
+                    // Create block
+                    const success = await createBlock(this.graph, {
+                        action: 'create-block',
+                        location: {
+                            'parent-uid': parentUid,
+                            order: 'last'
+                        },
+                        block: { string: content }
+                    });
+                    // Wait with exponential backoff
+                    const delay = initialDelay * Math.pow(2, retry);
+                    await new Promise(resolve => setTimeout(resolve, delay));
                     try {
-                        // Create block
-                        await createBlock(this.graph, {
-                            action: 'create-block',
-                            location: {
-                                'parent-uid': parentUid,
-                                order: 'first'
-                            },
-                            block: { string: content }
-                        });
-                        // Wait with exponential backoff
-                        const delay = initialDelay * Math.pow(2, retry);
-                        await new Promise(resolve => setTimeout(resolve, delay));
                         // Try to find the block using our improved findBlockWithRetry
-                        return await findBlockWithRetry(parentUid, content, maxRetries, initialDelay, case_sensitive);
+                        return await findBlockWithRetry(parentUid, content);
                     }
                     catch (error) {
                         const errorMessage = error instanceof Error ? error.message : String(error);
-                        console.log(`Failed to create/find block on attempt ${retry + 1}: ${errorMessage}`);
+                        console.log(`Failed to find block on attempt ${retry + 1}: ${errorMessage}`);
                         if (retry === maxRetries - 1)
                             throw error;
                     }
@@ -165,7 +156,7 @@ export class OutlineOperations {
                 // Otherwise, try one more time with a clean slate
                 console.log(`Retrying block creation for "${content}" with fresh attempt`);
                 await new Promise(resolve => setTimeout(resolve, initialDelay * 2));
-                return createAndVerifyBlock(content, parentUid, maxRetries, initialDelay, true, case_sensitive);
+                return createAndVerifyBlock(content, parentUid, maxRetries, initialDelay, true);
             }
         };
         // Get or create the parent block

package/build/tools/operations/search/handlers.js

@@ -1,4 +1,4 @@
-import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler } from '../../../search/index.js';
+import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler, DatomicSearchHandler } from '../../../search/index.js';
 // Base class for all search handlers
 export class BaseSearchHandler {
     graph;
@@ -54,3 +54,15 @@ export class TextSearchHandlerImpl extends BaseSearchHandler {
         return handler.execute();
     }
 }
+// Datomic query handler
+export class DatomicSearchHandlerImpl extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        const handler = new DatomicSearchHandler(this.graph, this.params);
+        return handler.execute();
+    }
+}

package/build/tools/schemas.js

@@ -426,5 +426,26 @@ export const toolSchemas = {
             properties: {},
             required: []
         }
+    },
+    roam_datomic_query: {
+        name: 'roam_datomic_query',
+        description: 'Execute a custom Datomic query on the Roam graph beyond the available search tools. This provides direct access to Roam\'s query engine for advanced data retrieval. Note: The Roam graph is case-sensitive.\nA list of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'The Datomic query to execute (in Datalog syntax)'
+                },
+                inputs: {
+                    type: 'array',
+                    description: 'Optional array of input parameters for the query',
+                    items: {
+                        type: 'string'
+                    }
+                }
+            },
+            required: ['query']
+        }
     }
 };

package/build/tools/tool-handlers.js

@@ -4,6 +4,7 @@ import { SearchOperations } from './operations/search/index.js';
 import { MemoryOperations } from './operations/memory.js';
 import { TodoOperations } from './operations/todos.js';
 import { OutlineOperations } from './operations/outline.js';
+import { DatomicSearchHandlerImpl } from './operations/search/handlers.js';
 export class ToolHandlers {
     graph;
     pageOps;
@@ -60,6 +61,11 @@ export class ToolHandlers {
     async searchByDate(params) {
         return this.searchOps.searchByDate(params);
     }
+    // Datomic query
+    async executeDatomicQuery(params) {
+        const handler = new DatomicSearchHandlerImpl(this.graph, params);
+        return handler.execute();
+    }
     // Memory Operations
     async remember(memory, categories) {
         return this.memoryOps.remember(memory, categories);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.22.1",
+  "version": "0.23.1",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {