Roam Research MCP

🚀 Roam Research Server API Documentation

The Roam Research server offers a powerful API for interacting with Roam Research diagrams. It implements the Model Context Protocol (MCP), enabling developers to programmatically access and manipulate Roam Research data.

🚀 Quick Start

This document details the various tools provided by the server, including their functions, parameters, input/output formats, and error handling mechanisms.

✨ Features

🔍 Block Match Search

Search for specific blocks using string content:

use_roam_search {
  "string": "The string to search for",
  "page_title_uid": "Page title or UID (optional)"
}

Function Description

• Search for blocks containing the given string within the specified page.
• Support partial and multi-line matching.
• Return detailed information about the matching blocks, including content, UID, and page title.

🔍 Page Search

Search for pages based on page titles:

use_roam_page_search {
  "string": "The page title to search for",
  "exact_match": boolean (optional, default: false)
}

Function Description

• Support fuzzy search and exact match modes.
• Return basic information about the matching pages, including UID and title.
• Specify whether to distinguish between uppercase and lowercase.

📄 Page Content Retrieval

Retrieve page content by UID:

use_roam_page_get {
  "page_title_uid": "Page title or UID"
}

Function Description

• Return the complete content structure of the specified page.
• Include all nested blocks and their relationships.
• Support parsing of complex hierarchical structures.

🆕 Block Creation

Create a new block on a page:

use_roam_create_block {
  "page_title_uid": "Target page title or UID",
  "string": "The string content to insert"
}

Function Description

• Support inserting new blocks at specified positions.
• Automatically generate unique UIDs.
• Return information about the newly created block.

🔄 Block Update

Update the content of an existing block:

use_roam_update_block {
  "block_uid": "The UID of the block to update",
  "string": "The new string content"
}

Function Description

• Support partial updates and complete replacements.
• Return information about the updated block.
• Include version control information.

🗑️ Block Deletion

Delete a specified block:

use_roam_delete_block {
  "block_uid": "The UID of the block to delete"
}

Function Description

• Implement a secure deletion mechanism to prevent accidental deletion.
• Return deletion confirmation information.
• Support batch deletion operations.

💻 Datalog Query Interface

Directly access Roam's query engine:

use_roam_query {
  "query": "Datalog query statement",
  "inputs": []
}

Function Description

• Support full Datalog query functionality.
• Include aggregate functions and string operations.
• Return structured data of the result set.

⚠️ Error Handling

The server provides a comprehensive error handling mechanism:

• Configuration errors:
  • Missing API key or graph name.
  • Environment variable configuration issues.
• API errors:
  • Authentication failure.
  • Invalid request.
  • Operation failure.
• Tool-specific errors:
  • Page not found (case-sensitive search).
  • Block not found by content.
  • Invalid tag format.
  • Missing required parameters.

Each error response includes:

• MCP standard error code.
• Detailed error message.
• Suggestions for resolution (when applicable).

📚 Documentation

Server Implementation Details

The server is built on the Node.js and Express frameworks, using TypeScript for type-safe development. The main dependent modules include:

• @roamjs/core - Roam core functionality library.
• express - Web application framework.
• typescript - Static type support.

Project Structure

src/
├── server.ts - Main server file
├── routes/ - Route modules
│   ├── blocks.ts - Block-related routes
│   └── pages.ts - Page-related routes
├── middleware/ - Middleware
│   ├── auth.ts - Authentication middleware
│   └── errorHandling.ts - Error handling middleware
└── types/ - Define type files

Development Environment Configuration

The following dependencies are required:

• Node.js 14+
• TypeScript 4.0+
• @roamjs/core 5.x
• Express 4.x

💻 Usage Examples

Creating a New Block

const response = await fetch('/api/create-block', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "page_title_uid": "My Page",
    "string": "New block content"
  })
});

Querying Datalog

const response = await fetch('/api/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "query": "SELECT * FROM blocks WHERE content LIKE '%test%'"
  })
});

Handling Page Not Found

try {
  const response = await fetch('/api/search-page', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "string": "NonExistentPage"
    })
  });
} catch (error) {
  console.error('Error:', error);
}

📄 Conclusion

This document details the functionality and usage of the Roam Research server API. Developers can use these interfaces to achieve in-depth interaction with Roam Research data. For further support or question resolution, please contact our technical team.