roam-research-mcp 0.25.5 → 0.25.7

package/README.md

@@ -26,12 +26,42 @@ npm install
 npm run build
 ```
 
-## To Test
+## Docker
+
+This project can be easily containerized using Docker. A `Dockerfile` is provided at the root of the repository.
+
+### Build the Docker Image
 
-Run [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build…
+To build the Docker image, navigate to the project root and run:
 
+```bash
+docker build -t roam-research-mcp .
 ```
-npx @modelcontextprotocol/inspector node build/index.js
+
+### Run the Docker Container
+
+To run the Docker container and map port 3000 (if your application uses it), you must also provide the necessary environment variables. Use the `-e` flag to pass `ROAM_API_TOKEN`, `ROAM_GRAPH_NAME`, and optionally `MEMORIES_TAG`:
+
+```bash
+docker run -p 3000:3000 \
+  -e ROAM_API_TOKEN="your-api-token" \
+  -e ROAM_GRAPH_NAME="your-graph-name" \
+  -e MEMORIES_TAG="#[[LLM/Memories]]" \
+  roam-research-mcp
+```
+
+Alternatively, if you have a `.env` file in the project root (which is copied into the Docker image during build), you can use the `--env-file` flag:
+
+```bash
+docker run -p 3000:3000 --env-file .env roam-research-mcp
+```
+
+## To Test
+
+Run [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build using the provided npm script:
+
+```bash
+npm run inspector
 ```
 
 ## Features
@@ -48,22 +78,22 @@ The server provides powerful tools for interacting with Roam Research:
 - Efficient batch operations
 - Hierarchical outline creation
 
-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. `roam_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
-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
-16. `roam_datomic_query`: Execute custom Datalog queries on the Roam graph for advanced data retrieval and analysis
+1. `roam_fetch_page_by_title`: Fetch page content by title.
+2. `roam_create_page`: Create new pages with optional content and headings.
+3. `roam_create_block`: Add new blocks to an existing page or today's daily note.
+4. `roam_import_markdown`: Import nested markdown content under a specific block.
+5. `roam_add_todo`: Add a list of todo items to today's daily page.
+6. `roam_create_outline`: Add a structured outline to an existing page or block.
+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_update_block`: Update a single block identified by its UID.
+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.
+14. `roam_remember`: Add a memory or piece of information to remember.
+15. `roam_recall`: Retrieve all stored memories.
+16. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph beyond the available search tools.
 
 ## Setup
 

package/build/server/roam-server.js

@@ -5,43 +5,58 @@ import { initializeGraph } from '@roam-research/roam-api-sdk';
 import { API_TOKEN, GRAPH_NAME } from '../config/environment.js';
 import { toolSchemas } from '../tools/schemas.js';
 import { ToolHandlers } from '../tools/tool-handlers.js';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read package.json to get the version
+const packageJsonPath = join(__dirname, '../../package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+const serverVersion = packageJson.version;
 export class RoamServer {
     constructor() {
-        this.graph = initializeGraph({
-            token: API_TOKEN,
-            graph: GRAPH_NAME,
-        });
-        this.toolHandlers = new ToolHandlers(this.graph);
+        try {
+            this.graph = initializeGraph({
+                token: API_TOKEN,
+                graph: GRAPH_NAME,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InternalError, `Failed to initialize Roam graph: ${errorMessage}`);
+        }
+        try {
+            this.toolHandlers = new ToolHandlers(this.graph);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InternalError, `Failed to initialize tool handlers: ${errorMessage}`);
+        }
+        // Ensure toolSchemas is not empty before proceeding
+        if (Object.keys(toolSchemas).length === 0) {
+            throw new McpError(ErrorCode.InternalError, 'No tool schemas defined in src/tools/schemas.ts');
+        }
         this.server = new Server({
             name: 'roam-research',
-            version: '0.25.5',
+            version: serverVersion, // Use the version from package.json
         }, {
             capabilities: {
                 tools: {
-                    roam_remember: {},
-                    roam_recall: {},
-                    roam_add_todo: {},
-                    roam_fetch_page_by_title: {},
-                    roam_create_page: {},
-                    roam_create_block: {},
-                    roam_import_markdown: {},
-                    roam_create_outline: {},
-                    roam_search_for_tag: {},
-                    roam_search_by_status: {},
-                    roam_search_block_refs: {},
-                    roam_search_hierarchy: {},
-                    roam_find_pages_modified_today: {},
-                    roam_search_by_text: {},
-                    roam_update_block: {},
-                    roam_update_multiple_blocks: {},
-                    roam_search_by_date: {},
-                    roam_datomic_query: {}
+                    ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
                 },
             },
         });
         this.setupRequestHandlers();
         // Error handling
-        this.server.onerror = (error) => { };
+        this.server.onerror = (error) => {
+            // Re-throw as McpError to be caught by the MCP client
+            if (error instanceof McpError) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InternalError, `MCP server internal error: ${errorMessage}`);
+        };
         process.on('SIGINT', async () => {
             await this.server.close();
             process.exit(0);
@@ -220,7 +235,13 @@ export class RoamServer {
         });
     }
     async run() {
-        const transport = new StdioServerTransport();
-        await this.server.connect(transport);
+        try {
+            const transport = new StdioServerTransport();
+            await this.server.connect(transport);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InternalError, `Failed to connect MCP server: ${errorMessage}`);
+        }
     }
 }

package/build/tools/schemas.js

@@ -19,21 +19,24 @@ export const toolSchemas = {
         },
     },
     roam_fetch_page_by_title: {
+        name: 'roam_fetch_page_by_title',
         description: 'Fetch page by title, defaults to raw JSON string.',
-        type: 'object',
-        properties: {
-            title: {
-                type: 'string',
-                description: 'Title of the page. For date pages, use ordinal date formats such as January 2nd, 2025'
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Title of the page. For date pages, use ordinal date formats such as January 2nd, 2025'
+                },
+                format: {
+                    type: 'string',
+                    enum: ['markdown', 'raw'],
+                    default: 'raw',
+                    description: "Format output as markdown or JSON. 'markdown' returns as string; 'raw' returns JSON string of the page's blocks"
+                }
             },
-            format: {
-                type: 'string',
-                enum: ['markdown', 'raw'],
-                default: 'raw',
-                description: "Format output as markdown or JSON. 'markdown' returns as string; 'raw' returns JSON string of the page's blocks"
-            }
+            required: ['title']
         },
-        required: ['title']
     },
     roam_create_page: {
         name: 'roam_create_page',
@@ -149,7 +152,7 @@ export const toolSchemas = {
     },
     roam_import_markdown: {
         name: 'roam_import_markdown',
-        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID or by exact string match within a specific page.',
+        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -171,7 +174,7 @@ export const toolSchemas = {
                 },
                 parent_string: {
                     type: 'string',
-                    description: 'Optional: Exact string content of the parent block to add content under (must provide either page_uid or page_title)'
+                    description: 'Optional: Exact string content of the parent block to add content under (must provide either page_uid (preferred) or page_title)'
                 },
                 order: {
                     type: 'string',
@@ -311,7 +314,7 @@ export const toolSchemas = {
     },
     roam_update_block: {
         name: 'roam_update_block',
-        description: 'Update a single block identified by its UID. Use this for individual block updates when you need to either replace the entire content or apply a transform pattern to modify specific parts of the content.\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: 'Update a single block identified by its UID. Use this for individual block updates when you need to either replace the entire content or apply a transform pattern to modify specific parts of the content.\nNOTE 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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.25.5",
+  "version": "0.25.7",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -31,7 +31,8 @@
     "build": "tsc && chmod 755 build/index.js",
     "prepare": "npm run build",
     "watch": "tsc --watch",
-    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js",
+    "start": "node build/index.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "0.6.0",