Roam Research MCP Server

Instructions

Implementation Reference

• src/tools/operations/outline.ts:497-671 (handler)

  Core handler implementation that resolves target page and parent block, parses nested markdown content using parseMarkdown and convertToRoamActions, executes batchActions to import into Roam graph, fetches and returns created nested block structure.
  async importMarkdown( content: string, page_uid?: string, page_title?: string, parent_uid?: string, parent_string?: string, order: 'first' | 'last' = 'last' ): Promise<{ success: boolean; page_uid: string; parent_uid: string; created_uids: NestedBlock[] }> { // First get the page UID let targetPageUid = page_uid; if (!targetPageUid && page_title) { const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`; const findResults = await q(this.graph, findQuery, [page_title]) as [string][]; if (findResults && findResults.length > 0) { targetPageUid = findResults[0][0]; } else { throw new McpError( ErrorCode.InvalidRequest, `Page with title "${page_title}" not found` ); } } // If no page specified, use today's date page if (!targetPageUid) { const today = new Date(); const dateStr = formatRoamDate(today); const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`; const findResults = await q(this.graph, findQuery, [dateStr]) as [string][]; if (findResults && findResults.length > 0) { targetPageUid = findResults[0][0]; } else { // Create today's page try { await createPage(this.graph, { action: 'create-page', page: { title: dateStr } }); const results = await q(this.graph, findQuery, [dateStr]) as [string][]; if (!results || results.length === 0) { throw new McpError( ErrorCode.InternalError, 'Could not find created today\'s page' ); } targetPageUid = results[0][0]; } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to create today's page: ${error instanceof Error ? error.message : String(error)}` ); } } } // Now get the parent block UID let targetParentUid = parent_uid; if (!targetParentUid && parent_string) { if (!targetPageUid) { throw new McpError( ErrorCode.InvalidRequest, 'Must provide either page_uid or page_title when using parent_string' ); } // Find block by exact string match within the page const findBlockQuery = `[:find ?b-uid :in $ ?page-uid ?block-string :where [?p :block/uid ?page-uid] [?b :block/page ?p] [?b :block/string ?block-string] [?b :block/uid ?b-uid]]`; const blockResults = await q(this.graph, findBlockQuery, [targetPageUid, parent_string]) as [string][]; if (blockResults && blockResults.length > 0) { targetParentUid = blockResults[0][0]; } else { // If parent_string block doesn't exist, create it targetParentUid = await this.createAndVerifyBlock(parent_string, targetPageUid); } } // If no parent specified, use page as parent if (!targetParentUid) { targetParentUid = targetPageUid; } // Always use parseMarkdown for content with multiple lines or any markdown formatting const isMultilined = content.includes('\n'); if (isMultilined) { // Parse markdown into hierarchical structure const convertedContent = convertToRoamMarkdown(content); const nodes = parseMarkdown(convertedContent); // Convert markdown nodes to batch actions const actions = convertToRoamActions(nodes, targetParentUid, order); // Execute batch actions to add content const result = await batchActions(this.graph, { action: 'batch-actions', actions }); if (!result) { throw new McpError( ErrorCode.InternalError, 'Failed to import nested markdown content' ); } // After successful batch action, get all nested UIDs under the parent const createdUids = await this.fetchNestedStructure(targetParentUid); return { success: true, page_uid: targetPageUid, parent_uid: targetParentUid, created_uids: createdUids }; } else { // Create a simple block for non-nested content using batchActions const actions = [{ action: 'create-block', location: { "parent-uid": targetParentUid, "order": order }, block: { string: content } }]; try { await batchActions(this.graph, { action: 'batch-actions', actions }); } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to create content block: ${error instanceof Error ? error.message : String(error)}` ); } // For single-line content, we still need to fetch the UID and construct a NestedBlock const createdUids: NestedBlock[] = []; try { const foundUid = await this.findBlockWithRetry(targetParentUid, content); if (foundUid) { createdUids.push({ uid: foundUid, text: content, level: 0, order: 0, children: [] }); } } catch (error: any) { // Log warning but don't re-throw, as the block might be created, just not immediately verifiable // console.warn(`Could not verify single block creation for "${content}": ${error.message}`); } return { success: true, page_uid: targetPageUid, parent_uid: targetParentUid, created_uids: createdUids }; } }
• src/tools/schemas.ts:169-204 (schema)

  Input schema definition, description, and tool name generation for 'roam_import_markdown'.
  [toolName(BASE_TOOL_NAMES.IMPORT_MARKDOWN)]: { name: toolName(BASE_TOOL_NAMES.IMPORT_MARKDOWN), 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. If a `parent_string` is provided and the block does not exist, it will be created. Returns a nested structure of the created blocks.\nIMPORTANT: Before using this tool, ensure that you have loaded into context the \'Roam Markdown Cheatsheet\' resource.', inputSchema: { type: 'object', properties: { content: { type: 'string', description: 'Nested markdown content to import' }, page_uid: { type: 'string', description: 'Optional: UID of the page containing the parent block (preferred for accuracy).' }, page_title: { type: 'string', description: 'Optional: Title of the page containing the parent block (used if page_uid is not provided).' }, parent_uid: { type: 'string', description: 'Optional: UID of the parent block to add content under (preferred for accuracy).' }, parent_string: { type: 'string', description: 'Optional: Exact string content of an existing parent block to add content under (used if parent_uid is not provided; requires page_uid or page_title). If the block does not exist, it will be created.' }, order: { type: 'string', description: 'Optional: Where to add the content under the parent ("first" or "last")', enum: ['first', 'last'], default: 'first' } }, required: ['content'] } },
• src/server/roam-server.ts:160-187 (registration)

  MCP server request handler registration for the tool, extracting arguments and delegating to ToolHandlers.importMarkdown.
  case BASE_TOOL_NAMES.IMPORT_MARKDOWN: { const { content, page_uid, page_title, parent_uid, parent_string, order = 'first' } = request.params.arguments as { content: string; page_uid?: string; page_title?: string; parent_uid?: string; parent_string?: string; order?: 'first' | 'last'; }; const result = await this.toolHandlers.importMarkdown( content, page_uid, page_title, parent_uid, parent_string, order ); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
• src/tools/tool-handlers.ts:128-137 (handler)

  Wrapper handler in ToolHandlers class that delegates to OutlineOperations.importMarkdown.
  async importMarkdown( content: string, page_uid?: string, page_title?: string, parent_uid?: string, parent_string?: string, order: 'first' | 'last' = 'first' ) { return this.outlineOps.importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order); }