Roam Research

漫游研究 MCP 服务器

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

安装

您可以全局安装该包：

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

测试

构建后运行MCP Inspector ...

特征

该服务器提供了与 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 ：在漫游图上执行自定义数据日志查询，以进行高级数据检索和分析

设置

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

用法

按标题获取页面

使用已解析的块引用获取并读取页面内容：

将页面内容以 markdown 形式返回：

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

创建页面

创建具有可选内容的新页面：

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

创建块

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

您可以指定：

• page_uid ：直接引用目标页面
• title ：目标页面的名称（如果不存在则创建）
• 两者都不是：今天的每日页面将添加屏蔽

返回：

创建大纲

创建具有适当嵌套和结构的分层轮廓：

特征：

• 创建最多 10 层嵌套的复杂轮廓
• 验证大纲结构和内容
• 维持适当的亲子关系
• 大纲的可选标题块
• 如果没有指定页面，则默认为今天的每日页面
• 高效的批量创建区块操作

参数：

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

返回：

添加待办事项

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

特征：

• 使用漫游复选框语法添加待办事项（ {{TODO}} todo text ）
• 支持在一次操作中添加多个待办事项
• 添加 10 个以上待办事项时使用批处理操作来提高效率
• 如果今天的页面不存在则自动创建
• 按顺序将待办事项添加为顶级块

导入嵌套 Markdown

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

特征：

• 导入特定块下的内容：
  • 通过 UID 或精确字符串匹配查找父块
  • 通过标题或 UID 定位特定页面内的区块
  • 如果没有指定页面，则默认为今天的页面
• 控制内容放置：
  • 添加为父块的第一个或最后一个子块
  • 保留层次结构
  • 嵌套内容的高效批量操作
• 综合返回值：
  { "success": true, "page_uid": "target-page-uid", "parent_uid": "parent-block-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”）

搜索块引用

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

特征：

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

参数：

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

返回：

按文本搜索

在所有页面或特定页面内搜索包含特定文本的块：

特征：

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

参数：

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

返回：

更新块内容

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

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

特征：

• 两种更新模式：
  • 直接内容替换
  • 使用正则表达式进行基于模式的转换
• 更新之前验证块的存在
• 返回更新后的内容作为响应
• 支持全局或单场比赛替换
• 保留块关系和元数据

参数：

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

返回：

搜索标签

搜索包含特定标签的块，并可选择按附近标签进行过滤：

特征：

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

参数：

• primary_tag ：要搜索的主标签（必需）
• page_title_uid ：要搜索的页面的标题或 UID（可选）
• near_tag ：用于过滤结果的另一个标签（可选）
• case_sensitive ：是否执行区分大小写的搜索（可选，默认值：true，以匹配 Roam 的本机行为）

返回：

记住信息

使用自动标记和分类来存储记忆或重要信息：

特征：

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

参数：

• memory ：需要记住的信息（必需）
• categories ：用于标记内存的可选类别数组

返回：

按日期搜索

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

特征：

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

参数：

• start_date ：ISO 格式的开始日期 (YYYY-MM-DD)（必需）
• end_date ：ISO 格式的结束日期 (YYYY-MM-DD)（可选）
• type ：是否按“创建”、“修改”或“两者”进行搜索（必需）
• scope ：是否搜索“块”、“页面”或“两者”（必需）
• include_content ：是否包含匹配的块/页面的内容（可选，默认值：true）

返回：

查找今天修改的页面

查找今天午夜以来修改过的所有页面：

特征：

• 跟踪自午夜以来对页面所做的所有修改
• 检测块层次结构中任何级别的变化
• 返回已修改页面标题的唯一列表
• 包括已修改页面的数量
• 无需参数

返回：

执行 Datomic 查询

在漫游图上执行自定义数据日志查询以进行高级数据检索和分析：

特征：

• 直接访问 Roam 的查询引擎
• 支持所有Datalog查询功能：
  • 复杂模式匹配
  • 聚合函数（计数、总和、最大值、最小值、平均值、不同）
  • 字符串操作（包括？、以...开头？、以...结尾？）
  • 逻辑运算（<、>、<=、>=、=、not=）
  • 递归查询规则
• 区分大小写和不区分大小写的搜索功能
• 跨整个图表的高效查询

参数：

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

返回：

示例查询：

1. 统计所有页面：

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

3. 查找在某个日期之后修改的块：

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

搜索块层次结构

浏览并搜索块父子关系：

特征：

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

参数：

• parent_uid ：要查找子块的 UID（向下搜索时必需）
• child_uid ：要查找父块的 UID（向上搜索时必需）
• page_title_uid ：要搜索的页面的标题或 UID（可选）
• max_depth ：搜索深度（可选，默认值：1，最大值：10）

返回：

错误处理

服务器针对常见场景提供了全面的错误处理：

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

每个错误响应包括：

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

发展

建筑

构建服务器：

这将：

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

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

使用 MCP Inspector 进行测试

MCP 检查器是一款用于测试和调试 MCP 服务器的工具。要测试服务器，请执行以下操作：

这将：

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

执照

MIT 许可证