roam-research-mcp 1.6.0 → 2.4.0

package/build/config/environment.js

@@ -9,40 +9,76 @@ const envPath = join(projectRoot, '.env');
 if (existsSync(envPath)) {
     dotenv.config({ path: envPath });
 }
-// Required environment variables
-const API_TOKEN = process.env.ROAM_API_TOKEN;
-const GRAPH_NAME = process.env.ROAM_GRAPH_NAME;
-// Validate environment variables
-if (!API_TOKEN || !GRAPH_NAME) {
-    const missingVars = [];
-    if (!API_TOKEN)
-        missingVars.push('ROAM_API_TOKEN');
-    if (!GRAPH_NAME)
-        missingVars.push('ROAM_GRAPH_NAME');
-    throw new Error(`Missing required environment variables: ${missingVars.join(', ')}\n\n` +
-        'Please configure these variables either:\n' +
-        '1. In your MCP settings file:\n' +
-        '   - For Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json\n' +
-        '   - For Claude: ~/Library/Application Support/Claude/claude_desktop_config.json\n\n' +
-        '   Example configuration:\n' +
-        '   {\n' +
-        '     "mcpServers": {\n' +
-        '       "roam-research": {\n' +
-        '         "command": "node",\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' +
-        '         }\n' +
-        '       }\n' +
-        '     }\n' +
-        '   }\n\n' +
-        '2. Or in a .env file in the roam-research directory:\n' +
-        '   ROAM_API_TOKEN=your-api-token\n' +
-        '   ROAM_GRAPH_NAME=your-graph-name');
-}
-const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088'; // Default to 8088
+// HTTP server configuration
+const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088';
 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 };
+// Re-export for backwards compatibility with single-graph mode
+// These are still used by CLI commands and for validation
+const API_TOKEN = process.env.ROAM_API_TOKEN;
+const GRAPH_NAME = process.env.ROAM_GRAPH_NAME;
+// Multi-graph mode configuration
+const ROAM_GRAPHS = process.env.ROAM_GRAPHS;
+const ROAM_DEFAULT_GRAPH = process.env.ROAM_DEFAULT_GRAPH;
+/**
+ * Check if we're in multi-graph mode
+ */
+export function isMultiGraphMode() {
+    return !!ROAM_GRAPHS;
+}
+/**
+ * Validate that either multi-graph or single-graph configuration is provided
+ * Called during server/CLI initialization
+ */
+export function validateEnvironment() {
+    if (ROAM_GRAPHS) {
+        // Multi-graph mode
+        if (!ROAM_DEFAULT_GRAPH) {
+            throw new Error('ROAM_DEFAULT_GRAPH is required when using ROAM_GRAPHS.\n' +
+                'Set it to the key of the graph to use by default.');
+        }
+        // Validate JSON
+        try {
+            JSON.parse(ROAM_GRAPHS);
+        }
+        catch (e) {
+            throw new Error(`Invalid JSON in ROAM_GRAPHS: ${e.message}`);
+        }
+    }
+    else {
+        // Single-graph mode - require legacy env vars
+        if (!API_TOKEN || !GRAPH_NAME) {
+            const missingVars = [];
+            if (!API_TOKEN)
+                missingVars.push('ROAM_API_TOKEN');
+            if (!GRAPH_NAME)
+                missingVars.push('ROAM_GRAPH_NAME');
+            throw new Error(`Missing required environment variables: ${missingVars.join(', ')}\n\n` +
+                'Please configure these variables either:\n' +
+                '1. In your MCP settings file:\n' +
+                '   - For Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json\n' +
+                '   - For Claude: ~/Library/Application Support/Claude/claude_desktop_config.json\n\n' +
+                '   Example configuration:\n' +
+                '   {\n' +
+                '     "mcpServers": {\n' +
+                '       "roam-research": {\n' +
+                '         "command": "node",\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' +
+                '         }\n' +
+                '       }\n' +
+                '     }\n' +
+                '   }\n\n' +
+                '2. Or in a .env file in the roam-research directory:\n' +
+                '   ROAM_API_TOKEN=your-api-token\n' +
+                '   ROAM_GRAPH_NAME=your-graph-name\n\n' +
+                '3. Or use multi-graph mode:\n' +
+                '   ROAM_GRAPHS=\'{"personal": {"token": "...", "graph": "..."}}\'\n' +
+                '   ROAM_DEFAULT_GRAPH=personal');
+        }
+    }
+}
+export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, CORS_ORIGINS, ROAM_GRAPHS, ROAM_DEFAULT_GRAPH };

