roam_find_pages_modified_today
Retrieve pages modified today in Roam Research with pagination and sorting options for efficient daily review.
Instructions
Find pages that have been modified today (since midnight), with pagination and sorting options.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | The maximum number of pages to retrieve (default: 50). Use -1 for no limit, but be aware that very large result sets can impact performance. | |
| offset | No | The number of pages to skip before returning matches. Useful for pagination. Defaults to 0. | |
| sort_order | No | Sort order for pages based on modification date. "desc" for most recent first, "asc" for oldest first. | desc |
Implementation Reference
- src/tools/operations/pages.ts:27-95 (handler)The main handler function that executes the tool logic: queries the Roam graph using Datomic for pages with blocks modified since midnight today, handles pagination and sorting, extracts unique page titles, and returns formatted results.async findPagesModifiedToday(limit: number = 50, offset: number = 0, sort_order: 'asc' | 'desc' = 'desc') { // Define ancestor rule for traversing block hierarchy const ancestorRule = `[ [ (ancestor ?b ?a) [?a :block/children ?b] ] [ (ancestor ?b ?a) [?parent :block/children ?b] (ancestor ?parent ?a) ] ]`; // Get start of today const startOfDay = new Date(); startOfDay.setHours(0, 0, 0, 0); try { // Query for pages modified today, including modification time for sorting let query = `[:find ?title ?time :in $ ?start_of_day % :where [?page :node/title ?title] (ancestor ?block ?page) [?block :edit/time ?time] [(> ?time ?start_of_day)]]`; if (limit !== -1) { query += ` :limit ${limit}`; } if (offset > 0) { query += ` :offset ${offset}`; } const results = await q( this.graph, query, [startOfDay.getTime(), ancestorRule] ) as [string, number][]; if (!results || results.length === 0) { return { success: true, pages: [], message: 'No pages have been modified today' }; } // Sort results by modification time results.sort((a, b) => { if (sort_order === 'desc') { return b[1] - a[1]; // Newest first } else { return a[1] - b[1]; // Oldest first } }); // Extract unique page titles from sorted results const uniquePages = Array.from(new Set(results.map(([title]) => title))); return { success: true, pages: uniquePages, message: `Found ${uniquePages.length} page(s) modified today` }; } catch (error: any) { throw new McpError( ErrorCode.InternalError, `Failed to find modified pages: ${error.message}` ); } }
- src/server/roam-server.ts:271-279 (registration)Tool registration in the MCP server switch statement: matches the tool name via BASE_TOOL_NAMES.FIND_PAGES_MODIFIED_TODAY, extracts parameters, calls the handler, and formats the response.case BASE_TOOL_NAMES.FIND_PAGES_MODIFIED_TODAY: { const { max_num_pages } = request.params.arguments as { max_num_pages?: number; }; const result = await this.toolHandlers.findPagesModifiedToday(max_num_pages || 50); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
- src/tools/schemas.ts:314-338 (schema)Defines the tool name, description, and input schema (parameters: limit, offset, sort_order with defaults).[toolName(BASE_TOOL_NAMES.FIND_PAGES_MODIFIED_TODAY)]: { name: toolName(BASE_TOOL_NAMES.FIND_PAGES_MODIFIED_TODAY), description: 'Find pages that have been modified today (since midnight), with pagination and sorting options.', inputSchema: { type: 'object', properties: { limit: { type: 'integer', description: 'The maximum number of pages to retrieve (default: 50). Use -1 for no limit, but be aware that very large result sets can impact performance.', default: 50 }, offset: { type: 'integer', description: 'The number of pages to skip before returning matches. Useful for pagination. Defaults to 0.', default: 0 }, sort_order: { type: 'string', description: 'Sort order for pages based on modification date. "desc" for most recent first, "asc" for oldest first.', enum: ['asc', 'desc'], default: 'desc' } } } },