Roam Research MCP Server

Instructions

Implementation Reference

• src/tools/operations/todos.ts:8-69 (handler)

  Core handler implementation for roam_add_todo: adds todo items as individual TODO blocks to today's daily page, creating the page if necessary.
  async addTodos(todos: string[]): Promise<{ success: boolean }> { if (!Array.isArray(todos) || todos.length === 0) { throw new McpError( ErrorCode.InvalidRequest, 'todos must be a non-empty array' ); } // Get today's date const today = new Date(); const dateStr = formatRoamDate(today); // Try to find today's page 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][]; let targetPageUid: string; if (findResults && findResults.length > 0) { targetPageUid = findResults[0][0]; } else { // Create today's page if it doesn't exist try { await createPage(this.graph, { action: 'create-page', page: { title: dateStr } }); // Get the new page's UID const results = await q(this.graph, findQuery, [dateStr]) as [string][]; if (!results || results.length === 0) { throw new Error('Could not find created today\'s page'); } targetPageUid = results[0][0]; } catch (error) { throw new Error('Failed to create today\'s page'); } } const todo_tag = "{{TODO}}"; const actions = todos.map((todo, index) => ({ action: 'create-block', location: { 'parent-uid': targetPageUid, order: index }, block: { string: `${todo_tag} ${todo}` } })); const result = await batchActions(this.graph, { action: 'batch-actions', actions }); if (!result) { throw new Error('Failed to create todo blocks'); } return { success: true }; }
• src/tools/schemas.ts:40-57 (schema)

  Input schema definition for the roam_add_todo tool, specifying an array of todo strings.
  [toolName(BASE_TOOL_NAMES.ADD_TODO)]: { name: toolName(BASE_TOOL_NAMES.ADD_TODO), 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.', inputSchema: { type: 'object', properties: { todos: { type: 'array', items: { type: 'string', description: 'Todo item text' }, description: 'List of todo items to add' } }, required: ['todos'], }, },
• src/server/roam-server.ts:189-195 (registration)

  Tool registration in the MCP server's callTool handler switch statement, dispatching to toolHandlers.addTodos.
  case BASE_TOOL_NAMES.ADD_TODO: { const { todos } = request.params.arguments as { todos: string[] }; const result = await this.toolHandlers.addTodos(todos); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
• src/tools/tool-handlers.ts:119-121 (handler)

  Wrapper handler in ToolHandlers class that delegates to TodoOperations.addTodos.
  async addTodos(todos: string[]) { return this.todoOps.addTodos(todos); }
• src/tools/tool-handlers.ts:21-32 (registration)

  Instantiation of TodoOperations instance in ToolHandlers constructor for use by addTodos wrapper.
  private todoOps: TodoOperations; private outlineOps: OutlineOperations; private batchOps: BatchOperations; private cachedCheatsheet: string | null = null; constructor(private graph: Graph) { this.pageOps = new PageOperations(graph); this.blockOps = new BlockOperations(graph); this.blockRetrievalOps = new BlockRetrievalOperations(graph); // Initialize new instance this.searchOps = new SearchOperations(graph); this.memoryOps = new MemoryOperations(graph); this.todoOps = new TodoOperations(graph);