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()