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
- 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, }, )
- 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
- 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: