roam-research-mcp 0.36.0 → 1.3.2

package/build/tools/operations/table.js

@@ -0,0 +1,142 @@
+import { BatchOperations } from './batch.js';
+/**
+ * Validates table input before building actions.
+ */
+export function validateTableInput(input) {
+    const errors = [];
+    if (!input.parent_uid) {
+        errors.push({ field: 'parent_uid', message: 'parent_uid is required' });
+    }
+    if (!input.headers || !Array.isArray(input.headers)) {
+        errors.push({ field: 'headers', message: 'headers must be an array' });
+    }
+    else if (input.headers.length === 0) {
+        errors.push({ field: 'headers', message: 'At least one header is required' });
+    }
+    if (!input.rows || !Array.isArray(input.rows)) {
+        errors.push({ field: 'rows', message: 'rows must be an array' });
+    }
+    else {
+        const expectedCells = (input.headers?.length || 1) - 1;
+        for (let i = 0; i < input.rows.length; i++) {
+            const row = input.rows[i];
+            if (!row.label && row.label !== '') {
+                errors.push({
+                    field: `rows[${i}].label`,
+                    message: 'Row label is required (use empty string for blank)'
+                });
+            }
+            if (!Array.isArray(row.cells)) {
+                errors.push({
+                    field: `rows[${i}].cells`,
+                    message: 'Row cells must be an array'
+                });
+            }
+            else if (row.cells.length !== expectedCells) {
+                errors.push({
+                    field: `rows[${i}].cells`,
+                    message: `Expected ${expectedCells} cells, got ${row.cells.length}`
+                });
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Builds batch actions for creating a Roam table structure.
+ *
+ * Roam tables have a specific nested structure:
+ * - The table container block contains {{[[table]]}}
+ * - Header row is nested deeply (each column nested under the previous)
+ * - Data rows follow the same nesting pattern
+ */
+export function buildTableActions(input) {
+    const actions = [];
+    // Create table container
+    actions.push({
+        action: 'create-block',
+        uid: '{{uid:table}}',
+        string: '{{[[table]]}}',
+        location: { 'parent-uid': input.parent_uid, order: input.order ?? 'last' }
+    });
+    // Create header row with nested structure
+    // In Roam tables, each column is nested under the previous column
+    let headerParent = '{{uid:table}}';
+    for (let i = 0; i < input.headers.length; i++) {
+        const uid = `{{uid:header_${i}}}`;
+        const headerText = input.headers[i] || ' '; // Convert empty to space
+        actions.push({
+            action: 'create-block',
+            uid,
+            string: headerText,
+            location: { 'parent-uid': headerParent, order: 0 }
+        });
+        headerParent = uid;
+    }
+    // Create data rows
+    // Each row starts as a child of the table, with cells nested under each other
+    for (let rowIdx = 0; rowIdx < input.rows.length; rowIdx++) {
+        const row = input.rows[rowIdx];
+        // Row label (first column) - child of table at position rowIdx + 1 (after header)
+        const labelUid = `{{uid:row_${rowIdx}_label}}`;
+        const labelText = row.label || ' '; // Convert empty to space
+        actions.push({
+            action: 'create-block',
+            uid: labelUid,
+            string: labelText,
+            location: { 'parent-uid': '{{uid:table}}', order: rowIdx + 1 }
+        });
+        // Row cells - each cell is nested under the previous
+        let cellParent = labelUid;
+        for (let cellIdx = 0; cellIdx < row.cells.length; cellIdx++) {
+            const cellUid = `{{uid:row_${rowIdx}_cell_${cellIdx}}}`;
+            const cellText = row.cells[cellIdx] || ' '; // Convert empty to space
+            actions.push({
+                action: 'create-block',
+                uid: cellUid,
+                string: cellText,
+                location: { 'parent-uid': cellParent, order: 0 }
+            });
+            cellParent = cellUid;
+        }
+    }
+    return actions;
+}
+export class TableOperations {
+    constructor(graph) {
+        this.batchOps = new BatchOperations(graph);
+    }
+    /**
+     * Creates a table in Roam with the specified headers and rows.
+     *
+     * @param input Table configuration including parent_uid, headers, and rows
+     * @returns Result including success status and table block UID
+     */
+    async createTable(input) {
+        // Validate input
+        const validation = validateTableInput(input);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: {
+                    code: 'VALIDATION_ERROR',
+                    message: validation.errors.map(e => `[${e.field}] ${e.message}`).join('; ')
+                },
+                validation_passed: false,
+                actions_attempted: 0
+            };
+        }
+        // Build table actions
+        const actions = buildTableActions(input);
+        // Execute batch
+        const result = await this.batchOps.processBatch(actions);
+        // Add table_uid if successful
+        if (result.success && result.uid_map) {
+            return {
+                ...result,
+                table_uid: result.uid_map['table']
+            };
+        }
+        return result;
+    }
+}

package/build/tools/schemas.js

@@ -40,7 +40,7 @@ export const toolSchemas = {
     },
     roam_create_page: {
         name: 'roam_create_page',
-        description: 'Create a new standalone page in Roam with optional content, including structured outlines, using explicit nesting levels and headings (H1-H3). This is the preferred method for creating a new page with an outline in a single step. Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        description: 'Create a new standalone page in Roam with optional content, including structured outlines and tables, using explicit nesting levels and headings (H1-H3). This is the preferred method for creating a new page with an outline in a single step. Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information\n- Creating pages with mixed text and table content in one call.\n**Efficiency Tip:** This tool batches page and content creation efficiently. For adding content to existing pages, use `roam_process_batch_actions` instead.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -50,28 +50,58 @@ export const toolSchemas = {
                 },
                 content: {
                     type: 'array',
-                    description: 'Initial content for the page as an array of blocks with explicit nesting levels. Note: While empty blocks (e.g., {"text": "", "level": 1}) can be used for visual spacing, they create empty entities in the database. Please use them sparingly and only for structural purposes, not for simple visual separation.',
+                    description: 'Initial content for the page as an array of content items. Each item can be a text block or a table. Text blocks use {text, level, heading?}. Tables use {type: "table", headers, rows}. Items are processed in order.',
                     items: {
                         type: 'object',
                         properties: {
+                            type: {
+                                type: 'string',
+                                enum: ['text', 'table'],
+                                description: 'Content type: "text" for regular blocks (default), "table" for tables',
+                                default: 'text'
+                            },
                             text: {
                                 type: 'string',
-                                description: 'Content of the block'
+                                description: 'Content of the block (for type: "text")'
                             },
                             level: {
                                 type: 'integer',
-                                description: 'Indentation level (1-10, where 1 is top level)',
+                                description: 'Indentation level (1-10, where 1 is top level). For tables, this should always be 1.',
                                 minimum: 1,
                                 maximum: 10
                             },
                             heading: {
                                 type: 'integer',
-                                description: 'Optional: Heading formatting for this block (1-3)',
+                                description: 'Optional: Heading formatting for this block (1-3). Only for type: "text".',
                                 minimum: 1,
                                 maximum: 3
+                            },
+                            headers: {
+                                type: 'array',
+                                description: 'Column headers for the table (for type: "table"). First header is typically empty for row labels.',
+                                items: { type: 'string' }
+                            },
+                            rows: {
+                                type: 'array',
+                                description: 'Data rows for the table (for type: "table"). Each row has a label and cells.',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        label: {
+                                            type: 'string',
+                                            description: 'The row label (first column content). Use empty string for blank.'
+                                        },
+                                        cells: {
+                                            type: 'array',
+                                            description: 'Cell values for this row. Must have exactly (headers.length - 1) items.',
+                                            items: { type: 'string' }
+                                        }
+                                    },
+                                    required: ['label', 'cells']
+                                }
                             }
                         },
-                        required: ['text', 'level']
+                        required: ['level']
                     }
                 },
             },
