🚀 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/ - 定义类型文件
📄 许可证
文档中未提及相关信息。