星战科技xingzhan.cloud
返回市场
漫游研究MCP

漫游研究MCP

作者：2b3pro63 星标更新：2025-09-14
安装使用来源：spider==github.com

项目介绍

Roam Research MCP 服务器

npm 版本 项目状态：WIP – 初始开发正在进行中，但尚未发布稳定、可用的版本。 许可证：MIT GitHub

这是一个提供全面访问 Roam Research API 功能的 Model Context Protocol (MCP) 服务器。此服务器使像 Claude 这样的AI助手能够通过标准化接口与您的 Roam Research 图表进行交互。它支持标准输入/输出（stdio）、HTTP 流和服务器发送事件（SSE）通信。（正在进行中的个人项目，未经 Roam Research 官方认可）

<a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://gips1.baidu.com/it/u=947314323,3114419934&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Roam Research MCP 服务器" /></a> <a href="https://mseep.ai/app/2b3pro-roam-research-mcp"><img width="380" height="200" src="https://gips2.baidu.com/it/u=2027249751,1298384053&fm=3081&app=3081&f=PNG?w=479&h=180" alt="MseeP.ai 安全评估徽章" /></a>

安装和使用

此 MCP 服务器支持三种主要的通信方法：

  1. **Stdio（标准输入/输出）：**适用于本地进程间通信、命令行工具以及在同一台机器上运行的应用程序的直接集成。这是在直接运行服务器时默认的通信方式。
  2. **HTTP 流：**提供基于网络的通信，适合于基于Web的客户端、远程应用程序或需要实时更新的HTTP场景。HTTP流端点默认运行在端口 8088 上。
  3. **SSE（服务器发送事件）：**用于需要SSE的传统客户端。SSE端点默认运行在端口 8087 上。（注意：⚠️ 已弃用：自 MCP 规范版本 2025-03-26 起，SSE 传输已被弃用。推荐使用 HTTP 流传输。）

使用 Stdio 运行

您可以全局安装该包并运行它：

npm install -g roam-research-mcp
roam-research-mcp

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

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

使用 HTTP 流运行

要以 HTTP 流或 SSE 支持运行服务器，可以：

  1. 使用默认端口： 构建后运行 npm start（如上所示）。服务器将自动监听端口 8088 的 HTTP 流和端口 8087 的 SSE。

  2. 指定自定义端口： 在启动服务器之前设置 HTTP_STREAM_PORT 和/或 SSE_PORT 环境变量。

    HTTP_STREAM_PORT=9000 SSE_PORT=9001 npm start

    或者，如果您使用 .env 文件，则可以在其中添加 HTTP_STREAM_PORT=9000 和/或 SSE_PORT=9001。

Docker

该项目可以轻松地使用 Docker 进行容器化。在仓库根目录提供了 Dockerfile。

构建 Docker 镜像

要构建 Docker 镜像，请导航到项目根目录并运行：

docker build -t roam-research-mcp .

运行 Docker 容器

要运行 Docker 容器并映射必要的端口，您还必须提供所需的环境变量。使用 -e 标志传递 ROAM_API_TOKEN、ROAM_GRAPH_NAME，以及可选的 MEMORIES_TAG、HTTP_STREAM_PORT 和 SSE_PORT：

docker run -p 3000:3000 -p 8088:8088 -p 8087:8087 \
  -e ROAM_API_TOKEN="your-api-token" \
  -e ROAM_GRAPH_NAME="your-graph-name" \
  -e MEMORIES_TAG="#[[LLM/Memories]]" \
  -e CUSTOM_INSTRUCTIONS_PATH="/path/to/your/custom_instructions_file.md" \
  -e HTTP_STREAM_PORT="8088" \
  -e SSE_PORT="8087" \
  roam-research-mcp

或者，如果您在项目根目录有一个 .env 文件（在构建过程中复制到 Docker 镜像中），您可以使用 --env-file 标志：

docker run -p 3000:3000 -p  8088:8088 --env-file .env roam-research-mcp

测试

构建后运行 MCP Inspector：

npm run inspector

