roam_find_pages_modified_today

Instructions

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'
        }
      }
    }
  },