roam-research-mcp 1.0.0 → 1.4.0

package/build/diff/parser.test.js

@@ -0,0 +1,281 @@
+import { describe, it, expect } from 'vitest';
+import { parseExistingBlock, parseExistingBlocks, flattenExistingBlocks, markdownToBlocks, getBlockDepth, } from './parser.js';
+describe('parseExistingBlock', () => {
+    it('parses a simple block', () => {
+        const roamBlock = {
+            ':block/uid': 'abc123def',
+            ':block/string': 'Hello world',
+            ':block/order': 0,
+            ':block/heading': null,
+        };
+        const block = parseExistingBlock(roamBlock);
+        expect(block.uid).toBe('abc123def');
+        expect(block.text).toBe('Hello world');
+        expect(block.order).toBe(0);
+        expect(block.heading).toBeNull();
+        expect(block.children).toEqual([]);
+        expect(block.parentUid).toBeNull();
+    });
+    it('parses block with heading', () => {
+        const roamBlock = {
+            ':block/uid': 'heading1',
+            ':block/string': 'Title',
+            ':block/order': 0,
+            ':block/heading': 2,
+        };
+        const block = parseExistingBlock(roamBlock);
+        expect(block.heading).toBe(2);
+    });
+    it('parses nested children', () => {
+        const roamBlock = {
+            ':block/uid': 'parent',
+            ':block/string': 'Parent',
+            ':block/order': 0,
+            ':block/children': [
+                {
+                    ':block/uid': 'child1',
+                    ':block/string': 'Child 1',
+                    ':block/order': 0,
+                },
+                {
+                    ':block/uid': 'child2',
+                    ':block/string': 'Child 2',
+                    ':block/order': 1,
+                },
+            ],
+        };
+        const block = parseExistingBlock(roamBlock);
+        expect(block.children.length).toBe(2);
+        expect(block.children[0].uid).toBe('child1');
+        expect(block.children[0].parentUid).toBe('parent');
+        expect(block.children[1].uid).toBe('child2');
+        expect(block.children[1].parentUid).toBe('parent');
+    });
+    it('sorts children by order', () => {
+        const roamBlock = {
+            ':block/uid': 'parent',
+            ':block/string': 'Parent',
+            ':block/order': 0,
+            ':block/children': [
+                { ':block/uid': 'c', ':block/string': 'C', ':block/order': 2 },
+                { ':block/uid': 'a', ':block/string': 'A', ':block/order': 0 },
+                { ':block/uid': 'b', ':block/string': 'B', ':block/order': 1 },
+            ],
+        };
+        const block = parseExistingBlock(roamBlock);
+        expect(block.children.map((c) => c.uid)).toEqual(['a', 'b', 'c']);
+    });
+    it('handles missing properties gracefully', () => {
+        const roamBlock = {};
+        const block = parseExistingBlock(roamBlock);
+        expect(block.uid).toBe('');
+        expect(block.text).toBe('');
+        expect(block.order).toBe(0);
+        expect(block.heading).toBeNull();
+    });
+});
+describe('parseExistingBlocks', () => {
+    it('parses page children into blocks', () => {
+        const pageData = {
+            ':block/uid': 'page123',
+            ':block/children': [
+                { ':block/uid': 'b1', ':block/string': 'First', ':block/order': 0 },
+                { ':block/uid': 'b2', ':block/string': 'Second', ':block/order': 1 },
+            ],
+        };
+        const blocks = parseExistingBlocks(pageData);
+        expect(blocks.length).toBe(2);
+        expect(blocks[0].text).toBe('First');
+        expect(blocks[1].text).toBe('Second');
+        expect(blocks[0].parentUid).toBeNull();
+    });
+    it('returns empty array for page with no children', () => {
+        const pageData = { ':block/uid': 'page123' };
+        const blocks = parseExistingBlocks(pageData);
+        expect(blocks).toEqual([]);
+    });
+});
+describe('flattenExistingBlocks', () => {
+    it('flattens nested blocks into array', () => {
+        const blocks = [
+            {
+                uid: 'a',
+                text: 'A',
+                order: 0,
+                heading: null,
+                parentUid: null,
+                children: [
+                    {
+                        uid: 'a1',
+                        text: 'A1',
+                        order: 0,
+                        heading: null,
+                        parentUid: 'a',
+                        children: [],
+                    },
+                    {
+                        uid: 'a2',
+                        text: 'A2',
+                        order: 1,
+                        heading: null,
+                        parentUid: 'a',
+                        children: [],
+                    },
+                ],
+            },
+            {
+                uid: 'b',
+                text: 'B',
+                order: 1,
+                heading: null,
+                parentUid: null,
+                children: [],
+            },
+        ];
+        const flat = flattenExistingBlocks(blocks);
+        expect(flat.map((b) => b.uid)).toEqual(['a', 'a1', 'a2', 'b']);
+    });
+    it('preserves depth-first order', () => {
+        const blocks = [
+            {
+                uid: 'root',
+                text: 'Root',
+                order: 0,
+                heading: null,
+                parentUid: null,
+                children: [
+                    {
+                        uid: 'child1',
+                        text: 'Child 1',
+                        order: 0,
+                        heading: null,
+                        parentUid: 'root',
+                        children: [
+                            {
+                                uid: 'grandchild',
+                                text: 'Grandchild',
+                                order: 0,
+                                heading: null,
+                                parentUid: 'child1',
+                                children: [],
+                            },
+                        ],
+                    },
+                    {
+                        uid: 'child2',
+                        text: 'Child 2',
+                        order: 1,
+                        heading: null,
+                        parentUid: 'root',
+                        children: [],
+                    },
+                ],
+            },
+        ];
+        const flat = flattenExistingBlocks(blocks);
+        expect(flat.map((b) => b.uid)).toEqual([
+            'root',
+            'child1',
+            'grandchild',
+            'child2',
+        ]);
+    });
+    it('returns empty array for empty input', () => {
+        expect(flattenExistingBlocks([])).toEqual([]);
+    });
+});
+describe('markdownToBlocks', () => {
+    const pageUid = 'page123';
+    it('converts simple markdown to blocks', () => {
+        const markdown = `- First item
+- Second item`;
+        const blocks = markdownToBlocks(markdown, pageUid);
+        expect(blocks.length).toBe(2);
+        expect(blocks[0].text).toBe('First item');
+        expect(blocks[1].text).toBe('Second item');
+        expect(blocks[0].parentRef?.blockUid).toBe(pageUid);
+        expect(blocks[1].parentRef?.blockUid).toBe(pageUid);
+    });
+    it('handles nested markdown', () => {
+        const markdown = `- Parent
+  - Child`;
+        const blocks = markdownToBlocks(markdown, pageUid);
+        expect(blocks.length).toBe(2);
+        const parentBlock = blocks.find((b) => b.text === 'Parent');
+        const childBlock = blocks.find((b) => b.text === 'Child');
+        expect(parentBlock).toBeDefined();
+        expect(childBlock).toBeDefined();
+        expect(childBlock?.parentRef?.blockUid).toBe(parentBlock?.ref.blockUid);
+    });
+    it('preserves heading levels', () => {
+        const markdown = `# Heading 1
+## Heading 2
+### Heading 3`;
+        const blocks = markdownToBlocks(markdown, pageUid);
+        expect(blocks[0].heading).toBe(1);
+        expect(blocks[1].heading).toBe(2);
+        expect(blocks[2].heading).toBe(3);
+    });
+    it('generates unique UIDs', () => {
+        const markdown = `- Item 1
+- Item 2
+- Item 3`;
+        const blocks = markdownToBlocks(markdown, pageUid);
+        const uids = blocks.map((b) => b.ref.blockUid);
+        expect(new Set(uids).size).toBe(3); // All unique
+    });
+    it('sets order based on sibling position', () => {
+        const markdown = `- First
+- Second
+- Third`;
+        const blocks = markdownToBlocks(markdown, pageUid);
+        expect(blocks[0].order).toBe(0);
+        expect(blocks[1].order).toBe(1);
+        expect(blocks[2].order).toBe(2);
+    });
+});
+describe('getBlockDepth', () => {
+    it('returns 0 for root blocks', () => {
+        const blocks = [
+            {
+                ref: { blockUid: 'root' },
+                text: 'Root',
+                parentRef: { blockUid: 'page' },
+                order: 0,
+                open: true,
+                heading: null,
+            },
+        ];
+        expect(getBlockDepth(blocks[0], blocks)).toBe(0);
+    });
+    it('returns correct depth for nested blocks', () => {
+        const blocks = [
+            {
+                ref: { blockUid: 'parent' },
+                text: 'Parent',
+                parentRef: { blockUid: 'page' },
+                order: 0,
+                open: true,
+                heading: null,
+            },
+            {
+                ref: { blockUid: 'child' },
+                text: 'Child',
+                parentRef: { blockUid: 'parent' },
+                order: 0,
+                open: true,
+                heading: null,
+            },
+            {
+                ref: { blockUid: 'grandchild' },
+                text: 'Grandchild',
+                parentRef: { blockUid: 'child' },
+                order: 0,
+                open: true,
+                heading: null,
+            },
+        ];
+        expect(getBlockDepth(blocks[1], blocks)).toBe(1);
+        expect(getBlockDepth(blocks[2], blocks)).toBe(2);
+    });
+});

