Roam Research MCP 服务器

一个提供全面访问 Roam Research API 功能的模型上下文协议 (MCP) 服务器。此服务器使像 Claude 这样的 AI 助手能够通过标准化接口与您的 Roam Research 图形进行交互。（这是一个正在进行中的个人项目，并未得到 Roam Research 的官方认可）

安装

您可以全局安装该包：

npm install -g roam-research-mcp

或者克隆仓库并从源代码构建：

git clone https://github.com/2b3pro/roam-research-mcp.git
cd roam-research-mcp
npm install
npm run build

特性

该服务器提供了与 Roam Research 交互的强大工具：

• 支持 .env 文件的环境变量处理
• 全面的输入验证
• 不区分大小写的页面标题匹配
• 递归块引用解析
• Markdown 解析和转换
• 每日页面集成
• 详细的调试日志
• 高效的批量操作
• 分层大纲创建

1. roam_fetch_page_by_title: 通过标题获取并读取页面内容，递归解析最多4级的块引用
2. roam_create_page: 创建带有可选内容的新页面
3. roam_create_block: 在页面中创建新块（默认为今天的每日页面）
4. roam_import_markdown: 将嵌套的markdown内容导入到特定块下
5. roam_add_todo: 向今天的每日页面添加多个带复选框语法的待办事项
6. roam_create_outline: 创建具有适当嵌套和结构的层次大纲
7. roam_search_block_refs: 在页面内或整个图谱中搜索块引用
8. roam_search_hierarchy: 导航并搜索块之间的父子关系
9. roam_find_pages_modified_today: 查找自今日午夜以来被修改的所有页面
10. roam_search_by_text: 在所有页面或特定页面中搜索包含特定文本的块
11. roam_update_block: 使用直接文本或基于模式的转换来更新块内容
12. roam_search_by_date: 根据创建或修改日期搜索块和页面
13. roam_search_for_tag: 搜索包含特定标签的块，并可选择通过附近的标签进行过滤
14. roam_remember: 存储并分类记忆或信息，自动打标签
15. roam_recall: 回忆带有标签 MEMORIES_TAG（见下文）的块或同名页面标题上的块
16. roam_datomic_query: 在Roam图谱上执行自定义Datalog查询，以进行高级数据检索和分析

设置

1. 创建 Roam Research API 令牌：

   • 前往您的图设置
   • 导航到“API 令牌”部分（设置 > “图”标签 > “API 令牌”部分，然后点击“+ 新建 API 令牌”按钮）
   • 创建一个新的令牌

2. 配置环境变量：
   您有两种配置所需环境变量的选项：

   选项 1：使用 .env 文件（推荐用于开发）
   在 roam-research 目录中创建一个 .env 文件：

   ROAM_API_TOKEN=your-api-token
   ROAM_GRAPH_NAME=your-graph-name
   MEMORIES_TAG='#[[LLM/Memories]]'
   

   选项 2：使用 MCP 设置（替代方法）
   将配置添加到您的 MCP 设置文件中：

   • 对于 Cline (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json)：
   • 对于 Claude 桌面应用程序 (~/Library/Application Support/Claude/claude_desktop_config.json)：

   {
     "mcpServers": {
       "roam-research": {
         "command": "node",
         "args": ["/path/to/roam-research-mcp/build/index.js"],
         "env": {
           "ROAM_API_TOKEN": "your-api-token",
           "ROAM_GRAPH_NAME": "your-graph-name",
           "MEMORIES_TAG": "#[[LLM/Memories]]"
         }
       }
     }
   }
   

   注意：服务器将首先尝试从 .env 文件加载，然后回退到 MCP 设置中的环境变量。

3. 构建服务器（确保您在 MCP 的根目录下）：

   cd roam-research-mcp
   npm install
   npm run build
   

使用方法

通过标题获取页面

获取并读取具有解析块引用的页面内容：

use_mcp_tool roam-research roam_fetch_page_by_title {
  "title": "Example Page"
}

返回页面内容为 markdown 格式，包含：

• 完整的层次结构
• 递归解析的块引用（最多 4 层深）
• 适当的嵌套缩进
• 完整的 markdown 格式化

创建页面

创建一个带有可选内容的新页面：

use_mcp_tool roam-research roam_create_page {
  "title": "New Page",
  "content": "Initial content for the page"
}

成功时返回创建页面的 UID。

