roam-research-mcp 0.36.0 → 1.3.2

package/build/cache/page-uid-cache.js

@@ -0,0 +1,55 @@
+/**
+ * Simple in-memory cache for page title -> UID mappings.
+ * Pages are stable entities that rarely get deleted, making them safe to cache.
+ * This reduces redundant API queries when looking up the same page multiple times.
+ */
+class PageUidCache {
+    constructor() {
+        this.cache = new Map(); // title (lowercase) -> UID
+    }
+    /**
+     * Get a cached page UID by title.
+     * @param title - Page title (case-insensitive)
+     * @returns The cached UID or undefined if not cached
+     */
+    get(title) {
+        return this.cache.get(title.toLowerCase());
+    }
+    /**
+     * Cache a page title -> UID mapping.
+     * @param title - Page title (will be stored lowercase)
+     * @param uid - Page UID
+     */
+    set(title, uid) {
+        this.cache.set(title.toLowerCase(), uid);
+    }
+    /**
+     * Check if a page title is cached.
+     * @param title - Page title (case-insensitive)
+     */
+    has(title) {
+        return this.cache.has(title.toLowerCase());
+    }
+    /**
+     * Called when a page is created - immediately add to cache.
+     * @param title - Page title
+     * @param uid - Page UID
+     */
+    onPageCreated(title, uid) {
+        this.set(title, uid);
+    }
+    /**
+     * Clear the cache (useful for testing or session reset).
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the current cache size.
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+// Singleton instance - shared across all operations
+export const pageUidCache = new PageUidCache();

package/build/cli/import-markdown.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { API_TOKEN, GRAPH_NAME } from '../config/environment.js';
+import { PageOperations } from '../tools/operations/pages.js';
+import { parseMarkdown } from '../markdown-utils.js';
+/**
+ * Flatten nested MarkdownNode[] to flat array with absolute levels
+ */
+function flattenNodes(nodes, baseLevel = 1) {
+    const result = [];
+    for (const node of nodes) {
+        result.push({
+            text: node.content,
+            level: baseLevel,
+            ...(node.heading_level && { heading: node.heading_level })
+        });
+        if (node.children.length > 0) {
+            result.push(...flattenNodes(node.children, baseLevel + 1));
+        }
+    }
+    return result;
+}
+/**
+ * Read all input from stdin
+ */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/**
+ * Show usage help
+ */
+function showUsage() {
+    console.error('Usage: roam-import <page-title>');
+    console.error('');
+    console.error('Reads markdown from stdin and imports to Roam Research.');
+    console.error('');
+    console.error('Examples:');
+    console.error('  cat document.md | roam-import "Meeting Notes"');
+    console.error('  pbpaste | roam-import "Ideas"');
+    console.error('  echo "- Item 1\\n- Item 2" | roam-import "Quick Note"');
+    console.error('');
+    console.error('Environment variables required:');
+    console.error('  ROAM_API_TOKEN   Your Roam Research API token');
+    console.error('  ROAM_GRAPH_NAME  Your Roam graph name');
+}
+async function main() {
+    // Parse CLI arguments
+    const args = process.argv.slice(2);
+    const pageTitle = args[0];
+    if (!pageTitle || pageTitle === '--help' || pageTitle === '-h') {
+        showUsage();
+        process.exit(pageTitle ? 0 : 1);
+    }
+    // Check if stdin is a TTY (no input piped)
+    if (process.stdin.isTTY) {
+        console.error('Error: No input received. Pipe markdown content to this command.');
+        console.error('');
+        showUsage();
+        process.exit(1);
+    }
+    // Read markdown from stdin
+    const markdownContent = await readStdin();
+    if (!markdownContent.trim()) {
+        console.error('Error: Empty input received.');
+        process.exit(1);
+    }
+    // Initialize Roam graph
+    const graph = initializeGraph({
+        token: API_TOKEN,
+        graph: GRAPH_NAME
+    });
+    // Parse markdown to nodes
+    const nodes = parseMarkdown(markdownContent);
+    // Flatten nested structure to content blocks
+    const contentBlocks = flattenNodes(nodes);
+    if (contentBlocks.length === 0) {
+        console.error('Error: No content blocks parsed from input.');
+        process.exit(1);
+    }
+    // Create page with content
+    const pageOps = new PageOperations(graph);
+    const result = await pageOps.createPage(pageTitle, contentBlocks);
+    if (result.success) {
+        console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
+    }
+    else {
+        console.error(`Failed to create page '${pageTitle}'`);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+});

package/build/config/environment.js

@@ -29,7 +29,7 @@ if (!API_TOKEN || !GRAPH_NAME) {
         '     "mcpServers": {\n' +
         '       "roam-research": {\n' +
         '         "command": "node",\n' +
-        '         "args": ["/path/to/roam-research/build/index.js"],\n' +
+        '         "args": ["/path/to/roam-research-mcp/build/index.js"],\n' +
         '         "env": {\n' +
         '           "ROAM_API_TOKEN": "your-api-token",\n' +
         '           "ROAM_GRAPH_NAME": "your-graph-name"\n' +
@@ -42,6 +42,7 @@ if (!API_TOKEN || !GRAPH_NAME) {
         '   ROAM_GRAPH_NAME=your-graph-name');
 }
 const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088'; // Default to 8088
-const SSE_PORT = process.env.SSE_PORT || '8087'; // Default to 8087
-const CORS_ORIGIN = process.env.CORS_ORIGIN || 'http://localhost:5678';
-export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT, CORS_ORIGIN };
+const CORS_ORIGINS = (process.env.CORS_ORIGIN || 'http://localhost:5678,https://roamresearch.com')
+    .split(',')
+    .map(origin => origin.trim());
+export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, CORS_ORIGINS };