package/build/config/graph-registry.js

@@ -0,0 +1,221 @@
+/**
+ * GraphRegistry - Manages multiple Roam graph connections with safety guardrails
+ *
+ * Supports:
+ * - Multiple graph configurations via ROAM_GRAPHS env var
+ * - Backwards compatibility with single graph via ROAM_API_TOKEN/ROAM_GRAPH_NAME
+ * - Write protection for non-default graphs via write_key confirmation
+ * - Lazy graph initialization (connects only when first accessed)
+ */
+import { initializeGraph } from '@roam-research/roam-api-sdk';
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+/** List of tool names that perform write operations */
+export const WRITE_OPERATIONS = [
+    'roam_create_page',
+    'roam_create_outline',
+    'roam_import_markdown',
+    'roam_process_batch_actions',
+    'roam_add_todo',
+    'roam_remember',
+    'roam_create_table',
+    'roam_move_block',
+    'roam_update_page_markdown',
+    'roam_rename_page',
+];
+/**
+ * Check if a tool name is a write operation
+ */
+export function isWriteOperation(toolName) {
+    return WRITE_OPERATIONS.includes(toolName);
+}
+/**
+ * GraphRegistry - Central manager for multiple Roam graph connections
+ */
+export class GraphRegistry {
+    constructor(configs, defaultKey) {
+        this.configs = new Map(Object.entries(configs));
+        this.initialized = new Map();
+        this.defaultKey = defaultKey;
+        this.isMultiGraph = this.configs.size > 1;
+        // Validate default key exists
+        if (!this.configs.has(defaultKey)) {
+            throw new Error(`Default graph key "${defaultKey}" not found in configuration`);
+        }
+    }
+    /**
+     * Get configuration for a graph by key
+     */
+    getConfig(key) {
+        return this.configs.get(key);
+    }
+    /**
+     * Get all available graph keys
+     */
+    getAvailableGraphs() {
+        return Array.from(this.configs.keys());
+    }
+    /**
+     * Get an initialized Graph instance, creating it lazily if needed
+     * @param key - Graph key from config. Defaults to defaultKey if not specified.
+     */
+    getGraph(key) {
+        const resolvedKey = key ?? this.defaultKey;
+        // Check if already initialized
+        const existing = this.initialized.get(resolvedKey);
+        if (existing) {
+            return existing;
+        }
+        // Get config
+        const config = this.configs.get(resolvedKey);
+        if (!config) {
+            throw new McpError(ErrorCode.InvalidParams, `Unknown graph: "${resolvedKey}". Available graphs: ${this.getAvailableGraphs().join(', ')}`);
+        }
+        // Initialize the graph
+        const graph = initializeGraph({
+            token: config.token,
+            graph: config.graph,
+        });
+        this.initialized.set(resolvedKey, graph);
+        return graph;
+    }
+    /**
+     * Check if a write operation is allowed for a given graph
+     *
+     * Rules:
+     * - Writes to default graph are always allowed
+     * - Writes to non-default graphs require:
+     *   - If write_key is configured: must provide matching write_key
+     *   - If no write_key configured: writes are allowed
+     */
+    isWriteAllowed(graphKey, providedWriteKey) {
+        const resolvedKey = graphKey ?? this.defaultKey;
+        // Writes to default graph are always allowed
+        if (resolvedKey === this.defaultKey) {
+            return true;
+        }
+        const config = this.configs.get(resolvedKey);
+        if (!config) {
+            return false; // Unknown graph
+        }
+        // If no write_key is configured, allow writes
+        if (!config.write_key) {
+            return true;
+        }
+        // Check if provided key matches
+        return providedWriteKey === config.write_key;
+    }
+    /**
+     * Validate write access and return an informative error if denied
+     */
+    validateWriteAccess(toolName, graphKey, providedWriteKey) {
+        if (!isWriteOperation(toolName)) {
+            return; // Not a write operation, no validation needed
+        }
+        const resolvedKey = graphKey ?? this.defaultKey;
+        if (!this.isWriteAllowed(resolvedKey, providedWriteKey)) {
+            const config = this.configs.get(resolvedKey);
+            if (!config) {
+                throw new McpError(ErrorCode.InvalidParams, `Unknown graph: "${resolvedKey}". Available graphs: ${this.getAvailableGraphs().join(', ')}`);
+            }
+            // Provide informative error with the required key
+            throw new McpError(ErrorCode.InvalidParams, `Write to "${resolvedKey}" graph requires write_key confirmation.\n` +
+                `Provide write_key: "${config.write_key}" to proceed.`);
+        }
+    }
+    /**
+     * Resolve graph key and validate access for a tool call
+     * Returns the Graph instance ready to use
+     */
+    resolveGraphForTool(toolName, graphKey, writeKey) {
+        // Validate write access if this is a write operation
+        this.validateWriteAccess(toolName, graphKey, writeKey);
+        // Return the graph instance
+        return this.getGraph(graphKey);
+    }
+    /**
+     * Generate markdown documentation about available graphs and their configuration
+     * Used to inform AI models about graph access requirements
+     */
+    getGraphInfoMarkdown() {
+        const graphKeys = this.getAvailableGraphs();
+        // Single graph mode - minimal info
+        if (graphKeys.length === 1 && graphKeys[0] === 'default') {
+            return ''; // No need to show graph info in single-graph mode
+        }
+        const lines = [
+            '## Available Graphs',
+            '',
+            '| Graph | Default | Write Protected |',
+            '|-------|---------|-----------------|',
+        ];
+        for (const key of graphKeys) {
+            const config = this.configs.get(key);
+            const isDefault = key === this.defaultKey;
+            const isProtected = !!config.write_key;
+            const defaultCol = isDefault ? '✓' : '';
+            const protectedCol = isProtected
+                ? `Yes (requires \`write_key: "${config.write_key}"\`)`
+                : 'No';
+            lines.push(`| ${key} | ${defaultCol} | ${protectedCol} |`);
+        }
+        lines.push('');
+        lines.push('> **Note:** Write operations to protected graphs require the `write_key` parameter.');
+        lines.push('');
+        lines.push('---');
+        lines.push('');
+        return lines.join('\n');
+    }
+}
+/**
+ * Create a GraphRegistry from environment variables
+ *
+ * Supports two modes:
+ * 1. Multi-graph: ROAM_GRAPHS JSON + ROAM_DEFAULT_GRAPH
+ * 2. Single graph (backwards compat): ROAM_API_TOKEN + ROAM_GRAPH_NAME
+ */
+export function createRegistryFromEnv() {
+    const roamGraphsJson = process.env.ROAM_GRAPHS;
+    if (roamGraphsJson) {
+        // Multi-graph mode
+        try {
+            const configs = JSON.parse(roamGraphsJson);
+            const defaultKey = process.env.ROAM_DEFAULT_GRAPH?.trim().replace(/,+$/, '');
+            if (!defaultKey) {
+                throw new Error('ROAM_DEFAULT_GRAPH is required when using ROAM_GRAPHS');
+            }
+            return new GraphRegistry(configs, defaultKey);
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error(`Invalid JSON in ROAM_GRAPHS: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    // Backwards compatibility: single graph mode
+    const token = process.env.ROAM_API_TOKEN;
+    const graphName = process.env.ROAM_GRAPH_NAME;
+    if (!token || !graphName) {
+        const missingVars = [];
+        if (!token)
+            missingVars.push('ROAM_API_TOKEN');
+        if (!graphName)
+            missingVars.push('ROAM_GRAPH_NAME');
+        throw new Error(`Missing required environment variables: ${missingVars.join(', ')}\n\n` +
+            'Configure either:\n' +
+            '1. Multi-graph mode:\n' +
+            '   ROAM_GRAPHS=\'{"personal": {"token": "...", "graph": "..."}}\'\n' +
+            '   ROAM_DEFAULT_GRAPH=personal\n\n' +
+            '2. Single graph mode (backwards compatible):\n' +
+            '   ROAM_API_TOKEN=your-api-token\n' +
+            '   ROAM_GRAPH_NAME=your-graph-name');
+    }
+    // Create single-graph registry with "default" as the key
+    const configs = {
+        default: {
+            token,
+            graph: graphName,
+        }
+    };
+    return new GraphRegistry(configs, 'default');
+}

package/build/config/graph-registry.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { GraphRegistry } from './graph-registry.js';
+describe('GraphRegistry', () => {
+    describe('getGraphInfoMarkdown', () => {
+        it('returns empty string for single-graph mode with default key', () => {
+            const registry = new GraphRegistry({ default: { token: 'token', graph: 'graph' } }, 'default');
+            expect(registry.getGraphInfoMarkdown()).toBe('');
+        });
+        it('returns markdown table for multi-graph mode', () => {
+            const registry = new GraphRegistry({
+                personal: { token: 'token1', graph: 'personal-graph' },
+                work: { token: 'token2', graph: 'work-graph', write_key: 'confirm' },
+            }, 'personal');
+            const markdown = registry.getGraphInfoMarkdown();
+            expect(markdown).toContain('## Available Graphs');
+            expect(markdown).toContain('| personal | ✓ | No |');
+            expect(markdown).toContain('| work |  | Yes (requires `write_key: "confirm"`) |');
+            expect(markdown).toContain('> **Note:** Write operations to protected graphs');
+        });
+        it('shows write protection for default graph if configured', () => {
+            const registry = new GraphRegistry({
+                main: { token: 'token1', graph: 'main-graph', write_key: 'secret' },
+                backup: { token: 'token2', graph: 'backup-graph' },
+            }, 'main');
+            const markdown = registry.getGraphInfoMarkdown();
+            expect(markdown).toContain('| main | ✓ | Yes (requires `write_key: "secret"`) |');
+            expect(markdown).toContain('| backup |  | No |');
+        });
+    });
+});

package/build/search/status-search.js

@@ -17,14 +17,15 @@ export class StatusSearchHandler extends BaseSearchHandler {
         // Build query based on whether we're searching in a specific page
         let queryStr;
         let queryParams;
+        // Search for "{{TODO" or "{{DONE" which matches both {{[[TODO]]}} and {{TODO}} formats
         if (targetPageUid) {
             queryStr = `[:find ?block-uid ?block-str
                   :in $ ?status ?page-uid
                   :where [?p :block/uid ?page-uid]
                          [?b :block/page ?p]
-         [?b :block/string ?block-str]
-         [?b :block/uid ?block-uid]
-         [(clojure.string/includes? ?block-str (str "{{[[" ?status "]]}}"))]]`;
+                         [?b :block/string ?block-str]
+                         [?b :block/uid ?block-uid]
+                         [(clojure.string/includes? ?block-str (str "{{" ?status))]]`;
             queryParams = [status, targetPageUid];
         }
         else {
@@ -34,7 +35,7 @@ export class StatusSearchHandler extends BaseSearchHandler {
                          [?b :block/uid ?block-uid]
                          [?b :block/page ?p]
                          [?p :node/title ?page-title]
-                         [(clojure.string/includes? ?block-str (str "{{[[" ?status "]]}}"))]]`;
+                         [(clojure.string/includes? ?block-str (str "{{" ?status))]]`;
             queryParams = [status];
         }
         const rawResults = await q(this.graph, queryStr, queryParams);