roam-research-mcp 0.30.1 → 0.30.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +72 -115
- package/build/markdown-utils.js +1 -1
- package/build/server/roam-server.js +43 -1
- package/build/tools/schemas.js +9 -9
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -102,12 +102,13 @@ The server provides powerful tools for interacting with Roam Research:
|
|
|
102
102
|
- Detailed debug logging
|
|
103
103
|
- Efficient batch operations
|
|
104
104
|
- Hierarchical outline creation
|
|
105
|
+
- Enhanced documentation for Roam Tables in `Roam_Markdown_Cheatsheet.md` for clearer guidance on nesting.
|
|
105
106
|
|
|
106
|
-
1. `roam_fetch_page_by_title`: Fetch page content by title.
|
|
107
|
+
1. `roam_fetch_page_by_title`: Fetch page content by title. Returns content in the specified format.
|
|
107
108
|
2. `roam_create_page`: Create new pages with optional content and headings.
|
|
108
109
|
3. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)
|
|
109
110
|
4. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)
|
|
110
|
-
5. `roam_create_outline`: Add a structured outline to an existing page or block, with support for `children_view_type`. (Internally uses `roam_process_batch_actions`.)
|
|
111
|
+
5. `roam_create_outline`: Add a structured outline to an existing page or block, with support for `children_view_type`. Best for simpler, sequential outlines. For complex nesting (e.g., tables), consider `roam_process_batch_actions`. If `page_title_uid` and `block_text_uid` are both blank, content defaults to the daily page. (Internally uses `roam_process_batch_actions`.)
|
|
111
112
|
6. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
|
|
112
113
|
7. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
|
|
113
114
|
8. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight).
|
|
@@ -117,8 +118,8 @@ The server provides powerful tools for interacting with Roam Research:
|
|
|
117
118
|
12. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.
|
|
118
119
|
13. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)
|
|
119
120
|
14. `roam_recall`: Retrieve all stored memories.
|
|
120
|
-
15. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph beyond the available search tools.
|
|
121
|
-
16. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch.
|
|
121
|
+
15. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools.
|
|
122
|
+
16. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
|
|
122
123
|
|
|
123
124
|
**Deprecated Tools**:
|
|
124
125
|
The following tools have been deprecated as of `v.0.30.0` in favor of the more powerful and flexible `roam_process_batch_actions`:
|
|
@@ -127,7 +128,27 @@ The following tools have been deprecated as of `v.0.30.0` in favor of the more p
|
|
|
127
128
|
- `roam_update_block`: Use `roam_process_batch_actions` with the `update-block` action.
|
|
128
129
|
- `roam_update_multiple_blocks`: Use `roam_process_batch_actions` with multiple `update-block` actions.
|
|
129
130
|
|
|
130
|
-
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
### Tool Usage Guidelines and Best Practices
|
|
134
|
+
|
|
135
|
+
**Pre-computation and Context Loading:**
|
|
136
|
+
✅ Before attempting any Roam operations, **it is highly recommended** to load the `Roam Markdown Cheatsheet` resource into your context. This ensures you have immediate access to the correct Roam-flavored Markdown syntax, including details for tables, block references, and other special formatting. Example prompt: "Read the Roam cheatsheet first. Then, … <rest of your instructions>"
|
|
137
|
+
|
|
138
|
+
**Identifying Pages and Blocks for Manipulation:**
|
|
139
|
+
To ensure accurate operations, always strive to identify target pages and blocks using their Unique Identifiers (UIDs) whenever possible. While some tools accept case-sensitive text titles or content, UIDs provide unambiguous references, reducing the risk of errors due to ambiguity or changes in text.
|
|
140
|
+
|
|
141
|
+
- **For Pages:** Use `roam_fetch_page_by_title` to retrieve a page's UID if you only have its title. Example: "Read the page titled 'Trip to Las Vegas'"
|
|
142
|
+
- **For Blocks:** If you need to manipulate an existing block, first use search tools like `roam_search_by_text`, `roam_search_for_tag`, or `roam_fetch_page_by_title` (with raw format) to find the block and obtain its UID. If the block exists on a page that has already been read, then a search isn't necessary.
|
|
143
|
+
|
|
144
|
+
**Case-Sensitivity:**
|
|
145
|
+
Be aware that text-based inputs (e.g., page titles, block content for search) are generally case-sensitive in Roam. Always match the exact casing of the text as it appears in your graph.
|
|
146
|
+
|
|
147
|
+
**Iterative Refinement and Verification:**
|
|
148
|
+
For complex operations, especially those involving nested structures or multiple changes, it is often beneficial to break down the task into smaller, verifiable steps. After each significant tool call, consider fetching the affected content to verify the changes before proceeding.
|
|
149
|
+
|
|
150
|
+
**Understanding Tool Nuances:**
|
|
151
|
+
Familiarize yourself with the specific behaviors and limitations of each tool. For instance, `roam_create_outline` is best for sequential outlines, while `roam_process_batch_actions` offers granular control for complex structures like tables. Refer to the individual tool descriptions for detailed usage notes.
|
|
131
152
|
|
|
132
153
|
When making changes to your Roam graph, precision in your requests is crucial for achieving desired outcomes.
|
|
133
154
|
|
|
@@ -141,119 +162,53 @@ Instead of:
|
|
|
141
162
|
Prefer:
|
|
142
163
|
`"parent_uid": "((some-unique-uid))"`
|
|
143
164
|
|
|
144
|
-
**Migrating from Deprecated Tools:**
|
|
145
|
-
The following examples demonstrate how to achieve the functionality of the deprecated tools using `roam_process_batch_actions`.
|
|
146
|
-
|
|
147
|
-
**1. Replacing `roam_create_block`:**
|
|
148
|
-
|
|
149
|
-
- **Old (Deprecated):**
|
|
150
|
-
```json
|
|
151
|
-
{
|
|
152
|
-
"tool_name": "roam_create_block",
|
|
153
|
-
"arguments": {
|
|
154
|
-
"content": "New block content",
|
|
155
|
-
"page_uid": "((page-uid))"
|
|
156
|
-
}
|
|
157
|
-
}
|
|
158
|
-
```
|
|
159
|
-
- **New (Recommended):**
|
|
160
|
-
```json
|
|
161
|
-
{
|
|
162
|
-
"tool_name": "roam_process_batch_actions",
|
|
163
|
-
"arguments": {
|
|
164
|
-
"actions": [
|
|
165
|
-
{
|
|
166
|
-
"action": "create-block",
|
|
167
|
-
"location": {
|
|
168
|
-
"parent-uid": "((page-uid))",
|
|
169
|
-
"order": "last"
|
|
170
|
-
},
|
|
171
|
-
"block": {
|
|
172
|
-
"string": "New block content"
|
|
173
|
-
}
|
|
174
|
-
}
|
|
175
|
-
]
|
|
176
|
-
}
|
|
177
|
-
}
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
**2. Replacing `roam_update_block`:**
|
|
181
|
-
|
|
182
|
-
- **Old (Deprecated):**
|
|
183
|
-
```json
|
|
184
|
-
{
|
|
185
|
-
"tool_name": "roam_update_block",
|
|
186
|
-
"arguments": {
|
|
187
|
-
"block_uid": "((block-uid))",
|
|
188
|
-
"content": "Updated block content"
|
|
189
|
-
}
|
|
190
|
-
}
|
|
191
|
-
```
|
|
192
|
-
- **New (Recommended):**
|
|
193
|
-
```json
|
|
194
|
-
{
|
|
195
|
-
"tool_name": "roam_process_batch_actions",
|
|
196
|
-
"arguments": {
|
|
197
|
-
"actions": [
|
|
198
|
-
{
|
|
199
|
-
"action": "update-block",
|
|
200
|
-
"uid": "((block-uid))",
|
|
201
|
-
"string": "Updated block content"
|
|
202
|
-
}
|
|
203
|
-
]
|
|
204
|
-
}
|
|
205
|
-
}
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
**3. Replacing `roam_update_multiple_blocks`:**
|
|
209
|
-
|
|
210
|
-
- **Old (Deprecated):**
|
|
211
|
-
```json
|
|
212
|
-
{
|
|
213
|
-
"tool_name": "roam_update_multiple_blocks",
|
|
214
|
-
"arguments": {
|
|
215
|
-
"updates": [
|
|
216
|
-
{
|
|
217
|
-
"block_uid": "((block-uid-1))",
|
|
218
|
-
"content": "Content for block 1"
|
|
219
|
-
},
|
|
220
|
-
{
|
|
221
|
-
"block_uid": "((block-uid-2))",
|
|
222
|
-
"transform": {
|
|
223
|
-
"find": "old text",
|
|
224
|
-
"replace": "new text"
|
|
225
|
-
}
|
|
226
|
-
}
|
|
227
|
-
]
|
|
228
|
-
}
|
|
229
|
-
}
|
|
230
|
-
```
|
|
231
|
-
- **New (Recommended):**
|
|
232
|
-
```json
|
|
233
|
-
{
|
|
234
|
-
"tool_name": "roam_process_batch_actions",
|
|
235
|
-
"arguments": {
|
|
236
|
-
"actions": [
|
|
237
|
-
{
|
|
238
|
-
"action": "update-block",
|
|
239
|
-
"uid": "((block-uid-1))",
|
|
240
|
-
"string": "Content for block 1"
|
|
241
|
-
},
|
|
242
|
-
{
|
|
243
|
-
"action": "update-block",
|
|
244
|
-
"uid": "((block-uid-2))",
|
|
245
|
-
"string": "((block-content-with-new-text))"
|
|
246
|
-
// Note: Transformations (find/replace) must be handled by the client
|
|
247
|
-
// before sending the 'string' to roam_process_batch_actions.
|
|
248
|
-
}
|
|
249
|
-
]
|
|
250
|
-
}
|
|
251
|
-
}
|
|
252
|
-
```
|
|
253
|
-
|
|
254
165
|
**Caveat Regarding Heading Formatting:**
|
|
255
166
|
Please note that while the `roam_process_batch_actions` tool can set block headings (H1, H2, H3), directly **removing** an existing heading (i.e., reverting a heading block to a plain text block) through this tool is not currently supported by the Roam API. The `heading` attribute persists its value once set, and attempting to remove it by setting `heading` to `0`, `null`, or omitting the property will not unset the heading.
|
|
256
167
|
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## Example Prompts
|
|
171
|
+
|
|
172
|
+
Here are some examples of how to creatively use the Roam tool in an LLM to interact with your Roam graph, particularly leveraging `roam_process_batch_actions` for complex operations.
|
|
173
|
+
|
|
174
|
+
### Example 1: Creating a Project Outline
|
|
175
|
+
|
|
176
|
+
This prompt demonstrates creating a new page and populating it with a structured outline using a single `roam_process_batch_actions` call.
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
"Create a new Roam page titled 'Project Alpha Planning' and add the following outline:
|
|
180
|
+
- Overview
|
|
181
|
+
- Goals
|
|
182
|
+
- Scope
|
|
183
|
+
- Team Members
|
|
184
|
+
- John Doe
|
|
185
|
+
- Jane Smith
|
|
186
|
+
- Tasks
|
|
187
|
+
- Task 1
|
|
188
|
+
- Subtask 1.1
|
|
189
|
+
- Subtask 1.2
|
|
190
|
+
- Task 2
|
|
191
|
+
- Deadlines"
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Example 2: Updating Multiple To-Dos and Adding a New One
|
|
195
|
+
|
|
196
|
+
This example shows how to mark existing to-do items as `DONE` and add a new one, all within a single batch.
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
"Mark 'Finish report' and 'Review presentation' as done on today's daily page, and add a new todo 'Prepare for meeting'."
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Example 3: Moving and Updating a Block
|
|
203
|
+
|
|
204
|
+
This demonstrates moving a block from one location to another and simultaneously updating its content.
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
"Move the block 'Important note about client feedback' (from page 'Meeting Notes 2025-06-30') under the 'Action Items' section on the 'Project Alpha Planning' page, and change its content to 'Client feedback reviewed and incorporated'."
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
257
212
|
## Setup
|
|
258
213
|
|
|
259
214
|
1. Create a [Roam Research API token](https://x.com/RoamResearch/status/1789358175474327881):
|
|
@@ -333,6 +288,8 @@ Each error response includes:
|
|
|
333
288
|
- Detailed error message
|
|
334
289
|
- Suggestions for resolution when applicable
|
|
335
290
|
|
|
291
|
+
---
|
|
292
|
+
|
|
336
293
|
## Development
|
|
337
294
|
|
|
338
295
|
### Building
|
package/build/markdown-utils.js
CHANGED
|
@@ -21,7 +21,7 @@ function convertTableToRoamFormat(text) {
|
|
|
21
21
|
.replace(/^\||\|$/g, '')
|
|
22
22
|
.split('|')
|
|
23
23
|
.map(cell => cell.trim()));
|
|
24
|
-
let roamTable = '{{table}}\n';
|
|
24
|
+
let roamTable = '{{[[table]]}}\n';
|
|
25
25
|
// First row becomes column headers
|
|
26
26
|
const headers = rows[0];
|
|
27
27
|
for (let i = 0; i < headers.length; i++) {
|
|
@@ -2,7 +2,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
|
2
2
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
3
3
|
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
|
|
4
4
|
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
|
|
5
|
-
import { CallToolRequestSchema, ErrorCode,
|
|
5
|
+
import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
|
|
6
6
|
import { initializeGraph } from '@roam-research/roam-api-sdk';
|
|
7
7
|
import { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT } from '../config/environment.js';
|
|
8
8
|
import { toolSchemas } from '../tools/schemas.js';
|
|
@@ -20,6 +20,7 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
|
|
|
20
20
|
const serverVersion = packageJson.version;
|
|
21
21
|
export class RoamServer {
|
|
22
22
|
constructor() {
|
|
23
|
+
console.log('RoamServer: Constructor started.');
|
|
23
24
|
try {
|
|
24
25
|
this.graph = initializeGraph({
|
|
25
26
|
token: API_TOKEN,
|
|
@@ -41,6 +42,7 @@ export class RoamServer {
|
|
|
41
42
|
if (Object.keys(toolSchemas).length === 0) {
|
|
42
43
|
throw new McpError(ErrorCode.InternalError, 'No tool schemas defined in src/tools/schemas.ts');
|
|
43
44
|
}
|
|
45
|
+
console.log('RoamServer: Constructor finished.');
|
|
44
46
|
}
|
|
45
47
|
// Refactored to accept a Server instance
|
|
46
48
|
setupRequestHandlers(mcpServer) {
|
|
@@ -48,6 +50,32 @@ export class RoamServer {
|
|
|
48
50
|
mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
|
|
49
51
|
tools: Object.values(toolSchemas),
|
|
50
52
|
}));
|
|
53
|
+
// List available resources
|
|
54
|
+
mcpServer.setRequestHandler(ListResourcesRequestSchema, async () => {
|
|
55
|
+
const resources = [
|
|
56
|
+
{
|
|
57
|
+
name: 'Roam Markdown Cheatsheet',
|
|
58
|
+
uri: 'roam-markdown-cheatsheet.md',
|
|
59
|
+
type: 'text', // Changed from ResourceType.Text to string literal 'text'
|
|
60
|
+
description: 'A cheatsheet for Roam-flavored Markdown syntax.',
|
|
61
|
+
},
|
|
62
|
+
];
|
|
63
|
+
return { resources };
|
|
64
|
+
});
|
|
65
|
+
// Access resource
|
|
66
|
+
mcpServer.setRequestHandler(ReadResourceRequestSchema, async (request) => {
|
|
67
|
+
if (request.params.uri === 'roam-markdown-cheatsheet.md') {
|
|
68
|
+
const cheatsheetPath = join(__dirname, '../../Roam_Markdown_Cheatsheet.md');
|
|
69
|
+
try {
|
|
70
|
+
const content = readFileSync(cheatsheetPath, 'utf8');
|
|
71
|
+
return { contents: [{ type: 'text', text: content, uri: request.params.uri }] };
|
|
72
|
+
}
|
|
73
|
+
catch (error) {
|
|
74
|
+
throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`); // Changed to InternalError
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
throw new McpError(ErrorCode.InternalError, `Resource not found: ${request.params.uri}`); // Changed to InternalError
|
|
78
|
+
});
|
|
51
79
|
// Handle tool calls
|
|
52
80
|
mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
53
81
|
try {
|
|
@@ -182,7 +210,9 @@ export class RoamServer {
|
|
|
182
210
|
});
|
|
183
211
|
}
|
|
184
212
|
async run() {
|
|
213
|
+
console.log('RoamServer: run() method started.');
|
|
185
214
|
try {
|
|
215
|
+
console.log('RoamServer: Attempting to create stdioMcpServer...');
|
|
186
216
|
const stdioMcpServer = new Server({
|
|
187
217
|
name: 'roam-research',
|
|
188
218
|
version: serverVersion,
|
|
@@ -191,11 +221,17 @@ export class RoamServer {
|
|
|
191
221
|
tools: {
|
|
192
222
|
...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
|
|
193
223
|
},
|
|
224
|
+
resources: {
|
|
225
|
+
'roam-markdown-cheatsheet.md': {}
|
|
226
|
+
}
|
|
194
227
|
},
|
|
195
228
|
});
|
|
229
|
+
console.log('RoamServer: stdioMcpServer created. Setting up request handlers...');
|
|
196
230
|
this.setupRequestHandlers(stdioMcpServer);
|
|
231
|
+
console.log('RoamServer: stdioMcpServer handlers setup complete. Connecting transport...');
|
|
197
232
|
const stdioTransport = new StdioServerTransport();
|
|
198
233
|
await stdioMcpServer.connect(stdioTransport);
|
|
234
|
+
console.log('RoamServer: stdioTransport connected. Attempting to create httpMcpServer...');
|
|
199
235
|
const httpMcpServer = new Server({
|
|
200
236
|
name: 'roam-research-http', // A distinct name for the HTTP server
|
|
201
237
|
version: serverVersion,
|
|
@@ -204,13 +240,19 @@ export class RoamServer {
|
|
|
204
240
|
tools: {
|
|
205
241
|
...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
|
|
206
242
|
},
|
|
243
|
+
resources: {
|
|
244
|
+
'roam-markdown-cheatsheet.md': {}
|
|
245
|
+
}
|
|
207
246
|
},
|
|
208
247
|
});
|
|
248
|
+
console.log('RoamServer: httpMcpServer created. Setting up request handlers...');
|
|
209
249
|
this.setupRequestHandlers(httpMcpServer);
|
|
250
|
+
console.log('RoamServer: httpMcpServer handlers setup complete. Connecting transport...');
|
|
210
251
|
const httpStreamTransport = new StreamableHTTPServerTransport({
|
|
211
252
|
sessionIdGenerator: () => Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
|
|
212
253
|
});
|
|
213
254
|
await httpMcpServer.connect(httpStreamTransport);
|
|
255
|
+
console.log('RoamServer: httpStreamTransport connected.');
|
|
214
256
|
const httpServer = createServer(async (req, res) => {
|
|
215
257
|
try {
|
|
216
258
|
await httpStreamTransport.handleRequest(req, res);
|
package/build/tools/schemas.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
export const toolSchemas = {
|
|
3
3
|
roam_add_todo: {
|
|
4
4
|
name: 'roam_add_todo',
|
|
5
|
-
description: 'Add a list of todo items as individual blocks to today\'s daily page in Roam. Each item becomes its own actionable block with todo status.\nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
|
|
5
|
+
description: 'Add a list of todo items as individual blocks to today\'s daily page in Roam. Each item becomes its own actionable block with todo status.\nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
|
|
6
6
|
inputSchema: {
|
|
7
7
|
type: 'object',
|
|
8
8
|
properties: {
|
|
@@ -20,7 +20,7 @@ export const toolSchemas = {
|
|
|
20
20
|
},
|
|
21
21
|
roam_fetch_page_by_title: {
|
|
22
22
|
name: 'roam_fetch_page_by_title',
|
|
23
|
-
description: 'Fetch page by title
|
|
23
|
+
description: 'Fetch page by title. Returns content in the specified format.',
|
|
24
24
|
inputSchema: {
|
|
25
25
|
type: 'object',
|
|
26
26
|
properties: {
|
|
@@ -40,7 +40,7 @@ export const toolSchemas = {
|
|
|
40
40
|
},
|
|
41
41
|
roam_create_page: {
|
|
42
42
|
name: 'roam_create_page',
|
|
43
|
-
description: 'Create new standalone page in Roam with optional content using explicit nesting levels and headings (H1-H3). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.',
|
|
43
|
+
description: 'Create new standalone page in Roam with optional content using explicit nesting levels and headings (H1-H3). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
|
|
44
44
|
inputSchema: {
|
|
45
45
|
type: 'object',
|
|
46
46
|
properties: {
|
|
@@ -80,7 +80,7 @@ export const toolSchemas = {
|
|
|
80
80
|
},
|
|
81
81
|
roam_create_outline: {
|
|
82
82
|
name: 'roam_create_outline',
|
|
83
|
-
description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. Best for:\n- Adding supplementary structured content to existing pages\n- Creating temporary or working outlines (meeting notes, brainstorms)\n- Organizing thoughts or research under a specific topic\n- Breaking down subtopics or components of a larger concept',
|
|
83
|
+
description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. Best for:\n- Adding supplementary structured content to existing pages\n- Creating temporary or working outlines (meeting notes, brainstorms)\n- Organizing thoughts or research under a specific topic\n- Breaking down subtopics or components of a larger concept\nBest for simpler, contiguous hierarchical content. For complex nesting (e.g., tables) or granular control over block placement, consider `roam_process_batch_actions` instead.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
|
|
84
84
|
inputSchema: {
|
|
85
85
|
type: 'object',
|
|
86
86
|
properties: {
|
|
@@ -90,7 +90,7 @@ export const toolSchemas = {
|
|
|
90
90
|
},
|
|
91
91
|
block_text_uid: {
|
|
92
92
|
type: 'string',
|
|
93
|
-
description: 'The text content or UID of the block to nest the outline under (UID is preferred for accuracy). If blank, content is nested directly under the page.'
|
|
93
|
+
description: 'The text content or UID of the block to nest the outline under (UID is preferred for accuracy). If blank, content is nested directly under the page (or the default daily page if page_title_uid is also blank).'
|
|
94
94
|
},
|
|
95
95
|
outline: {
|
|
96
96
|
type: 'array',
|
|
@@ -129,7 +129,7 @@ export const toolSchemas = {
|
|
|
129
129
|
},
|
|
130
130
|
roam_import_markdown: {
|
|
131
131
|
name: 'roam_import_markdown',
|
|
132
|
-
description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.',
|
|
132
|
+
description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
|
|
133
133
|
inputSchema: {
|
|
134
134
|
type: 'object',
|
|
135
135
|
properties: {
|
|
@@ -324,7 +324,7 @@ export const toolSchemas = {
|
|
|
324
324
|
},
|
|
325
325
|
roam_remember: {
|
|
326
326
|
name: 'roam_remember',
|
|
327
|
-
description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
|
|
327
|
+
description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
|
|
328
328
|
inputSchema: {
|
|
329
329
|
type: 'object',
|
|
330
330
|
properties: {
|
|
@@ -364,7 +364,7 @@ export const toolSchemas = {
|
|
|
364
364
|
},
|
|
365
365
|
roam_datomic_query: {
|
|
366
366
|
name: 'roam_datomic_query',
|
|
367
|
-
description: 'Execute a custom Datomic query on the Roam graph beyond the available search tools. This provides direct access to Roam\'s query engine
|
|
367
|
+
description: 'Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. This provides direct access to Roam\'s query engine. Note: Roam graph is case-sensitive.\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
|
|
368
368
|
inputSchema: {
|
|
369
369
|
type: 'object',
|
|
370
370
|
properties: {
|
|
@@ -385,7 +385,7 @@ export const toolSchemas = {
|
|
|
385
385
|
},
|
|
386
386
|
roam_process_batch_actions: {
|
|
387
387
|
name: 'roam_process_batch_actions',
|
|
388
|
-
description: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order. For creating nested blocks, you can use a temporary client-side UID in a parent block and refer to it in a child block within the same batch. For actions on existing blocks, a valid block UID is required.',
|
|
388
|
+
description: 'Executes a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Actions are executed in the provided order. For creating nested blocks, you can use a temporary client-side UID in a parent block and refer to it in a child block within the same batch. For actions on existing blocks, a valid block UID is required. Note: Roam-flavored markdown, including block embedding with `((UID))` syntax, is supported within the `string` property for `create-block` and `update-block` actions. For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs. Tools like `roam_fetch_page_by_title` or other search tools can be used to retrieve these UIDs before executing batch actions. For simpler, sequential outlines, `roam_create_outline` is often more suitable.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.',
|
|
389
389
|
inputSchema: {
|
|
390
390
|
type: 'object',
|
|
391
391
|
properties: {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "roam-research-mcp",
|
|
3
|
-
"version": "0.30.
|
|
3
|
+
"version": "0.30.2",
|
|
4
4
|
"description": "A Model Context Protocol (MCP) server for Roam Research API integration",
|
|
5
5
|
"private": false,
|
|
6
6
|
"repository": {
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"start": "node build/index.js"
|
|
35
35
|
},
|
|
36
36
|
"dependencies": {
|
|
37
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
37
|
+
"@modelcontextprotocol/sdk": "^1.13.2",
|
|
38
38
|
"@roam-research/roam-api-sdk": "^0.10.0",
|
|
39
39
|
"dotenv": "^16.4.7"
|
|
40
40
|
},
|