package/build/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
 import { RoamServer } from './server/roam-server.js';
 const server = new RoamServer();
-server.run().catch(() => { });
+server.run().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

package/build/markdown-utils.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'crypto';
 /**
  * Check if text has a traditional markdown table
  */
@@ -91,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;
@@ -132,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,
@@ -168,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,
@@ -239,12 +286,14 @@ function parseTableRows(lines) {
     }
     return tableNodes;
 }
-function generateBlockUid() {
-    // Generate a random string of 9 characters (Roam's format)
+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
+    const bytes = randomBytes(9);
     let uid = '';
     for (let i = 0; i < 9; i++) {
-        uid += chars.charAt(Math.floor(Math.random() * chars.length));
+        uid += chars[bytes[i] % 64];
     }
     return uid;
 }

package/build/search/datomic-search.js

@@ -8,7 +8,46 @@ export class DatomicSearchHandler extends BaseSearchHandler {
     async execute() {
         try {
             // Execute the datomic query using the Roam API
-            const results = await q(this.graph, this.params.query, this.params.inputs || []);
+            let results = await q(this.graph, this.params.query, this.params.inputs || []);
+            if (this.params.regexFilter) {
+                let regex;
+                try {
+                    regex = new RegExp(this.params.regexFilter, this.params.regexFlags);
+                }
+                catch (e) {
+                    return {
+                        success: false,
+                        matches: [],
+                        message: `Invalid regex filter provided: ${e instanceof Error ? e.message : String(e)}`
+                    };
+                }
+                results = results.filter(result => {
+                    if (this.params.regexTargetField && this.params.regexTargetField.length > 0) {
+                        for (const field of this.params.regexTargetField) {
+                            // Access nested fields if path is provided (e.g., "prop.nested")
+                            const fieldPath = field.split('.');
+                            let value = result;
+                            for (const part of fieldPath) {
+                                if (typeof value === 'object' && value !== null && part in value) {
+                                    value = value[part];
+                                }
+                                else {
+                                    value = undefined; // Field not found
+                                    break;
+                                }
+                            }
+                            if (typeof value === 'string' && regex.test(value)) {
+                                return true;
+                            }
+                        }
+                        return false;
+                    }
+                    else {
+                        // Default to stringifying the whole result if no target field is specified
+                        return regex.test(JSON.stringify(result));
+                    }
+                });
+            }
             return {
                 success: true,
                 matches: results.map(result => ({

package/build/server/roam-server.js

@@ -1,7 +1,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ListToolsRequestSchema, ListPromptsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initializeGraph } from '@roam-research/roam-api-sdk';
 import { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT } from '../config/environment.js';
 import { toolSchemas } from '../tools/schemas.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
@@ -20,7 +20,6 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 const serverVersion = packageJson.version;
 export class RoamServer {
     constructor() {
-        // console.log('RoamServer: Constructor started.');
         try {
             this.graph = initializeGraph({
                 token: API_TOKEN,
@@ -42,7 +41,23 @@ export class RoamServer {
         if (Object.keys(toolSchemas).length === 0) {
             throw new McpError(ErrorCode.InternalError, 'No tool schemas defined in src/tools/schemas.ts');
         }
-        // console.log('RoamServer: Constructor finished.');
+    }
+    // Helper to create and configure MCP server instance
+    createMcpServer(nameSuffix = '') {
+        const server = new Server({
+            name: `roam-research${nameSuffix}`,
+            version: serverVersion,
+        }, {
+            capabilities: {
+                tools: {
+                    ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, toolSchemas[toolName].inputSchema])),
+                },
+                resources: {}, // No resources exposed via capabilities
+                prompts: {}, // No prompts exposed via capabilities
+            },
+        });
+        this.setupRequestHandlers(server);
+        return server;
     }
     // Refactored to accept a Server instance
     setupRequestHandlers(mcpServer) {
@@ -59,6 +74,10 @@ export class RoamServer {
         mcpServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`);
         });
+        // List available prompts
+        mcpServer.setRequestHandler(ListPromptsRequestSchema, async () => {
+            return { prompts: [] };
+        });
         // Handle tool calls
         mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
@@ -192,6 +211,18 @@ 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) }],
+                        };
+                    }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }
@@ -206,65 +237,77 @@ export class RoamServer {
         });
     }
     async run() {
-        // console.log('RoamServer: run() method started.');
         try {
-            // console.log('RoamServer: Attempting to create stdioMcpServer...');
-            const stdioMcpServer = new Server({
-                name: 'roam-research',
-                version: serverVersion,
-            }, {
-                capabilities: {
-                    tools: {
-                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, toolSchemas[toolName].inputSchema])),
-                    },
-                    resources: {
-                        'roam-markdown-cheatsheet.md': {}
-                    }
-                },
-            });
-            // console.log('RoamServer: stdioMcpServer created. Setting up request handlers...');
-            this.setupRequestHandlers(stdioMcpServer);
-            // console.log('RoamServer: stdioMcpServer handlers setup complete. Connecting transport...');
+            const stdioMcpServer = this.createMcpServer();
             const stdioTransport = new StdioServerTransport();
             await stdioMcpServer.connect(stdioTransport);
-            // console.log('RoamServer: stdioTransport connected. Attempting to create httpMcpServer...');
-            const httpMcpServer = new Server({
-                name: 'roam-research-http', // A distinct name for the HTTP server
-                version: serverVersion,
-            }, {
-                capabilities: {
-                    tools: {
-                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, toolSchemas[toolName].inputSchema])),
-                    },
-                    resources: {
-                        'roam-markdown-cheatsheet.md': {}
-                    }
-                },
-            });
-            // console.log('RoamServer: httpMcpServer created. Setting up request handlers...');
-            this.setupRequestHandlers(httpMcpServer);
-            // console.log('RoamServer: httpMcpServer handlers setup complete. Connecting transport...');
-            const httpStreamTransport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
-            });
-            await httpMcpServer.connect(httpStreamTransport);
-            // console.log('RoamServer: httpStreamTransport connected.');
+            // 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) {
-                    // // console.error('HTTP Stream Server error:', error);
                     if (!res.headersSent) {
                         res.writeHead(500, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({ error: 'Internal Server Error' }));
@@ -273,7 +316,6 @@ export class RoamServer {
             });
             const availableHttpPort = await findAvailablePort(parseInt(HTTP_STREAM_PORT));
             httpServer.listen(availableHttpPort, () => {
-                // // console.log(`MCP Roam Research server running HTTP Stream on port ${availableHttpPort}`);
             });
         }
         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';