package/build/diff/types.js

@@ -0,0 +1,27 @@
+/**
+ * Diff Algorithm Types
+ *
+ * Type definitions for the smart diff algorithm that computes minimal
+ * update operations when syncing markdown content to Roam.
+ */
+/**
+ * Extract statistics from a DiffResult.
+ */
+export function getDiffStats(result) {
+    return {
+        creates: result.creates.length,
+        updates: result.updates.length,
+        moves: result.moves.length,
+        deletes: result.deletes.length,
+        preserved: result.preservedUids.size,
+    };
+}
+/**
+ * Check if a diff result contains no changes.
+ */
+export function isDiffEmpty(result) {
+    return (result.creates.length === 0 &&
+        result.updates.length === 0 &&
+        result.moves.length === 0 &&
+        result.deletes.length === 0);
+}

package/build/diff/types.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { getDiffStats, isDiffEmpty } from './types.js';
+function createDiffResult(createCount = 0, updateCount = 0, moveCount = 0, deleteCount = 0, preservedCount = 0) {
+    return {
+        creates: Array(createCount).fill({ action: 'create-block' }),
+        updates: Array(updateCount).fill({ action: 'update-block' }),
+        moves: Array(moveCount).fill({ action: 'move-block' }),
+        deletes: Array(deleteCount).fill({ action: 'delete-block' }),
+        preservedUids: new Set(Array(preservedCount).fill(null).map((_, i) => `uid${i}`)),
+    };
+}
+describe('getDiffStats', () => {
+    it('returns correct counts for all operation types', () => {
+        const diff = createDiffResult(2, 3, 1, 4, 5);
+        const stats = getDiffStats(diff);
+        expect(stats.creates).toBe(2);
+        expect(stats.updates).toBe(3);
+        expect(stats.moves).toBe(1);
+        expect(stats.deletes).toBe(4);
+        expect(stats.preserved).toBe(5);
+    });
+    it('returns zeros for empty diff', () => {
+        const diff = createDiffResult();
+        const stats = getDiffStats(diff);
+        expect(stats.creates).toBe(0);
+        expect(stats.updates).toBe(0);
+        expect(stats.moves).toBe(0);
+        expect(stats.deletes).toBe(0);
+        expect(stats.preserved).toBe(0);
+    });
+});
+describe('isDiffEmpty', () => {
+    it('returns true when no operations exist', () => {
+        const diff = createDiffResult(0, 0, 0, 0, 5);
+        expect(isDiffEmpty(diff)).toBe(true);
+    });
+    it('returns false when creates exist', () => {
+        const diff = createDiffResult(1);
+        expect(isDiffEmpty(diff)).toBe(false);
+    });
+    it('returns false when updates exist', () => {
+        const diff = createDiffResult(0, 1);
+        expect(isDiffEmpty(diff)).toBe(false);
+    });
+    it('returns false when moves exist', () => {
+        const diff = createDiffResult(0, 0, 1);
+        expect(isDiffEmpty(diff)).toBe(false);
+    });
+    it('returns false when deletes exist', () => {
+        const diff = createDiffResult(0, 0, 0, 1);
+        expect(isDiffEmpty(diff)).toBe(false);
+    });
+    it('ignores preserved count when checking empty', () => {
+        const diff = createDiffResult(0, 0, 0, 0, 100);
+        expect(isDiffEmpty(diff)).toBe(true);
+    });
+});

