roam-research-mcp 0.22.0 → 0.23.0

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/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

@@ -399,7 +399,7 @@ export const toolSchemas = {
     },
     roam_remember: {
         name: 'roam_remember',
-        description: 'Add a memory or piece of information to remember, stored on the daily page with #[[LLM/Memories]] tag and optional categories. Use roam_search_for_tag with "LLM/Memories" to find stored memories.\nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
+        description: 'Add a memory or piece of information to remember, stored on the daily page with #[[LLM/Memories]] tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -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. 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.0",
+  "version": "0.23.0",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {