roam-research-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ian Shen / 2B3 PRODUCTIONS LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# Roam Research MCP Server
+
+[![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)
+
+A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface.
+
+## Installation
+
+You can install the package globally:
+
+```bash
+npm install -g roam-research-mcp
+```
+
+Or clone the repository and build from source:
+
+```bash
+git clone https://github.com/2b3pro/roam-research-mcp.git
+cd roam-research-mcp
+npm install
+npm run build
+```
+
+## Features
+
+The server provides six powerful tools for interacting with Roam Research:
+
+1. `roam_fetch_page_by_title`: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep
+2. `roam_create_page`: Create new pages with optional content
+3. `roam_create_block`: Create new blocks in a page (defaults to today's daily page)
+4. `roam_import_markdown`: Import nested markdown content under specific blocks
+5. `roam_add_todo`: Add multiple todo items to today's daily page with checkbox syntax
+6. `roam_create_outline`: Create hierarchical outlines with proper nesting and structure
+
+## Setup
+
+1. Create a Roam Research API token:
+
+   - Go to your graph settings
+   - Navigate to the "API tokens" section
+   - Create a new token
+
+2. Configure the environment variables:
+   You have two options for configuring the required environment variables:
+
+   Option 1: Using a .env file (Recommended for development)
+   Create a `.env` file in the roam-research directory:
+
+   ```
+   ROAM_API_TOKEN=your-api-token
+   ROAM_GRAPH_NAME=your-graph-name
+   ```
+
+   Option 2: Using MCP settings (Alternative method)
+   Add the configuration to your MCP settings file:
+
+   - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "roam-research": {
+         "command": "node",
+         "args": ["/path/to/roam-research/build/index.js"],
+         "env": {
+           "ROAM_API_TOKEN": "your-api-token",
+           "ROAM_GRAPH_NAME": "your-graph-name"
+         }
+       }
+     }
+   }
+   ```
+
+   - For Claude desktop app (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "roam-research": {
+         "command": "node",
+         "args": ["/path/to/roam-research/build/index.js"],
+         "env": {
+           "ROAM_API_TOKEN": "your-api-token",
+           "ROAM_GRAPH_NAME": "your-graph-name"
+         }
+       }
+     }
+   }
+   ```
+
+   Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.
+
+3. Build the server:
+   ```bash
+   cd roam-research
+   npm install
+   npm run build
+   ```
+
+## Usage
+
+### Fetch Page By Title
+
+Fetch and read a page's content with resolved block references:
+
+```typescript
+use_mcp_tool roam-research roam_fetch_page_by_title {
+  "title": "Example Page"
+}
+```
+
+Returns the page content as markdown with:
+
+- Complete hierarchical structure
+- Block references recursively resolved (up to 4 levels deep)
+- Proper indentation for nesting levels
+- Full markdown formatting
+
+### Create Page
+
+Create a new page with optional content:
+
+```typescript
+use_mcp_tool roam-research roam_create_page {
+  "title": "New Page",
+  "content": "Initial content for the page"
+}
+```
+
+Returns the created page's UID on success.
+
+### Create Block
+
+Add a new block to a page (defaults to today's daily page if neither page_uid nor title provided):
+
+```typescript
+use_mcp_tool roam-research roam_create_block {
+  "content": "Block content",
+  "page_uid": "optional-target-page-uid",
+  "title": "optional-target-page-title"
+}
+```
+
+You can specify either:
+
+- `page_uid`: Direct reference to target page
+- `title`: Name of target page (will be created if it doesn't exist)
+- Neither: Block will be added to today's daily page
+
+Returns:
+
+```json
+{
+  "success": true,
+  "block_uid": "created-block-uid",
+  "parent_uid": "parent-page-uid"
+}
+```
+
+### Create Outline
+
+Create a hierarchical outline with proper nesting and structure:
+
+```typescript
+use_mcp_tool roam-research roam_create_outline {
+  "outline": [
+    {
+      "text": "I. Top Level",
+      "level": 1
+    },
+    {
+      "text": "A. Second Level",
+      "level": 2
+    },
+    {
+      "text": "1. Third Level",
+      "level": 3
+    }
+  ],
+  "page_title_uid": "optional-target-page",
+  "block_text_uid": "optional-header-text"
+}
+```
+
+Features:
+
+- Create complex outlines with up to 10 levels of nesting
+- Validate outline structure and content
+- Maintain proper parent-child relationships
+- Optional header block for the outline
+- Defaults to today's daily page if no page specified
+- Efficient batch operations for creating blocks
+
+Parameters:
+
+- `outline`: Array of outline items, each with:
+  - `text`: Content of the outline item (required)
+  - `level`: Nesting level (1-10, required)
+- `page_title_uid`: Target page title or UID (optional, defaults to today's page)
+- `block_text_uid`: Header text for the outline (optional)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "page_uid": "target-page-uid",
+  "parent_uid": "header-block-uid",
+  "created_uids": ["uid1", "uid2", ...]
+}
+```
+
+### Add Todo Items
+
+Add one or more todo items to today's daily page:
+
+```typescript
+use_mcp_tool roam-research roam_add_todo {
+  "todos": [
+    "First todo item",
+    "Second todo item",
+    "Third todo item"
+  ]
+}
+```
+
+Features:
+
+- Adds todos with Roam checkbox syntax (`{{TODO}} todo text`)
+- Supports adding multiple todos in a single operation
+- Uses batch actions for efficiency when adding >10 todos
+- Automatically creates today's page if it doesn't exist
+- Adds todos as top-level blocks in sequential order
+
+### Import Nested Markdown
+
+Import nested markdown content under a specific block:
+
+```typescript
+use_mcp_tool roam-research roam_import_markdown {
+  "content": "- Item 1\n  - Subitem A\n  - Subitem B\n- Item 2",
+  "page_uid": "optional-page-uid",
+  "page_title": "optional-page-title",
+  "parent_uid": "optional-parent-block-uid",
+  "parent_string": "optional-exact-block-content",
+  "order": "first"
+}
+```
+
+Features:
+
+- Import content under specific blocks:
+  - Find parent block by UID or exact string match
+  - Locate blocks within specific pages by title or UID
+  - Defaults to today's page if no page specified
+- Control content placement:
+  - Add as first or last child of parent block
+  - Preserve hierarchical structure
+  - Efficient batch operations for nested content
+- Comprehensive return value:
+  ```json
+  {
+    "success": true,
+    "page_uid": "target-page-uid",
+    "parent_uid": "parent-block-uid",
+    "created_uids": ["uid1", "uid2", ...]
+  }
+  ```
+
+Parameters:
+
+- `content`: Nested markdown content to import
+- `page_uid`: UID of the page containing the parent block
+- `page_title`: Title of the page containing the parent block (ignored if page_uid provided)
+- `parent_uid`: UID of the parent block to add content under
+- `parent_string`: Exact string content of the parent block (must provide either page_uid or page_title)
+- `order`: Where to add the content ("first" or "last", defaults to "first")
+
+## Error Handling
+
+The server provides comprehensive error handling for common scenarios:
+
+- Configuration errors:
+  - Missing API token or graph name
+  - Invalid environment variables
+- API errors:
+  - Authentication failures
+  - Invalid requests
+  - Failed operations
+- Tool-specific errors:
+  - Page not found (with case-insensitive search)
+  - Block not found by string match
+  - Invalid markdown format
+  - Missing required parameters
+  - Invalid outline structure or content
+
+Each error response includes:
+
+- Standard MCP error code
+- Detailed error message
+- Suggestions for resolution when applicable
+
+## Development
+
+The server is built with TypeScript and includes:
+
+- Environment variable handling with .env support
+- Comprehensive input validation
+- Case-insensitive page title matching
+- Recursive block reference resolution
+- Markdown parsing and conversion
+- Daily page integration
+- Detailed debug logging
+- Efficient batch operations
+- Hierarchical outline creation
+
+To modify or extend the server:
+
+1. Clone the repository
+2. Install dependencies with `npm install`
+3. Make changes to the source files
+4. Build with `npm run build`
+5. Test locally by configuring environment variables
+
+## License
+
+MIT License

package/build/config/environment.js

@@ -0,0 +1,44 @@
+import * as dotenv from 'dotenv';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+// Get the project root from the script path
+const scriptPath = process.argv[1]; // Full path to the running script
+const projectRoot = dirname(dirname(scriptPath)); // Go up two levels from build/index.js
+// Try to load .env from project root
+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/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');
+}
+export { API_TOKEN, GRAPH_NAME };

package/build/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { RoamServer } from './server/roam-server.js';
+const server = new RoamServer();
+server.run().catch(() => { });

package/build/markdown-utils.js

@@ -0,0 +1,205 @@
+/**
+ * Check if text has a traditional markdown table
+ */
+function hasMarkdownTable(text) {
+    return /^\|([^|]+\|)+\s*$\n\|(\s*:?-+:?\s*\|)+\s*$\n(\|([^|]+\|)+\s*$\n*)+$/.test(text);
+}
+/**
+ * Converts a markdown table to Roam format
+ */
+function convertTableToRoamFormat(text) {
+    const lines = text.split('\n')
+        .map(line => line.trim())
+        .filter(line => line.length > 0);
+    const tableRegex = /^\|([^|]+\|)+\s*$\n\|(\s*:?-+:?\s*\|)+\s*$\n(\|([^|]+\|)+\s*$\n*)+/m;
+    if (!tableRegex.test(text)) {
+        return text;
+    }
+    const rows = lines
+        .filter((_, index) => index !== 1)
+        .map(line => line.trim()
+        .replace(/^\||\|$/g, '')
+        .split('|')
+        .map(cell => cell.trim()));
+    let roamTable = '{{table}}\n';
+    // First row becomes column headers
+    const headers = rows[0];
+    for (let i = 0; i < headers.length; i++) {
+        roamTable += `${'  '.repeat(i + 1)}- ${headers[i]}\n`;
+    }
+    // Remaining rows become nested under each column
+    for (let rowIndex = 1; rowIndex < rows.length; rowIndex++) {
+        const row = rows[rowIndex];
+        for (let colIndex = 0; colIndex < row.length; colIndex++) {
+            roamTable += `${'  '.repeat(colIndex + 1)}- ${row[colIndex]}\n`;
+        }
+    }
+    return roamTable.trim();
+}
+function convertAllTables(text) {
+    return text.replaceAll(/(^\|([^|]+\|)+\s*$\n\|(\s*:?-+:?\s*\|)+\s*$\n(\|([^|]+\|)+\s*$\n*)+)/gm, (match) => {
+        return '\n' + convertTableToRoamFormat(match) + '\n';
+    });
+}
+function convertToRoamMarkdown(text) {
+    // First handle double asterisks/underscores (bold)
+    text = text.replace(/\*\*(.+?)\*\*/g, '**$1**'); // Preserve double asterisks
+    // Then handle single asterisks/underscores (italic)
+    text = text.replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '__$1__'); // Single asterisk to double underscore
+    text = text.replace(/(?<!_)_(?!_)(.+?)(?<!_)_(?!_)/g, '__$1__'); // Single underscore to double underscore
+    // Handle highlights
+    text = text.replace(/==(.+?)==/g, '^^$1^^');
+    // Convert tables
+    text = convertAllTables(text);
+    return text;
+}
+function parseMarkdown(markdown) {
+    const lines = markdown.split('\n');
+    const rootNodes = [];
+    const stack = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmedLine = line.trimEnd();
+        // Skip truly empty lines (no spaces)
+        if (trimmedLine === '') {
+            continue;
+        }
+        // Calculate indentation level (2 spaces = 1 level)
+        const indentation = line.match(/^\s*/)?.[0].length ?? 0;
+        let level = Math.floor(indentation / 2);
+        // Extract content after bullet point or heading
+        let content = trimmedLine;
+        content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
+        if (trimmedLine.startsWith('#') || trimmedLine.includes('{{table}}') || (trimmedLine.startsWith('**') && trimmedLine.endsWith('**'))) {
+            // Remove bullet point if it precedes a table marker
+            // content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
+            level = 0;
+            // Reset stack but keep heading/table as parent
+            stack.length = 1; // Keep only the heading/table
+        }
+        else if (stack[0]?.content.startsWith('#') || stack[0]?.content.includes('{{table}}') || (stack[0]?.content.startsWith('**') && stack[0]?.content.endsWith('**'))) {
+            // If previous node was a heading or table marker or wrapped in double-asterisks, increase level by 1
+            level = Math.max(level, 1);
+            // Remove bullet point
+            // content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
+        }
+        else {
+            // Remove bullet point
+            content = trimmedLine.replace(/^\s*[-*+]\s+/, '');
+        }
+        // Create new node
+        const node = {
+            content,
+            level,
+            children: []
+        };
+        // Find the appropriate parent for this node based on level
+        if (level === 0) {
+            rootNodes.push(node);
+            stack[0] = node;
+        }
+        else {
+            // Pop stack until we find the parent level
+            while (stack.length > level) {
+                stack.pop();
+            }
+            // Add as child to parent
+            if (stack[level - 1]) {
+                stack[level - 1].children.push(node);
+            }
+            else {
+                // If no parent found, treat as root node
+                rootNodes.push(node);
+            }
+            stack[level] = node;
+        }
+    }
+    return rootNodes;
+}
+function parseTableRows(lines) {
+    const tableNodes = [];
+    let currentLevel = -1;
+    for (const line of lines) {
+        const trimmedLine = line.trimEnd();
+        if (!trimmedLine)
+            continue;
+        // Calculate indentation level
+        const indentation = line.match(/^\s*/)?.[0].length ?? 0;
+        const level = Math.floor(indentation / 2);
+        // Extract content after bullet point
+        const content = trimmedLine.replace(/^\s*[-*+]\s*/, '');
+        // Create node for this cell
+        const node = {
+            content,
+            level,
+            children: []
+        };
+        // Track the first level we see to maintain relative nesting
+        if (currentLevel === -1) {
+            currentLevel = level;
+        }
+        // Add node to appropriate parent based on level
+        if (level === currentLevel) {
+            tableNodes.push(node);
+        }
+        else {
+            // Find parent by walking back through nodes
+            let parent = tableNodes[tableNodes.length - 1];
+            while (parent && parent.level < level - 1) {
+                parent = parent.children[parent.children.length - 1];
+            }
+            if (parent) {
+                parent.children.push(node);
+            }
+        }
+    }
+    return tableNodes;
+}
+function generateBlockUid() {
+    // Generate a random string of 9 characters (Roam's format)
+    const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_';
+    let uid = '';
+    for (let i = 0; i < 9; i++) {
+        uid += chars.charAt(Math.floor(Math.random() * chars.length));
+    }
+    return uid;
+}
+function convertNodesToBlocks(nodes) {
+    return nodes.map(node => ({
+        uid: generateBlockUid(),
+        content: node.content,
+        children: convertNodesToBlocks(node.children)
+    }));
+}
+function convertToRoamActions(nodes, parentUid, order = 'last') {
+    // First convert nodes to blocks with UIDs
+    const blocks = convertNodesToBlocks(nodes);
+    const actions = [];
+    // Helper function to recursively create actions
+    function createBlockActions(blocks, parentUid, order) {
+        for (const block of blocks) {
+            // Create the current block
+            const action = {
+                action: 'create-block',
+                location: {
+                    'parent-uid': parentUid,
+                    order
+                },
+                block: {
+                    uid: block.uid,
+                    string: block.content
+                }
+            };
+            actions.push(action);
+            // Create child blocks if any
+            if (block.children.length > 0) {
+                createBlockActions(block.children, block.uid, 'last');
+            }
+        }
+    }
+    // Create all block actions
+    createBlockActions(blocks, parentUid, order);
+    return actions;
+}
+// Export public functions and types
+export { parseMarkdown, convertToRoamActions, hasMarkdownTable, convertAllTables, convertToRoamMarkdown };