功能

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

  • 支持环境变量处理和 .env 文件
  • 全面的输入验证
  • 不区分大小写的页面标题匹配
  • 递归块引用解析
  • Markdown 解析和转换
  • 日常页面集成
  • 详细的调试日志
  • 高效的批处理操作
  • 层次结构大纲创建
  • 增强的文档，特别是关于 Roam 表格的 Roam_Markdown_Cheatsheet.md，以便更清晰地指导嵌套。
    • 自定义指令附加到 Cheat Sheet 关于您特定的 Roam 笔记。
  1. roam_fetch_page_by_title：通过标题获取页面内容。返回指定格式的内容。
  2. roam_fetch_block_with_children：通过其 UID 获取一个块及其层次结构下的子块，直到指定深度。自动处理 ((UID)) 格式。
  3. roam_create_page：创建新页面，可选内容和标题。现在会在日常页面上创建一个链接到新创建页面的块。
  4. roam_import_markdown：在特定块下导入嵌套的 Markdown 内容。（内部使用 roam_process_batch_actions。）
  5. roam_add_todo：向今天的日常页面添加待办事项列表。（内部使用 roam_process_batch_actions。）
  6. roam_create_outline：向现有页面或块添加结构化的大纲，支持 children_view_type。最适合简单的顺序大纲。对于复杂的嵌套（例如表格），考虑使用 roam_process_batch_actions。如果 page_title_uid 和 block_text_uid 都为空，则内容默认为日常页面。（内部使用 roam_process_batch_actions。）
  7. roam_search_block_refs：搜索页面内的块引用或整个图谱中的块引用。
  8. roam_search_hierarchy：搜索块层次结构中的父块或子块。
  9. roam_find_pages_modified_today：查找今天（从午夜开始）修改过的页面，带有分页和排序选项。
  10. roam_search_by_text：搜索包含特定文本的所有页面或特定页面中的块。此工具支持通过 limit 和 offset 参数进行分页。
  11. roam_search_by_status：搜索具有特定状态（TODO/DONE）的所有页面或特定页面中的块。
  12. roam_search_by_date：根据创建或修改日期搜索块或页面。
  13. roam_search_for_tag：搜索包含特定标签的块，并可选过滤出附近也包含另一个标签的块或排除包含特定标签的块。此工具支持通过 limit 和 offset 参数进行分页。
  14. roam_remember：添加记忆或信息以记住。（内部使用 roam_process_batch_actions。）
  15. roam_recall：检索所有存储的记忆。
  16. roam_datomic_query：在 Roam 图谱上执行自定义 Datomic 查询，以实现高级数据检索，超越现有的搜索工具。现在支持客户端侧正则表达式过滤，以增强查询后的处理。最佳用于复杂过滤（包括正则表达式）、高度复杂的布尔逻辑、任意排序标准和接近搜索。
  17. roam_markdown_cheatsheet：提供 Roam Markdown Cheat Sheet 资源的内容，如果设置了 CUSTOM_INSTRUCTIONS_PATH 环境变量，则可选连接自定义指令。
  18. roam_process_batch_actions：执行一系列低级块操作（创建、更新、移动、删除）在一个非事务性的批次中。提供对复杂嵌套如表格的细粒度控制。（注意：对于现有块的操作或在特定页面上下文中，通常需要先使用类似 roam_fetch_page_by_title 的工具获取有效的页面或块 UID。）

已弃用的工具： 以下工具已在 v0.36.2 中被更强大和灵活的 roam_process_batch_actions 替代：

  • roam_create_block：使用 roam_process_batch_actions 和 create-block 操作。
  • roam_update_block：使用 roam_process_batch_actions 和 update-block 操作。
  • roam_update_multiple_blocks：使用 roam_process_batch_actions 和多个 update-block 操作。

工具使用指南和最佳实践

预计算和上下文加载： ✅ 在尝试任何 Roam 操作之前，强烈建议 加载 Roam Markdown Cheat Sheet 资源到您的上下文中。这确保您立即拥有正确的 Roam 特色 Markdown 语法，包括表格、块引用和其他特殊格式的细节。示例提示：“首先阅读 Roam cheatsheet。然后，……<您的其余指令>”

  • 特定笔记和偏好 关于我的 Roam Research 图表。用户可以在 Cheat Sheet 中添加他们自己特定的笔记和偏好，以适应他们自己的图表。

识别用于操作的页面和块： 为了确保准确的操作，始终尽量使用它们的唯一标识符（UID）来识别目标页面和块。虽然某些工具接受大小写敏感的文本标题或内容，但 UID 提供了明确的引用，减少了由于歧义或文本更改而导致错误的风险。

  • 对于页面： 使用 roam_fetch_page_by_title 来检索页面的 UID，如果您只有它的标题。示例：“读取标题为 'Las Vegas 之旅' 的页面”
  • 对于块： 如果您需要操作一个现有的块，首先使用搜索工具如 roam_search_by_text、roam_search_for_tag 或 roam_fetch_page_by_title（以原始格式）找到块并获得其 UID。如果该块存在于已经读取的页面上，则不需要搜索。