@@ -80,7 +110,7 @@ export const toolSchemas = {
     },
     roam_create_outline: {
         name: 'roam_create_outline',
-        description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. To create a new page with an outline, use the `roam_create_page` tool instead. The `outline` parameter defines *new* blocks to be created. To nest content under an *existing* block, provide its UID or exact text in `block_text_uid`, and ensure the `outline` array contains only the child blocks with levels relative to that parent. Including the parent block\'s text in the `outline` array will create a duplicate block. Best for:\n- Adding supplementary structured content to existing pages\n- Creating temporary or working outlines (meeting notes, brainstorms)\n- Organizing thoughts or research under a specific topic\n- Breaking down subtopics or components of a larger concept\nBest for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider `roam_process_batch_actions` instead.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. To create a new page with an outline, use the `roam_create_page` tool instead. The `outline` parameter defines *new* blocks to be created. To nest content under an *existing* block, provide its UID or exact text in `block_text_uid`, and ensure the `outline` array contains only the child blocks with levels relative to that parent. Including the parent block\'s text in the `outline` array will create a duplicate block. Best for:\n- Adding supplementary structured content to existing pages\n- Creating temporary or working outlines (meeting notes, brainstorms)\n- Organizing thoughts or research under a specific topic\n- Breaking down subtopics or components of a larger concept\nBest for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider `roam_process_batch_actions` instead.\n**API Usage Note:** This tool performs verification queries after creation. For large outlines (10+ items) or when rate limits are a concern, consider using `roam_process_batch_actions` instead to minimize API calls.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -129,7 +159,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 (preferred) or by exact string match within a specific page. If a `parent_string` is provided and the block does not exist, it will be created. Returns a nested structure of the created blocks.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        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. If a `parent_string` is provided and the block does not exist, it will be created. Returns a nested structure of the created blocks.\n**API Usage Note:** This tool fetches the full nested structure after import for verification. For large imports or when rate limits are a concern, consider using `roam_process_batch_actions` with pre-structured actions instead.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -188,8 +218,8 @@ export const toolSchemas = {
                 },
                 limit: {
                     type: 'integer',
-                    description: 'Optional: The maximum number of results to return. Defaults to 1. Use -1 for no limit.',
-                    default: 1
+                    description: 'Optional: The maximum number of results to return. Defaults to 50. Use -1 for no limit, but be aware that very large results sets can impact performance.',
+                    default: 50
                 },
                 offset: {
                     type: 'integer',
@@ -274,15 +304,26 @@ export const toolSchemas = {
     },
     roam_find_pages_modified_today: {
         name: 'roam_find_pages_modified_today',
-        description: 'Find pages that have been modified today (since midnight), with limit.',
+        description: 'Find pages that have been modified today (since midnight), with pagination and sorting options.',
         inputSchema: {
             type: 'object',
             properties: {
-                max_num_pages: {
+                limit: {
                     type: 'integer',
-                    description: 'Max number of pages to retrieve (default: 50)',
+                    description: 'The maximum number of pages to retrieve (default: 50). Use -1 for no limit, but be aware that very large result sets can impact performance.',
                     default: 50
                 },
+                offset: {
+                    type: 'integer',
+                    description: 'The number of pages to skip before returning matches. Useful for pagination. Defaults to 0.',
+                    default: 0
+                },
+                sort_order: {
+                    type: 'string',
+                    description: 'Sort order for pages based on modification date. "desc" for most recent first, "asc" for oldest first.',
+                    enum: ['asc', 'desc'],
+                    default: 'desc'
+                }
             }
         }
     },
@@ -307,8 +348,8 @@ export const toolSchemas = {
                 },
                 limit: {
                     type: 'integer',
-                    description: 'Optional: The maximum number of results to return. Defaults to 1. Use -1 for no limit.',
-                    default: 1
+                    description: 'Optional: The maximum number of results to return. Defaults to 50. Use -1 for no limit, but be aware that very large results sets can impact performance.',
+                    default: 50
                 },
                 offset: {
                     type: 'integer',
@@ -403,7 +444,7 @@ export const toolSchemas = {
     },
     roam_datomic_query: {
         name: 'roam_datomic_query',
-        description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. Note: Roam graph is case-sensitive.\n\n__Optimal Use Cases for `roam_datomic_query`:__\n- __Regex Search:__ Use for scenarios requiring regex, as Datalog does not natively support full regular expressions. It can fetch broader results for client-side post-processing.\n- __Highly Complex Boolean Logic:__ Ideal for intricate combinations of "AND", "OR", and "NOT" conditions across multiple terms or attributes.\n- __Arbitrary Sorting Criteria:__ The go-to for highly customized sorting needs beyond default options.\n- __Proximity Search:__ For advanced search capabilities involving proximity, which are difficult to implement efficiently with simpler tools.\n\nList 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, limit).\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.',
+        description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. Note: Roam graph is case-sensitive.\n\n__Optimal Use Cases for `roam_datomic_query`:__\n- __Advanced Filtering (including Regex):__ Use for scenarios requiring complex filtering, including regex matching on results post-query, which Datalog does not natively support for all data types. It can fetch broader results for client-side post-processing.\n- __Highly Complex Boolean Logic:__ Ideal for intricate combinations of "AND", "OR", and "NOT" conditions across multiple terms or attributes.\n- __Arbitrary Sorting Criteria:__ The go-to for highly customized sorting needs beyond default options.\n- __Proximity Search:__ For advanced search capabilities involving proximity, which are difficult to implement efficiently with simpler tools.\n\nList 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, limit).\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: {
@@ -417,6 +458,21 @@ export const toolSchemas = {
                     items: {
                         type: 'string'
                     }
+                },
+                regexFilter: {
+                    type: 'string',
+                    description: 'Optional: A regex pattern to filter the results client-side after the Datomic query. Applied to JSON.stringify(result) or specific fields if regexTargetField is provided.'
+                },
+                regexFlags: {
+                    type: 'string',
+                    description: 'Optional: Flags for the regex filter (e.g., "i" for case-insensitive, "g" for global).',
+                },
+                regexTargetField: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Optional: An array of field paths (e.g., ["block_string", "page_title"]) within each Datomic result object to apply the regex filter to. If not provided, the regex is applied to the stringified full result.'
                 }
             },
             required: ['query']
@@ -424,7 +480,7 @@ export const toolSchemas = {
     },
     roam_process_batch_actions: {
         name: 'roam_process_batch_actions',
-        description: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order. For creating nested blocks, you can use a temporary client-side UID in a parent block and refer to it in a child block within the same batch. For actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with `((UID))` syntax, is supported within the `string` property for `create-block` and `update-block` actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like `roam_fetch_page_by_title` or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, `roam_create_outline` is often more suitable.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        description: '**RATE LIMIT EFFICIENT:** This is the most API-efficient tool for multiple block operations. Combine all create/update/delete operations into a single call whenever possible. For intensive page updates or revisions, prefer this tool over multiple sequential calls.\n\nExecutes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order.\n\n**UID Placeholders for Nested Blocks:** Use `{{uid:name}}` syntax for parent-child references within the same batch. The server generates proper random UIDs and returns a `uid_map` showing placeholder→UID mappings. Example: `{ uid: "{{uid:parent1}}", string: "Parent" }` then `{ location: { "parent-uid": "{{uid:parent1}}" }, string: "Child" }`. Response includes `{ success: true, uid_map: { "parent1": "Xk7mN2pQ9" } }`.\n\nFor actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with `((UID))` syntax, is supported within the `string` property for `create-block` and `update-block` actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like `roam_fetch_page_by_title` or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, `roam_create_outline` is often more suitable.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -508,4 +564,52 @@ export const toolSchemas = {
             required: ['block_uid']
         },
     },