创建块

向页面添加一个新块（如果未提供 page_uid 或 title，则默认为今天的每日页面）：

use_mcp_tool roam-research roam_create_block {
  "content": "Block content",
  "page_uid": "optional-target-page-uid",
  "title": "optional-target-page-title"
}

您可以指定以下之一：

• page_uid：直接引用目标页面
• title：目标页面的名称（如果不存在则会创建）
• 两者都不指定：块将被添加到今天的每日页面

返回：

{
  "success": true,
  "block_uid": "created-block-uid",
  "parent_uid": "parent-page-uid"
}

创建大纲

创建具有适当嵌套和结构的分层大纲：

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

功能：

• 创建多达 10 层嵌套的复杂大纲
• 验证大纲结构和内容
• 维护正确的父子关系
• 可选的大纲头部块
• 如果未指定页面，默认为今天的每日页面
• 高效的批量操作以创建块

参数：

• outline: 大纲项目数组，每个项目包含：
  • text: 大纲项目的文本内容（必填）
  • level: 嵌套级别（1-10，必填）
• page_title_uid: 目标页面的标题或UID（可选，默认为今天的页面）
• block_text_uid: 大纲的标题文本（可选）

返回值：

{
  "success": true,
  "page_uid": "target-page-uid",
  "parent_uid": "header-block-uid",
  "created_uids": ["uid1", "uid2", ...]
}

添加待办事项

向今天的每日页面添加一个或多个待办事项：

use_mcp_tool roam-research roam_add_todo {
  "todos": [
    "First todo item",
    "Second todo item",
    "Third todo item"
  ]
}

功能特点：

• 使用 Roam 的复选框语法 ({{TODO}} 待办事项文本) 添加待办事项
• 支持在单次操作中添加多个待办事项
• 当添加超过10个待办事项时使用批量操作以提高效率
• 如果今天页面不存在则自动创建
• 按顺序将待办事项作为顶级块添加

导入嵌套的 Markdown 内容

在特定块下导入嵌套的 Markdown 内容：

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

功能特点：

• 在特定块下导入内容：
  • 通过 UID 或精确字符串匹配查找父块
  • 通过标题或 UID 定位特定页面内的块
  • 如果未指定页面，则默认为今天的页面
• 控制内容放置位置：
  • 将内容添加为父块的第一个或最后一个子项
  • 保持层次结构
  • 对于嵌套内容进行高效的批量操作
• 全面的返回值：

  {
    "success": true,
    "page_uid": "目标页面UID",
    "parent_uid": "父块UID",
    "created_uids": ["uid1", "uid2", ...]
  }
  

参数：

• content: 要导入的嵌套 Markdown 内容
• page_uid: 包含父块的页面的UID
• page_title: 包含父块的页面的标题（如果提供了 page_uid 则忽略此参数）
• parent_uid: 父块的UID，在其下添加内容
• parent_string: 父块的确切字符串内容（必须提供 page_uid 或 page_title）
• order: 在哪里添加内容（"first" 或 "last"，默认为 "first"）

搜索块引用

在页面内或整个图中搜索块引用：

use_mcp_tool roam-research roam_search_block_refs {
  "block_uid": "optional-block-uid",
  "page_title_uid": "optional-page-title-or-uid"
}

功能特点：

• 查找特定块的所有引用
• 在页面内查找任何块引用
• 在整个图中搜索
• 支持直接和间接引用
• 包括块内容及其位置上下文

参数：

• block_uid: 要查找引用的目标块的UID（可选）
• page_title_uid: 要搜索的页面的标题或UID（可选）

返回值：

{
  "success": true,
  "matches": [
    {
      "block_uid": "referenced-block-uid",
      "content": "Block content with ((reference))",
      "page_title": "Page containing reference"
    }
  ],
  "message": "Found N block(s) referencing..."
}

按文本搜索

在整个页面或特定页面中搜索包含特定文本的块：

use_mcp_tool roam-research roam_search_by_text {
  "text": "search text",
  "page_title_uid": "optional-page-title-or-uid",
  "case_sensitive": true
}

功能特点：

• 在图中的所有块中搜索任意文本
• 可选的页面范围搜索
• 区分大小写或不区分大小写的搜索
• 返回带有页面上下文的块内容
• 使用 Datalog 查询进行高效的文本匹配

参数：

