zk_list_notes_by_date

Filter and retrieve notes from a Zettelkasten system within a specified date range. Supports searching by creation or update dates and allows limiting results for efficient note organization.

Instructions

List notes created or updated within a date range. Args: start_date: Start date in ISO format (YYYY-MM-DD) end_date: End date in ISO format (YYYY-MM-DD) use_updated: Whether to use updated_at instead of created_at limit: Maximum number of results to return

Input Schema

TableJSON Schema

Name	Required	Description	Default
`end_date`	No
`limit`	No
`start_date`	No
`use_updated`	No

Implementation Reference

src/zettelkasten_mcp/server/mcp_server.py:692-766 (handler)

Main handler function implementing the zk_list_notes_by_date tool logic: parses input dates, queries search_service for notes in range, applies limit, formats and returns a detailed list.

def zk_list_notes_by_date(
    start_date: str | None = None,
    end_date: str | None = None,
    use_updated: bool = False,
    limit: int = 10,
) -> str:
    """List notes created or modified within a specific date range.

    Args:
        start_date: Start of date range in ISO format YYYY-MM-DD (optional, defaults to earliest)
        end_date: End of date range in ISO format YYYY-MM-DD (optional, defaults to latest)
        use_updated: If true, filter by modification date instead of creation date (default: false)
        limit: Maximum number of results to return (default: 10)
    """
    try:
        # Parse dates
        start_datetime = None
        if start_date:
            start_datetime = datetime.fromisoformat(f"{start_date}T00:00:00")
        end_datetime = None
        if end_date:
            end_datetime = datetime.fromisoformat(f"{end_date}T23:59:59")

        # Get notes
        notes = self.search_service.find_notes_by_date_range(
            start_date=start_datetime,
            end_date=end_datetime,
            use_updated=use_updated,
        )

        # Limit results
        notes = notes[:limit]
        if not notes:
            date_type = "updated" if use_updated else "created"
            date_range = ""
            if start_date and end_date:
                date_range = f" between {start_date} and {end_date}"
            elif start_date:
                date_range = f" after {start_date}"
            elif end_date:
                date_range = f" before {end_date}"
            return f"No notes found {date_type}{date_range}."

        # Format results
        date_type = "updated" if use_updated else "created"
        output = f"Notes {date_type}"
        if start_date or end_date:
            if start_date and end_date:
                output += f" between {start_date} and {end_date}"
            elif start_date:
                output += f" after {start_date}"
            elif end_date:
                output += f" before {end_date}"
        output += f" (showing {len(notes)} results):\n\n"
        for i, note in enumerate(notes, 1):
            date = note.updated_at if use_updated else note.created_at
            output += f"{i}. {note.title} (ID: {note.id})\n"
            output += f"   {date_type.capitalize()}: {date.strftime('%Y-%m-%d %H:%M')}\n"
            if note.tags:
                output += (
                    f"   Tags: {', '.join(tag.name for tag in note.tags)}\n"
                )
            # Add a snippet of content (first 100 chars)
            content_preview = note.content[:100].replace("\n", " ")
            if len(note.content) > 100:
                content_preview += "..."
            output += f"   Preview: {content_preview}\n\n"
        return output
    except ValueError as e:
        # Special handling for date parsing errors
        logger.error(f"Date parsing error: {str(e)}")
        return f"Error parsing date: {str(e)}"
    except Exception as e:
        return self.format_error_response(e)

src/zettelkasten_mcp/server/mcp_server.py:683-691 (registration)

MCP tool registration decorator defining the tool name, description, and annotations indicating it's read-only and idempotent.

@self.mcp.tool(
    name="zk_list_notes_by_date",
    description="List notes created or modified within a specific date range.",
    annotations={
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
    },
)

src/zettelkasten_mcp/services/search_service.py:204-232 (helper)

Supporting helper method in SearchService that filters and sorts all notes by creation or update date within the given range.

def find_notes_by_date_range(
    self,
    start_date: Optional[datetime] = None,
    end_date: Optional[datetime] = None,
    use_updated: bool = False
) -> List[Note]:
    """Find notes created or updated within a date range."""
    all_notes = self.zettel_service.get_all_notes()
    matching_notes = []
    
    for note in all_notes:
        # Get the relevant date
        date = note.updated_at if use_updated else note.created_at
        
        # Check if in range
        if start_date and date < start_date:
            continue
        if end_date and date >= end_date + datetime.timedelta(seconds=1):
            continue
        
        matching_notes.append(note)
    
    # Sort by date (descending)
    matching_notes.sort(
        key=lambda x: x.updated_at if use_updated else x.created_at,
        reverse=True
    )
    
    return matching_notes

src/zettelkasten_mcp/server/mcp_server.py:692-697 (schema)

Input schema defined by function parameters with type annotations and defaults, output str.

def zk_list_notes_by_date(
    start_date: str | None = None,
    end_date: str | None = None,
    use_updated: bool = False,
    limit: int = 10,
) -> str:

zettelkasten-mcp