大小写敏感性： 请注意，基于文本的输入（例如，页面标题、用于搜索的块内容）在 Roam 中通常是大小写敏感的。始终匹配文本在您的图表中出现的确切大小写。

迭代细化和验证： 对于复杂操作，尤其是涉及嵌套结构或多处更改的情况，通常有益于将任务分解成较小的、可验证的步骤。在每次重要的工具调用之后，考虑获取受影响的内容以验证更改后再继续。

理解工具的细微差别： 熟悉每个工具的具体行为和限制。例如，roam_create_outline 最适合顺序大纲，而 roam_process_batch_actions 提供了对复杂结构如表格的细粒度控制。参考各个工具描述以获取详细使用说明。

当对您的 Roam 图表进行更改时，精确请求至关重要，以实现预期结果。

请求的精确性： 一些工具允许通过文本内容（例如，parent_string、title）来识别块或页面。虽然方便，但使用唯一标识符（UID） 总是首选，以确保准确性和可靠性。基于文本的匹配容易出错，如果有多个块具有相似内容或内容发生变化。工具设计为在提供明确的 UID 时工作最佳。

精确性的示例： 而不是： "parent_string": "My project notes"

更推荐： "parent_uid": "((some-unique-uid))"

关于标题格式的注意事项： 请注意，虽然 roam_process_batch_actions 工具可以设置块标题（H1、H2、H3），但直接移除现有标题（即将标题块还原为普通文本块）目前不被 Roam API 支持。一旦设置，heading 属性会保留其值，试图通过设置 heading 为 0、null 或省略该属性来取消标题设置将不会取消标题。

示例提示

这里有一些如何创造性地使用 Roam 工具与您的 Roam 图表互动的例子，特别是利用 roam_process_batch_actions 进行复杂操作。

示例 1：创建项目大纲

此提示演示了如何使用单个 roam_process_batch_actions 调用来创建一个新的页面并填充结构化的大纲。

"创建一个新的 Roam 页面，标题为 'Project Alpha Planning' 并添加以下大纲：
- 概述
  - 目标
  - 范围
- 团队成员
  - John Doe
  - Jane Smith
- 任务
  - 任务 1
    - 子任务 1.1
    - 子任务 1.2
  - 任务 2
- 截止日期"

示例 2：更新多个待办事项并添加新的一个

此示例展示了如何标记现有的待办事项为 DONE 并添加一个新的，所有都在一个批次内完成。

"将 '完成报告' 和 '审查演示文稿' 标记为已完成，并在今天的日常页面上添加一个新的待办事项 '准备会议'。"

示例 3：移动和更新一个块

此示例演示了如何将一个块从一个位置移动到另一个位置，并同时更新其内容。

"将 '重要客户反馈注释' 块（来自页面 'Meeting Notes 2025-06-30'）移动到 'Project Alpha Planning' 页面的 '行动项' 部分，并将其内容更改为 '客户反馈已审阅并纳入'。"

示例 4：制作表格

此示例演示了如何在页面 "Fruity Tables" 上添加一个新表格，比较四种水果：苹果、橙子、葡萄和枣。随机选择四个领域进行比较。

"在 Roam 中，在页面 'Fruity Tables' 上添加一个新表格，比较四种水果：苹果、橙子、葡萄和枣。随机选择四个领域进行比较。"

设置

  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]]'
CUSTOM_INSTRUCTIONS_PATH='/path/to/your/custom_instructions_file.md'
HTTP_STREAM_PORT=8088 # 或您希望用于 HTTP 流通信的端口
SSE_PORT=8087 # 或您希望用于 SSE 通信的端口

    选项 2：使用 MCP 设置（替代方法） 将配置添加到您的 MCP 设置文件中。请注意，如果您直接运行服务器，可能需要将 args 更新为 ["/path/to/roam-research-mcp/build/index.js"]。

    • 对于 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]]",
        "CUSTOM_INSTRUCTIONS_PATH": "/path/to/your/custom_instructions_file.md",
        "HTTP_STREAM_PORT": "8088",
        "SSE_PORT": "8087"
      }
    }
  }
}

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

  3. 构建服务器（确保您位于 MCP 的根目录中）：

    注意：在构建前，请自定义 'Roam_Markdown_CheatSheet.md'，添加任何特定于您的图表的笔记和偏好。

    cd roam-research-mcp
npm install
npm run build

错误处理

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

  • 配置