rekordbox-mcp

Instructions

Implementation Reference

• rekordbox_mcp/server.py:435-447 (handler)

  MCP tool handler for 'get_history_stats': ensures database connection, calls RekordboxDatabase.get_history_stats(), and serializes the result to a dictionary.
  @mcp.tool() async def get_history_stats() -> Dict[str, Any]: """ Get comprehensive statistics about DJ history sessions. Returns: Statistics about all history sessions including totals and trends """ await ensure_database_connected() stats = await db.get_history_stats() return stats.model_dump()
• rekordbox_mcp/database.py:667-714 (handler)

  Core implementation of history statistics computation: aggregates data from history sessions including totals, hours played, monthly breakdown, and averages.
  async def get_history_stats(self) -> HistoryStats: """ Get comprehensive statistics about DJ history sessions. Returns: Statistics about all history sessions """ if not self.db: raise RuntimeError("Database not connected") try: # Get all sessions (not folders) sessions = await self.get_history_sessions(include_folders=False) # Calculate basic stats total_sessions = len(sessions) total_tracks_played = sum(s.track_count for s in sessions) total_minutes = sum(s.duration_minutes for s in sessions if s.duration_minutes) total_hours_played = total_minutes / 60 if total_minutes > 0 else 0.0 avg_session_length = total_minutes / total_sessions if total_sessions > 0 else 0.0 # Group sessions by month sessions_by_month = {} for session in sessions: if session.date_created: try: # Extract year-month from date string date_part = session.date_created[:7] # "2025-08" sessions_by_month[date_part] = sessions_by_month.get(date_part, 0) + 1 except: pass # For more detailed stats, we'd need to analyze all tracks # This is a basic implementation return HistoryStats( total_sessions=total_sessions, total_tracks_played=total_tracks_played, total_hours_played=round(total_hours_played, 1), sessions_by_month=sessions_by_month, avg_session_length=round(avg_session_length, 1), favorite_genres=[], # Would require analyzing all session tracks most_played_track=None # Would require counting track occurrences ) except Exception as e: logger.error(f"Failed to get history stats: {e}") return HistoryStats()
• rekordbox_mcp/models.py:137-149 (schema)

  Pydantic schema defining the HistoryStats model used for input/output validation and type safety in the get_history_stats tool.
  class HistoryStats(BaseModel): """ Statistics about DJ history sessions. """ total_sessions: int = Field(0, ge=0, description="Total number of sessions") total_tracks_played: int = Field(0, ge=0, description="Total tracks across all sessions") total_hours_played: float = Field(0.0, ge=0, description="Total hours of DJ sets") most_played_track: Optional[Dict[str, Any]] = Field(None, description="Most played track across sessions") favorite_genres: List[Dict[str, Any]] = Field(default_factory=list, description="Top genres by play count") sessions_by_month: Dict[str, int] = Field(default_factory=dict, description="Sessions grouped by month") avg_session_length: float = Field(0.0, ge=0, description="Average session length in minutes")
• rekordbox_mcp/server.py:435-435 (registration)

  FastMCP tool registration decorator that registers the get_history_stats function as an MCP tool.
  @mcp.tool()