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 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
- ### Important Considerations for Tool Usage
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
@@ -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, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
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);
@@ -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, defaults to raw JSON string.',
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 for advanced data retrieval. 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.',
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.1",
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.0.0",
37
+ "@modelcontextprotocol/sdk": "^1.13.2",
38
38
  "@roam-research/roam-api-sdk": "^0.10.0",
39
39
  "dotenv": "^16.4.7"
40
40
  },