package/build/markdown-utils.js

@@ -92,6 +92,51 @@ function parseMarkdown(markdown) {
             processedLines.push(line);
         }
     }
+    // First pass: collect all unique indentation values to build level mapping
+    const indentationSet = new Set();
+    indentationSet.add(0); // Always include level 0
+    let inCodeBlockFirstPass = false;
+    for (const line of processedLines) {
+        const trimmedLine = line.trimEnd();
+        if (trimmedLine.match(/^(\s*)```/)) {
+            inCodeBlockFirstPass = !inCodeBlockFirstPass;
+            if (!inCodeBlockFirstPass)
+                continue; // Skip closing ```
+            const indent = line.match(/^\s*/)?.[0].length ?? 0;
+            indentationSet.add(indent);
+            continue;
+        }
+        if (inCodeBlockFirstPass || trimmedLine === '')
+            continue;
+        const bulletMatch = trimmedLine.match(/^(\s*)[-*+]\s+/);
+        if (bulletMatch) {
+            indentationSet.add(bulletMatch[1].length);
+        }
+        else {
+            const indent = line.match(/^\s*/)?.[0].length ?? 0;
+            indentationSet.add(indent);
+        }
+    }
+    // Create sorted array of indentation values and map to sequential levels
+    const sortedIndents = Array.from(indentationSet).sort((a, b) => a - b);
+    const indentToLevel = new Map();
+    sortedIndents.forEach((indent, index) => {
+        indentToLevel.set(indent, index);
+    });
+    // Helper to get level from indentation, finding closest match
+    function getLevel(indent) {
+        if (indentToLevel.has(indent)) {
+            return indentToLevel.get(indent);
+        }
+        // Find the closest smaller indentation
+        let closestLevel = 0;
+        for (const [ind, lvl] of indentToLevel) {
+            if (ind <= indent && lvl > closestLevel) {
+                closestLevel = lvl;
+            }
+        }
+        return closestLevel;
+    }
     const rootNodes = [];
     const stack = [];
     let inCodeBlock = false;
@@ -133,7 +178,7 @@ function parseMarkdown(markdown) {
                     }
                     return codeLine.trimStart();
                 });