+    roam_create_table: {
+        name: 'roam_create_table',
+        description: 'Create a table in Roam with specified headers and rows. This tool abstracts the complex nested structure that Roam tables require, making it much easier to create properly formatted tables.\n\n**Why use this tool:**\n- Roam tables require precise nested block structures that are error-prone to create manually\n- Automatically handles the {{[[table]]}} container and nested column structure\n- Validates row/column consistency before execution\n- Converts empty cells to spaces (required by Roam)\n\n**Example:** A table with headers ["", "Column A", "Column B"] and rows [{label: "Row 1", cells: ["A1", "B1"]}] creates a 2x3 table.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                parent_uid: {
+                    type: 'string',
+                    description: 'The UID of the parent block or page where the table should be created.'
+                },
+                order: {
+                    type: ['integer', 'string'],
+                    description: 'Optional: Position under the parent. Can be a number (0-based) or "first"/"last". Defaults to "last".',
+                    default: 'last'
+                },
+                headers: {
+                    type: 'array',
+                    description: 'Column headers for the table. The first header is typically empty (for the row label column). Example: ["", "Option A", "Option B"]',
+                    items: {
+                        type: 'string'
+                    },
+                    minItems: 1
+                },
+                rows: {
+                    type: 'array',
+                    description: 'Data rows for the table. Each row has a label (first column) and cells (remaining columns).',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: {
+                                type: 'string',
+                                description: 'The row label (first column content). Use empty string for blank.'
+                            },
+                            cells: {
+                                type: 'array',
+                                description: 'Cell values for this row. Must have exactly (headers.length - 1) items.',
+                                items: {
+                                    type: 'string'
+                                }
+                            }
+                        },
+                        required: ['label', 'cells']
+                    }
+                }
+            },
+            required: ['parent_uid', 'headers', 'rows']
+        }
+    },
 };

