zettelkasten-mcp

Instructions

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: