roam-research-mcp 1.0.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: {
@@ -450,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: {
@@ -534,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,12 +3,13 @@ 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) {
@@ -16,12 +17,13 @@ export class ToolHandlers {
         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(limit = 50, offset = 0, sort_order = 'desc') {
@@ -83,6 +85,10 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "1.0.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-mcp": "./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",