Roam Research MCP

🚀 Roam 研究服務器 API 文檔

Roam Research 服務器 API 為開發者提供了強大的功能，可與 Roam Research 圖紙進行交互。它實現了 Model Context Protocol (MCP)，讓開發者能以編程方式訪問和操作 Roam 研究數據。本文檔將詳細介紹服務器提供的各類工具、其功能、參數、輸入輸出格式以及錯誤處理機制。

🚀 快速開始

Roam Research 服務器 API 實現了 Model Context Protocol (MCP)，允許開發者通過編程方式訪問和操作 Room 研究數據。以下將詳細介紹其提供的各種工具。

✨ 主要特性

• 提供多種搜索和操作工具，如塊匹配搜索、頁面搜索、頁面內容獲取、塊創建、塊更新和塊刪除等。
• 支持 Datalog 查詢接口，可直接訪問 Roam 的查詢引擎。
• 具備全面的錯誤處理機制，每個錯誤響應包含標準錯誤代碼、詳細錯誤消息和解決建議。

📦 安裝指南

開發環境配置

需要以下依賴：

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

💻 使用示例

基礎用法

創建新塊

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"
  })
});

查詢 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%'"
  })
});

高級用法

處理未找到頁面

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);
}

📚 詳細文檔

工具概述

1. 塊匹配搜索

使用字符串內容查找特定塊：

use_roam_search {
  "string": "要搜索的字符串",
  "page_title_uid": "頁面標題或 UID（可選）"
}

功能說明

• 在指定頁面內查找包含給定字符串的塊。
• 支持部分匹配和多行匹配。
• 返回匹配塊的詳細信息，包括內容、UID 和頁面標題。

2. 頁面搜索

根據頁面標題進行搜索：

use_roam_page_search {
  "string": "要搜索的頁面標題",
  "exact_match": boolean（可選，默認：false）
}

功能說明

• 支持模糊搜索和精確匹配模式。
• 返回匹配頁面的基本信息，包括 UID 和標題。
• 可指定是否區分大小寫。

3. 頁面內容獲取

通過 UID 獲取頁面內容：

use_roam_page_get {
  "page_title_uid": "頁面標題或 UID"
}

功能說明

• 返回指定頁面的完整內容結構。
• 包括所有嵌套塊和它們之間的關係。
• 支持複雜的層次結構解析。

4. 塊創建

在頁面中創建新塊：

use_roam_create_block {
  "page_title_uid": "目標頁面標題或 UID",
  "string": "要插入的字符串內容"
}

功能說明

• 支持在指定位置插入新塊。
• 可自動生成唯一 UID。
• 返回新創建塊的信息。

5. 塊更新

更新現有塊的內容：

use_roam_update_block {
  "block_uid": "要更新的塊 UID",
  "string": "新的字符串內容"
}

功能說明

• 支持部分更新和完全替換。
• 返回更新後的塊信息。
• 包括版本控制信息。

6. 塊刪除

刪除指定塊：

use_roam_delete_block {
  "block_uid": "要刪除的塊 UID"
}

功能說明

• 安全刪除機制，防止誤刪。
• 返回刪除確認信息。
• 支持批量刪除操作。

Datalog 查詢接口

直接訪問 Roam 的查詢引擎：

use_roam_query {
  "query": "Datalog 查詢語句",
  "inputs": []
}

功能說明

• 支持完整的 Datalog 查詢功能。
• 包括聚合函數和字符串操作。
• 返回結果集的結構化數據。

錯誤處理

服務器提供全面的錯誤處理機制：

• 配置錯誤：
  • 缺少 API 密鑰或圖表名稱。
  • 環境變量配置問題。
• API 錯誤：
  • 認證失敗。
  • 請求無效。
  • 操作失敗。
• 工具特定錯誤：
  • 頁面未找到（區分大小寫搜索）。
  • 塊按內容未找到。
  • 標記格式無效。
  • 必要參數缺失。

每個錯誤響應都包含：

• MCP 標準錯誤代碼。
• 詳細錯誤消息。
• 解決建議（當適用時）。

🔧 技術細節

服務器實現細節

服務器基於 Node.js 和 Express 框架構建，使用 TypeScript 進行類型安全開發。主要依賴模塊包括：

• @roamjs/core - Roam 核心功能庫
• express - Web 應用框架
• typescript - 靜態類型支持

項目結構

src/
├── server.ts - 主服務器文件
├── routes/ - 路由模塊
│   ├── blocks.ts - 塊相關路由
│   └── pages.ts - 頁面相關路由
├── middleware/ - 中間件
│   ├── auth.ts - 認證中間件
│   └── errorHandling.ts - 錯誤處理中間件
└── types/ - 定義類型文件

📄 許可證

文檔中未提及相關信息。