rekordbox-mcp

Instructions

Implementation Reference

• rekordbox_mcp/server.py:405-432 (handler)

  The core handler function for the 'get_recent_sessions' MCP tool. It filters DJ history sessions from the database to return only those within the specified number of days back, sorts them by recency, and serializes using model_dump().
  @mcp.tool() async def get_recent_sessions(days: int = 30) -> List[Dict[str, Any]]: """ Get recent DJ history sessions within the specified number of days. Args: days: Number of days to look back (default: 30) Returns: List of recent history sessions """ await ensure_database_connected() from datetime import datetime, timedelta cutoff_date = datetime.now() - timedelta(days=days) cutoff_str = cutoff_date.strftime("%Y-%m-%d") sessions = await db.get_history_sessions(include_folders=False) # Filter by date recent_sessions = [ s for s in sessions if s.date_created and s.date_created >= cutoff_str ] # Sort by date, most recent first recent_sessions.sort(key=lambda x: x.date_created or "", reverse=True) return [session.model_dump() for session in recent_sessions]
• rekordbox_mcp/models.py:94-114 (schema)

  Pydantic BaseModel for HistorySession, defining the structure and validation for output objects returned by the get_recent_sessions tool.
  class HistorySession(BaseModel): """ Rekordbox DJ history session model. """ id: str = Field(..., description="Unique history session identifier") name: str = Field(..., description="Session name (usually date)") parent_id: Optional[str] = Field(None, description="Parent folder ID") is_folder: bool = Field(False, description="Whether this is a folder") date_created: Optional[str] = Field(None, description="Date session was created") track_count: int = Field(0, ge=0, description="Number of tracks in session") duration_minutes: Optional[int] = Field(None, description="Total session duration in minutes") @field_validator('date_created', mode='before') @classmethod def validate_date(cls, v): """Convert datetime objects to strings.""" if hasattr(v, 'strftime'): # datetime object return v.strftime("%Y-%m-%d %H:%M:%S") return str(v) if v is not None else None
• rekordbox_mcp/database.py:540-604 (helper)

  Supporting database method that retrieves all DJ history sessions (folders optional), calculates track counts and durations, and constructs HistorySession objects. Called by the get_recent_sessions tool.
  async def get_history_sessions(self, include_folders: bool = False) -> List[HistorySession]: """ Get all DJ history sessions from the database. Args: include_folders: Whether to include folder entries Returns: List of history sessions """ if not self.db: raise RuntimeError("Database not connected") try: # Get all histories, filtering out soft-deleted ones all_histories = list(self.db.get_history()) active_histories = [h for h in all_histories if getattr(h, 'rb_local_deleted', 0) == 0] sessions = [] for history in active_histories: # Filter by type: Attribute 1 = folder, Attribute 0 = session is_folder = history.Attribute == 1 if not include_folders and is_folder: continue # Get track count for sessions track_count = 0 duration_minutes = None if not is_folder: try: history_songs = list(self.db.get_history_songs(HistoryID=history.ID)) active_songs = [s for s in history_songs if getattr(s, 'rb_local_deleted', 0) == 0] track_count = len(active_songs) # Calculate duration if we have tracks if active_songs: all_content = list(self.db.get_content()) content_lookup = {str(c.ID): c for c in all_content if getattr(c, 'rb_local_deleted', 0) == 0} total_seconds = 0 for song in active_songs: content_id = str(song.ContentID) if content_id in content_lookup: track_length = getattr(content_lookup[content_id], 'Length', 0) or 0 total_seconds += track_length duration_minutes = round(total_seconds / 60) if total_seconds > 0 else None except Exception: track_count = 0 sessions.append(HistorySession( id=str(history.ID), name=history.Name or "", parent_id=str(history.ParentID) if history.ParentID and history.ParentID != "root" else None, is_folder=is_folder, date_created=history.DateCreated, track_count=track_count, duration_minutes=duration_minutes )) return sessions except Exception as e: logger.error(f"Failed to get history sessions: {e}") return []