• text: 要搜索的文本（必填）
• page_title_uid: 要搜索的页面的标题或UID（可选）
• case_sensitive: 是否执行区分大小写的搜索（可选，默认为 true 以匹配 Roam 的原生行为）

返回值：

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing search text",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) containing \"search text\""
}

更新块内容

更新块的内容，可以使用直接文本替换或基于模式的转换：

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "content": "New block content"
}

或者使用基于模式的转换：

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "transform_pattern": {
    "find": "\\bPython\\b",
    "replace": "[[Python]]",
    "global": true
  }
}

功能特点：

• 两种更新模式：
  • 直接内容替换
  • 使用正则表达式的基于模式的转换
• 在更新前验证块的存在
• 返回响应中的更新内容
• 支持全局替换或单个匹配替换
• 保持块的关系和元数据

参数：

• block_uid: 要更新的块的UID（必填）
• content: 块的新内容（如果使用直接替换）
• transform_pattern: 用于转换现有内容的模式：
  • find: 要查找的文本或正则表达式模式
  • replace: 用以替换的文本
  • global: 是否替换所有出现（默认：true）

返回值：

{
  "success": true,
  "content": "Updated block content"
}

搜索标签

根据特定标签搜索包含这些标签的块，并可选择通过附近的标签进行过滤：

use_mcp_tool roam-research roam_search_for_tag {
  "primary_tag": "Project/Tasks",
  "page_title_uid": "optional-page-title-or-uid",
  "near_tag": "optional-secondary-tag",
  "case_sensitive": true
}

功能特点：

• 搜索包含特定标签的块
• 可选地通过另一个标签的存在来过滤结果
• 页面范围或整个图谱范围的搜索
• 区分大小写或不区分大小写的搜索
• 返回带有页面上下文的块内容
• 使用Datalog查询高效地匹配标签

参数：

• primary_tag: 主要搜索的标签（必填）
• page_title_uid: 要在其中搜索的页面标题或UID（可选）
• near_tag: 用来过滤结果的另一个标签（可选）
• case_sensitive: 是否执行区分大小写的搜索（可选，默认：true，以匹配Roam的原生行为）

返回值：

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing #[[primary_tag]]",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) referencing \"primary_tag\""
}

记忆信息

存储记忆或重要信息，自动添加标签和分类：

use_mcp_tool roam-research roam_remember {
  "memory": "Important information to remember",
  "categories": ["Work", "Project/Alpha"]
}

功能特点：

• 存储带有#[[LLM/Memories]]标签的信息
• 添加可选的类别标签以便组织
• 自动添加到今天的每日页面
• 支持每条记忆有多个类别
• 使用roam_search_for_tag轻松检索
• 维护记忆的时间顺序

参数：

• memory: 要记住的信息（必填）
• categories: 用于标记记忆的可选类别数组

返回值：

{
  "success": true,
  "block_uid": "created-block-uid",
  "content": "Memory content with tags"
}

按日期搜索

根据创建日期或修改日期搜索块和页面：

use_mcp_tool roam-research roam_search_by_date {
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "type": "modified",
  "scope": "blocks",
  "include_content": true
}

功能特点：

• 根据创建日期、修改日期或两者进行搜索
• 过滤块、页面或两者
• 可选的日期范围，包括开始日期和结束日期
• 结果中包含或排除块/页面内容
• 按时间戳排序结果
• 使用Datalog查询高效地按日期过滤

参数：

• start_date: 开始日期，ISO格式（YYYY-MM-DD）（必填）
• end_date: 结束日期，ISO格式（YYYY-MM-DD）（可选）
• type: 按'created'、'modified'或'both'搜索（必填）
• scope: 搜索'blocks'、'pages'或'both'（必填）
• include_content: 是否包含匹配块/页面的内容（可选，默认：true）

返回值：

{
  "success": true,
  "matches": [
    {
      "uid": "block-or-page-uid",
      "type": "block",
      "time": 1704067200000,
      "content": "Block or page content",
      "page_title": "Page title (for blocks)"
    }
  ],
  "message": "Found N matches for the given date range and criteria"
}

查找今天修改过的页面

找到自今日午夜以来被修改的所有页面：

use_mcp_tool roam-research roam_find_pages_modified_today {}

特性：

• 跟踪自午夜以来对页面所做的所有修改
• 检测块层次结构中任何级别的更改
• 返回修改过的页面标题的唯一列表
• 包含修改页数的计数
• 不需要参数

