roam_add_todo
Add multiple todo items to today's Roam daily page as individual actionable blocks, each with todo status, using a list of text strings.
Instructions
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. NOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use alias syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words). IMPORTANT: Before using this tool, ensure that you have loaded into context the 'Roam Markdown Cheatsheet' resource.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| todos | Yes | List of todo items to add | |
| graph | No | Target graph key from ROAM_GRAPHS config. Defaults to ROAM_DEFAULT_GRAPH. Only needed in multi-graph mode. | |
| write_key | No | Write confirmation key. Required for write operations on non-default graphs when write_key is configured. |
Implementation Reference
- src/tools/operations/todos.ts:9-34 (handler)Core handler for roam_add_todo. Gets or creates today's daily page, maps each todo string to a 'create-block' action with {{[[TODO]]}} prefix, then executes the batch.
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 or create today's daily page const targetPageUid = await getOrCreateTodayPage(this.graph); const todo_tag = "{{[[TODO]]}}"; const actions = todos.map((todo, index) => ({ action: 'create-block', location: { 'parent-uid': targetPageUid, order: index }, block: { string: `${todo_tag} ${todo}` } })); await executeBatch(this.graph, actions, 'create todo blocks'); return { success: true }; } - src/tools/schemas.ts:29-46 (schema)Input schema for roam_add_todo: accepts an array of strings ('todos') plus optional multi-graph params (graph, write_key). 'todos' is required.
roam_add_todo: { name: 'roam_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: withMultiGraphParams({ todos: { type: 'array', items: { type: 'string', description: 'Todo item text' }, description: 'List of todo items to add' } }), required: ['todos'], }, }, - src/server/roam-server.ts:263-269 (registration)Case handler in the tool dispatch switch statement. Extracts 'todos' from cleanedArgs and delegates to toolHandlers.addTodos().
case 'roam_add_todo': { const { todos } = cleanedArgs as { todos: string[] }; const result = await toolHandlers.addTodos(todos); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; } - src/tools/tool-handlers.ts:144-145 (helper)Delegation method in ToolHandlers class that forwards addTodos calls to this.todoOps.addTodos(todos).
async addTodos(todos: string[]) { return this.todoOps.addTodos(todos); - src/config/graph-registry.ts:34-45 (registration)WRITE_OPERATIONS list marks roam_add_todo as a write operation, requiring write confirmation for protected graphs.
export const WRITE_OPERATIONS = [ 'roam_create_page', 'roam_create_outline', 'roam_import_markdown', 'roam_process_batch_actions', 'roam_add_todo', 'roam_remember', 'roam_create_table', 'roam_move_block', 'roam_update_page_markdown', 'roam_rename_page', ] as const;