roam-research-mcp 1.0.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

@@ -42,5 +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 CORS_ORIGIN = process.env.CORS_ORIGIN || 'http://localhost:5678';
-export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_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/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,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}`);
                 }
@@ -229,23 +241,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';