roam-research-mcp 0.12.3

package/build/markdown-utils.js

@@ -0,0 +1,204 @@
+/**
+ * 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;
+        if (trimmedLine.startsWith('#') || trimmedLine.includes('{{table}}')) {
+            // 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}}')) {
+            // If previous node was a heading or table marker, 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 };

package/build/test-addMarkdownText.js

@@ -0,0 +1,87 @@
+import { initializeGraph, createPage, batchActions, q } from '@roam-research/roam-api-sdk';
+import { parseMarkdown, convertToRoamActions } from './markdown-utils.js';
+import * as dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+// Load environment variables
+const scriptPath = fileURLToPath(import.meta.url);
+const projectRoot = dirname(dirname(scriptPath));
+const envPath = join(projectRoot, '.env');
+dotenv.config({ path: envPath });
+const API_TOKEN = process.env.ROAM_API_TOKEN;
+const GRAPH_NAME = process.env.ROAM_GRAPH_NAME;
+if (!API_TOKEN || !GRAPH_NAME) {
+    throw new Error('Missing required environment variables: ROAM_API_TOKEN and/or ROAM_GRAPH_NAME');
+}
+async function testAddMarkdownText() {
+    try {
+        // Initialize graph
+        console.log('Initializing graph...');
+        const graph = initializeGraph({
+            token: API_TOKEN,
+            graph: GRAPH_NAME,
+        });
+        // Test markdown content
+        const testPageTitle = `Test Markdown Import ${new Date().toISOString()}`;
+        console.log(`Using test page title: ${testPageTitle}`);
+        const markdownContent = `
+| Month    | Savings |
+| -------- | ------- |
+| January  | $250    |
+| February | $80     |
+| March    | $420    |
+
+# Main Topic
+- First point
+  - Nested point A
+    - Deep nested point
+  - Nested point B
+- Second point
+  1. Numbered subpoint
+  2. Another numbered point
+    - Mixed list type
+- Third point
+  - With some **bold** text
+  - And *italic* text
+    - And a [[Page Reference]]
+    - And a #[[Page Tag]]
+`;
+        // First create the page
+        console.log('\nCreating page...');
+        const success = await createPage(graph, {
+            action: 'create-page',
+            page: {
+                title: testPageTitle
+            }
+        });
+        if (!success) {
+            throw new Error('Failed to create test page');
+        }
+        // Get the page UID
+        const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+        const findResults = await q(graph, findQuery, [testPageTitle]);
+        if (!findResults || findResults.length === 0) {
+            throw new Error('Could not find created page');
+        }
+        const pageUid = findResults[0][0];
+        console.log('Page UID:', pageUid);
+        // Import markdown
+        console.log('\nImporting markdown...');
+        const nodes = parseMarkdown(markdownContent);
+        console.log('Parsed nodes:', JSON.stringify(nodes, null, 2));
+        // Convert and add markdown content
+        const actions = convertToRoamActions(nodes, pageUid, 'last');
+        const result = await batchActions(graph, {
+            action: 'batch-actions',
+            actions
+        });
+        console.log('\nImport result:', JSON.stringify(result, null, 2));
+        console.log('\nTest completed successfully!');
+        console.log(`Check your Roam graph for the page titled: ${testPageTitle}`);
+    }
+    catch (error) {
+        console.error('Error:', error);
+    }
+}
+// Run the test
+testAddMarkdownText();

package/build/test-queries.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { initializeGraph, q } from '@roam-research/roam-api-sdk';
+import * as dotenv from 'dotenv';
+// Load environment variables
+dotenv.config();
+const API_TOKEN = process.env.ROAM_API_TOKEN;
+const GRAPH_NAME = process.env.ROAM_GRAPH_NAME;
+if (!API_TOKEN || !GRAPH_NAME) {
+    throw new Error('Missing required environment variables: ROAM_API_TOKEN and ROAM_GRAPH_NAME');
+}
+async function main() {
+    const graph = initializeGraph({
+        token: API_TOKEN,
+        graph: GRAPH_NAME,
+    });
+    try {
+        // First verify we can find the page
+        console.log('Finding page...');
+        const searchQuery = `[:find ?uid .
+                         :where [?e :node/title "December 18th, 2024"]
+                                [?e :block/uid ?uid]]`;
+        const uid = await q(graph, searchQuery, []);
+        console.log('Page UID:', uid);
+        if (!uid) {
+            throw new Error('Page not found');
+        }
+        // Get all blocks under this page with their order
+        console.log('\nGetting blocks...');
+        const blocksQuery = `[:find ?block-uid ?block-str ?order ?parent-uid
+                         :where [?p :block/uid "${uid}"]
+                                [?b :block/page ?p]
+                                [?b :block/uid ?block-uid]
+                                [?b :block/string ?block-str]
+                                [?b :block/order ?order]
+                                [?b :block/parents ?parent]
+                                [?parent :block/uid ?parent-uid]]`;
+        const blocks = await q(graph, blocksQuery, []);
+        console.log('Found', blocks.length, 'blocks');
+        // Create a map of all blocks
+        const blockMap = new Map();
+        blocks.forEach(([uid, string, order]) => {
+            if (!blockMap.has(uid)) {
+                blockMap.set(uid, {
+                    uid,
+                    string,
+                    order: order,
+                    children: []
+                });
+            }
+        });
+        console.log('Created block map with', blockMap.size, 'entries');
+        // Build parent-child relationships
+        let relationshipsBuilt = 0;
+        blocks.forEach(([childUid, _, __, parentUid]) => {
+            const child = blockMap.get(childUid);
+            const parent = blockMap.get(parentUid);
+            if (child && parent && !parent.children.includes(child)) {
+                parent.children.push(child);
+                relationshipsBuilt++;
+            }
+        });
+        console.log('Built', relationshipsBuilt, 'parent-child relationships');
+        // Get top-level blocks (those directly under the page)
+        console.log('\nGetting top-level blocks...');
+        const topQuery = `[:find ?block-uid ?block-str ?order
+                      :where [?p :block/uid "${uid}"]
+                             [?b :block/page ?p]
+                             [?b :block/uid ?block-uid]
+                             [?b :block/string ?block-str]
+                             [?b :block/order ?order]
+                             (not-join [?b]
+                               [?b :block/parents ?parent]
+                               [?parent :block/page ?p])]`;
+        const topBlocks = await q(graph, topQuery, []);
+        console.log('Found', topBlocks.length, 'top-level blocks');
+        // Create root blocks
+        const rootBlocks = topBlocks
+            .map(([uid, string, order]) => ({
+            uid,
+            string,
+            order: order,
+            children: blockMap.get(uid)?.children || []
+        }))
+            .sort((a, b) => a.order - b.order);
+        // Log block hierarchy
+        console.log('\nBlock hierarchy:');
+        const logHierarchy = (blocks, level = 0) => {
+            blocks.forEach(block => {
+                console.log('  '.repeat(level) + '- ' + block.string.substring(0, 50) + '...');
+                if (block.children.length > 0) {
+                    logHierarchy(block.children.sort((a, b) => a.order - b.order), level + 1);
+                }
+            });
+        };
+        logHierarchy(rootBlocks);
+        // Convert to markdown
+        console.log('\nConverting to markdown...');
+        const toMarkdown = (blocks, level = 0) => {
+            return blocks.map(block => {
+                const indent = '  '.repeat(level);
+                let md = `${indent}- ${block.string}\n`;
+                if (block.children.length > 0) {
+                    md += toMarkdown(block.children.sort((a, b) => a.order - b.order), level + 1);
+                }
+                return md;
+            }).join('');
+        };
+        const markdown = toMarkdown(rootBlocks);
+        console.log('\nMarkdown output:');
+        console.log(markdown);
+    }
+    catch (error) {
+        console.error('Error:', error);
+    }
+}
+main().catch(console.error);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "roam-research-mcp",
+  "version": "0.12.3",
+  "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/2b3pro/roam-research-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "roam-research",
+    "api",
+    "claude",
+    "model-context-protocol"
+  ],
+  "author": "Ian Shen / 2B3 PRODUCTIONS LLC",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/2b3pro/roam-research-mcp/issues"
+  },
+  "homepage": "https://github.com/2b3pro/roam-research-mcp#readme",
+  "type": "module",
+  "bin": {
+    "roam-research": "./build/index.js"
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "0.6.0",
+    "@roam-research/roam-api-sdk": "^0.10.0",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}