roam_search_by_date

Instructions

Implementation Reference

• src/tools/operations/search/index.ts:97-152 (handler)

  Core handler function that implements the 'roam_search_by_date' tool logic: converts date range to timestamps, fetches all blocks via text search with empty query, filters by date (using placeholder logic), maps and sorts results.

  async searchByDate(params: {
    start_date: string;
    end_date?: string;
    type: 'created' | 'modified' | 'both';
    scope: 'blocks' | 'pages' | 'both';
    include_content: boolean;
  }): Promise<{ 
    success: boolean; 
    matches: Array<{ 
      uid: string; 
      type: string; 
      time: number; 
      content?: string; 
      page_title?: string 
    }>; 
    message: string 
  }> {
    // Convert dates to timestamps
    const startTimestamp = new Date(`${params.start_date}T00:00:00`).getTime();
    const endTimestamp = params.end_date ? new Date(`${params.end_date}T23:59:59`).getTime() : undefined;
  
    // Use text search handler for content-based filtering
    const handler = new TextSearchHandlerImpl(this.graph, {
      text: '', // Empty text to match all blocks
    });
  
    const result = await handler.execute();
  
    // Filter results by date
    const matches = result.matches
      .filter(match => {
        const time = params.type === 'created' ? 
          new Date(match.content || '').getTime() : // Use content date for creation time
          Date.now(); // Use current time for modification time (simplified)
        
        return time >= startTimestamp && (!endTimestamp || time <= endTimestamp);
      })
      .map(match => ({
        uid: match.block_uid,
        type: 'block',
        time: params.type === 'created' ? 
          new Date(match.content || '').getTime() : 
          Date.now(),
        ...(params.include_content && { content: match.content }),
        page_title: match.page_title
      }));
  
    // Sort by time
    const sortedMatches = matches.sort((a, b) => b.time - a.time);
  
    return {
      success: true,
      matches: sortedMatches,
      message: `Found ${sortedMatches.length} matches for the given date range and criteria`
    };
  }

• src/tools/tool-handlers.ts:93-100 (handler)

  Delegating handler method in ToolHandlers class that forwards the tool call to SearchOperations.searchByDate.

  async searchByDate(params: {
    start_date: string;
    end_date?: string;
    type: 'created' | 'modified' | 'both';
    scope: 'blocks' | 'pages' | 'both';
    include_content: boolean;
  }) {
    return this.searchOps.searchByDate(params);

• src/tools/schemas.ts:372-404 (schema)

  Input schema definition for the 'roam_search_by_date' tool, including parameters for date range, type, scope, and content inclusion.

  [toolName(BASE_TOOL_NAMES.SEARCH_BY_DATE)]: {
    name: toolName(BASE_TOOL_NAMES.SEARCH_BY_DATE),
    description: 'Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.',
    inputSchema: {
      type: 'object',
      properties: {
        start_date: {
          type: 'string',
          description: 'Start date in ISO format (YYYY-MM-DD)',
        },
        end_date: {
          type: 'string',
          description: 'Optional: End date in ISO format (YYYY-MM-DD)',
        },
        type: {
          type: 'string',
          enum: ['created', 'modified', 'both'],
          description: 'Whether to search by creation date, modification date, or both',
        },
        scope: {
          type: 'string',
          enum: ['blocks', 'pages', 'both'],
          description: 'Whether to search blocks, pages',
        },
        include_content: {
          type: 'boolean',
          description: 'Whether to include the content of matching blocks/pages',
          default: true,
        }
      },
      required: ['start_date', 'type', 'scope']
    }
  },

• src/server/roam-server.ts:292-304 (registration)

  Tool registration in the MCP server request handler: switch case that handles calls to 'roam_search_by_date' by invoking ToolHandlers.searchByDate and returning JSON result.

  case BASE_TOOL_NAMES.SEARCH_BY_DATE: {
    const params = request.params.arguments as {
      start_date: string;
      end_date?: string;
      type: 'created' | 'modified' | 'both';
      scope: 'blocks' | 'pages' | 'both';
      include_content: boolean;
    };
    const result = await this.toolHandlers.searchByDate(params);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/server/roam-server.ts:90-92 (registration)

  Registers all tools (including 'roam_search_by_date') for listing via MCP ListToolsRequest.

  mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: Object.values(toolSchemas),
  }));