-                const level = Math.floor(codeBlockIndentation / 2);
+                const level = getLevel(codeBlockIndentation);
                 const node = {
                     content: processedCodeLines.join('\n'),
                     level,
@@ -169,17 +214,18 @@ function parseMarkdown(markdown) {
         if (trimmedLine === '') {
             continue;
         }
-        const indentation = line.match(/^\s*/)?.[0].length ?? 0;
-        let level = Math.floor(indentation / 2);
+        let indentation;
         let contentToParse;
         const bulletMatch = trimmedLine.match(/^(\s*)[-*+]\s+/);
         if (bulletMatch) {
-            level = Math.floor(bulletMatch[1].length / 2);
+            indentation = bulletMatch[1].length;
             contentToParse = trimmedLine.substring(bulletMatch[0].length);
         }
         else {
+            indentation = line.match(/^\s*/)?.[0].length ?? 0;
             contentToParse = trimmedLine;
         }
+        const level = getLevel(indentation);
         const { heading_level, content: finalContent } = parseMarkdownHeadingLevel(contentToParse);
         const node = {
             content: finalContent,
@@ -240,7 +286,7 @@ function parseTableRows(lines) {
     }
     return tableNodes;
 }
-function generateBlockUid() {
+export function generateBlockUid() {
     // Generate a random string of 9 characters (Roam's format) using crypto for better randomness
     const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_';
     // 64 chars, which divides 256 evenly (256 = 64 * 4), so simple modulo is unbiased

package/build/server/roam-server.js

@@ -11,7 +11,7 @@ import { join, dirname } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { findAvailablePort } from '../utils/net.js';
-import { CORS_ORIGIN } from '../config/environment.js';
+import { CORS_ORIGINS } from '../config/environment.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read package.json to get the version
@@ -211,6 +211,25 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
+                    case 'roam_create_table': {
+                        const { parent_uid, order, headers, rows } = request.params.arguments;
+                        const result = await this.toolHandlers.createTable({
+                            parent_uid,
+                            order,
+                            headers,
+                            rows
+                        });
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
+                    case 'roam_update_page_markdown': {
+                        const { title, markdown, dry_run = false } = request.params.arguments;
+                        const result = await this.toolHandlers.updatePageMarkdown(title, markdown, dry_run);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }
@@ -229,23 +248,70 @@ export class RoamServer {
             const stdioMcpServer = this.createMcpServer();
             const stdioTransport = new StdioServerTransport();
             await stdioMcpServer.connect(stdioTransport);
-            const httpMcpServer = this.createMcpServer('-http');
-            const httpStreamTransport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
-            });
-            await httpMcpServer.connect(httpStreamTransport);
+            // Track active transports by session ID for proper session management
+            const activeSessions = new Map();
             const httpServer = createServer(async (req, res) => {
-                // Set CORS headers
-                res.setHeader('Access-Control-Allow-Origin', CORS_ORIGIN);
-                res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-                res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+                // Set CORS headers dynamically based on request origin
+                const requestOrigin = req.headers.origin;
+                if (requestOrigin && CORS_ORIGINS.includes(requestOrigin)) {
+                    res.setHeader('Access-Control-Allow-Origin', requestOrigin);
+                }
+                else if (CORS_ORIGINS.includes('*')) {
+                    res.setHeader('Access-Control-Allow-Origin', '*');
+                }
+                res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Mcp-Session-Id');
+                res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+                res.setHeader('Access-Control-Allow-Credentials', 'true');
                 // Handle preflight OPTIONS requests
                 if (req.method === 'OPTIONS') {
                     res.writeHead(204); // No Content
                     res.end();
                     return;
                 }
+                // Check for existing session ID in header
+                const sessionId = req.headers['mcp-session-id'];
+                // Handle session termination (DELETE request)
+                if (req.method === 'DELETE' && sessionId) {
+                    const transport = activeSessions.get(sessionId);
+                    if (transport) {
+                        await transport.close();
+                        activeSessions.delete(sessionId);
+                        res.writeHead(200);
+                        res.end();
+                    }
+                    else {
+                        res.writeHead(404, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Session not found' }));
+                    }
+                    return;
+                }
                 try {
+                    // If we have an existing session, use that transport
+                    if (sessionId && activeSessions.has(sessionId)) {
+                        const transport = activeSessions.get(sessionId);
+                        await transport.handleRequest(req, res);
+                        return;
+                    }
+                    // Create new transport and server for new sessions
+                    const httpMcpServer = this.createMcpServer('-http');
+                    const httpStreamTransport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
+                        onsessioninitialized: (newSessionId) => {
+                            activeSessions.set(newSessionId, httpStreamTransport);
+                        }
+                    });
+                    // Clean up session when transport closes
+                    httpStreamTransport.onclose = () => {
+                        const entries = activeSessions.entries();
+                        for (const [key, value] of entries) {
+                            if (value === httpStreamTransport) {
+                                activeSessions.delete(key);
+                                break;
+                            }
+                        }
+                    };
+                    await httpMcpServer.connect(httpStreamTransport);
                     await httpStreamTransport.handleRequest(req, res);
                 }
                 catch (error) {

package/build/shared/errors.js

@@ -0,0 +1,84 @@
+/**
+ * Structured error types for the Roam MCP server.
+ * Provides consistent error handling across all tools.
+ */
+/**
+ * Creates a structured validation error response.
+ */
+export function createValidationError(message, details, recovery) {
+    return {
+        code: 'VALIDATION_ERROR',
+        message,
+        details,
+        recovery
+    };
+}
+/**
+ * Creates a structured rate limit error response.
+ */
+export function createRateLimitError(retryAfterMs) {
+    return {
+        code: 'RATE_LIMIT',
+        message: 'Too many requests, please retry after backoff',
+        recovery: {
+            retry_after_ms: retryAfterMs ?? 60000,
+            suggestion: 'Wait for the specified duration before retrying'
+        }
+    };
+}
+/**
+ * Creates a structured API error response.
+ */
+export function createApiError(message, details) {
+    return {
+        code: 'API_ERROR',
+        message,
+        details
+    };
+}
+/**
+ * Creates a structured transaction failed error response.
+ */
+export function createTransactionFailedError(message, failedAtAction, committed) {
+    return {
+        success: false,
+        error: {
+            code: 'TRANSACTION_FAILED',
+            message,
+            details: failedAtAction !== undefined ? { action_index: failedAtAction } : undefined
+        },
+        committed
+    };
+}
+/**
+ * Checks if an error is a rate limit error based on error message.
+ */
+export function isRateLimitError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return message.includes('too many requests') ||
+            message.includes('rate limit') ||
+            message.includes('try again in');
+    }
+    if (typeof error === 'string') {
+        const message = error.toLowerCase();
+        return message.includes('too many requests') ||
+            message.includes('rate limit') ||
+            message.includes('try again in');
+    }
+    return false;
+}
+/**
+ * Checks if an error is a network error.
+ */
+export function isNetworkError(error) {
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return message.includes('network') ||
+            message.includes('econnrefused') ||
+            message.includes('econnreset') ||
+            message.includes('etimedout') ||
+            message.includes('socket');
+    }
+    return false;
+}

package/build/shared/index.js

@@ -0,0 +1,5 @@
+/**
+ * Shared utilities for the Roam MCP server.
+ */
+export * from './validation.js';
+export * from './errors.js';