package/build/tools/tool-handlers.js

@@ -3,28 +3,31 @@ import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { PageOperations } from './operations/pages.js';
 import { BlockOperations } from './operations/blocks.js';
-import { BlockRetrievalOperations } from './operations/block-retrieval.js'; // New import
+import { BlockRetrievalOperations } from './operations/block-retrieval.js';
 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 { BatchOperations } from './operations/batch.js';
+import { TableOperations } from './operations/table.js';
 import { DatomicSearchHandlerImpl } from './operations/search/handlers.js';
 export class ToolHandlers {
     constructor(graph) {
         this.graph = graph;
+        this.cachedCheatsheet = null;
         this.pageOps = new PageOperations(graph);
         this.blockOps = new BlockOperations(graph);
-        this.blockRetrievalOps = new BlockRetrievalOperations(graph); // Initialize new instance
+        this.blockRetrievalOps = new BlockRetrievalOperations(graph);
         this.searchOps = new SearchOperations(graph);
         this.memoryOps = new MemoryOperations(graph);
         this.todoOps = new TodoOperations(graph);
         this.outlineOps = new OutlineOperations(graph);
         this.batchOps = new BatchOperations(graph);
+        this.tableOps = new TableOperations(graph);
     }
     // Page Operations
-    async findPagesModifiedToday(max_num_pages = 50) {
-        return this.pageOps.findPagesModifiedToday(max_num_pages);
+    async findPagesModifiedToday(limit = 50, offset = 0, sort_order = 'desc') {
+        return this.pageOps.findPagesModifiedToday(limit, offset, sort_order);
     }
     async createPage(title, content) {
         return this.pageOps.createPage(title, content);
@@ -82,21 +85,39 @@ export class ToolHandlers {
     async processBatch(actions) {
         return this.batchOps.processBatch(actions);
     }
+    // Table Operations
+    async createTable(input) {
+        return this.tableOps.createTable(input);
+    }
     async getRoamMarkdownCheatsheet() {
+        if (this.cachedCheatsheet) {
+            return this.cachedCheatsheet;
+        }
         const __filename = fileURLToPath(import.meta.url);
         const __dirname = path.dirname(__filename);
         const cheatsheetPath = path.join(__dirname, '../../Roam_Markdown_Cheatsheet.md');
-        let cheatsheetContent = fs.readFileSync(cheatsheetPath, 'utf-8');
-        const customInstructionsPath = process.env.CUSTOM_INSTRUCTIONS_PATH;
-        if (customInstructionsPath && fs.existsSync(customInstructionsPath)) {
-            try {
-                const customInstructionsContent = fs.readFileSync(customInstructionsPath, 'utf-8');
-                cheatsheetContent += `\n\n${customInstructionsContent}`;
-            }
-            catch (error) {
-                console.warn(`Could not read custom instructions file at ${customInstructionsPath}: ${error}`);
+        try {
+            let cheatsheetContent = await fs.promises.readFile(cheatsheetPath, 'utf-8');
+            const customInstructionsPath = process.env.CUSTOM_INSTRUCTIONS_PATH;
+            if (customInstructionsPath) {
+                try {
+                    // Check if file exists asynchronously
+                    await fs.promises.access(customInstructionsPath);
+                    const customInstructionsContent = await fs.promises.readFile(customInstructionsPath, 'utf-8');
+                    cheatsheetContent += `\n\n${customInstructionsContent}`;
+                }
+                catch (error) {
+                    // File doesn't exist or is not readable, ignore custom instructions
+                    if (error.code !== 'ENOENT') {
+                        console.warn(`Could not read custom instructions file at ${customInstructionsPath}: ${error}`);
+                    }
+                }
             }
+            this.cachedCheatsheet = cheatsheetContent;
+            return cheatsheetContent;
+        }
+        catch (error) {
+            throw new Error(`Failed to read cheatsheet: ${error}`);
         }
-        return cheatsheetContent;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.36.0",
+  "version": "1.3.2",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -22,13 +22,14 @@
   "homepage": "https://github.com/2b3pro/roam-research-mcp#readme",
   "type": "module",
   "bin": {
-    "roam-research": "./build/index.js"
+    "roam-research-mcp": "build/index.js",
+    "roam-import": "build/cli/import-markdown.js"
   },
   "files": [
     "build"
   ],
   "scripts": {
-    "build": "echo \"Using custom instructions: .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md\" && tsc && cat Roam_Markdown_Cheatsheet.md .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md > build/Roam_Markdown_Cheatsheet.md && chmod 755 build/index.js",
+    "build": "echo \"Using custom instructions: .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md\" && tsc && cat Roam_Markdown_Cheatsheet.md .roam/${CUSTOM_INSTRUCTIONS_PREFIX}custom-instructions.md > build/Roam_Markdown_Cheatsheet.md && chmod 755 build/index.js build/cli/import-markdown.js",
     "clean": "rm -rf build",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
@@ -48,4 +49,4 @@
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3"
   }
-}
+}