返回值：

{
  "success": true,
  "pages": ["Page 1", "Page 2"],
  "message": "Found 2 page(s) modified today"
}

执行 Datomic 查询

在您的 Roam 图上执行自定义 Datalog 查询，以进行高级数据检索和分析：

use_mcp_tool roam-research roam_datomic_query {
  "query": "[:find (count ?p)\n :where [?p :node/title]]",
  "inputs": []
}

特性：

• 直接访问 Roam 的查询引擎
• 支持所有 Datalog 查询功能：
  • 复杂模式匹配
  • 聚合函数（计数、求和、最大值、最小值、平均值、去重）
  • 字符串操作（includes?, starts-with?, ends-with?）
  • 逻辑运算（<, >, <=, >=, =, not=）
  • 用于递归查询的规则
• 区分大小写和不区分大小写的搜索能力
• 高效地在整个图中查询

参数：

• query: 要执行的 Datalog 查询（必需）
• inputs: 可选的查询输入参数数组

返回值：

{
  "success": true,
  "matches": [
    {
      "content": "[result data]",
      "block_uid": "",
      "page_title": ""
    }
  ],
  "message": "Query executed successfully. Found N results."
}

示例查询：

1. 计算所有页面数量：

[:find (count ?p)
 :where [?p :node/title]]

1. 不区分大小写的文本搜索：

[:find ?string ?title
 :where
 [?b :block/string ?string]
 [(clojure.string/lower-case ?string) ?lower]
 [(clojure.string/includes? ?lower "search term")]
 [?b :block/page ?p]
 [?p :node/title ?title]]

1. 查找指定日期之后被修改的块：

[:find ?block_ref ?string
 :in $ ?start_of_day
 :where
 [?b :edit/time ?time]
 [(> ?time ?start_of_day)]
 [?b :block/uid ?block_ref]
 [?b :block/string ?string]]

更多查询示例和语法文档，请参见 Roam_Research_Datalog_Cheatsheet.md。

搜索块层次结构

浏览并搜索块之间的父子关系：

use_mcp_tool roam-research roam_search_hierarchy {
  "parent_uid": "optional-parent-block-uid",
  "child_uid": "optional-child-block-uid",
  "page_title_uid": "optional-page-title-or-uid",
  "max_depth": 3
}

特性：

• 向上或向下搜索块层次结构
• 查找特定块的所有子块
• 查找特定块的所有父块
• 配置搜索深度（1-10层）
• 可选的页面范围过滤
• 每个结果包括深度信息

参数：

• parent_uid: 要查找其子块的块的 UID（如果向下搜索，则为必需）
• child_uid: 要查找其父块的块的 UID（如果向上搜索，则为必需）
• page_title_uid: 要搜索的页面的标题或 UID（可选）
• max_depth: 搜索多少层级深（可选，默认：1，最大：10）

返回值：

{
  "success": true,
  "matches": [
    {
      "block_uid": "related-block-uid",
      "content": "Block content",
      "depth": 2,
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) as children/parents..."
}

错误处理

服务器提供了全面的错误处理机制来应对常见情况：

• 配置错误：
  • 缺少 API token 或图形名称
  • 无效的环境变量
• API 错误：
  • 认证失败
  • 无效请求
  • 操作失败
• 工具特定错误：
  • 页面未找到（使用不区分大小写的搜索）
  • 通过字符串匹配未找到块
  • 无效的 Markdown 格式
  • 缺少必需参数
  • 无效的大纲结构或内容

每个错误响应都包含：

• 标准 MCP 错误代码
• 详细的错误消息
• 当适用时提供解决建议

开发

构建

要构建服务器：

npm install
npm run build

这将：

1. 安装所有必需的依赖项
2. 将 TypeScript 编译为 JavaScript
3. 使输出文件可执行

您还可以在开发过程中使用 npm run watch 来自动重新编译已更改的文件。

使用 MCP Inspector 进行测试

MCP Inspector 是一个帮助测试和调试 MCP 服务器的工具。要测试服务器：

# Inspect with npx:
npx @modelcontextprotocol/inspector node build/index.js

这将：

1. 以检查模式启动服务器
2. 提供一个交互界面，用于：
   • 列出可用的工具和资源
   • 使用自定义参数执行工具
   • 查看工具响应和错误处理

许可证

MIT 许可证