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/ - 定义类型文件

📄 许可证

文档中未提及相关信息。