rekordbox-mcp

Instructions

Implementation Reference

• rekordbox_mcp/server.py:169-184 (handler)

  The MCP tool handler for 'get_top_rated_tracks', decorated with @mcp.tool() for registration. It checks database connection, calls the database helper method, and returns list of track dictionaries.

  @mcp.tool()
  async def get_top_rated_tracks(limit: int = 20) -> List[Dict[str, Any]]:
      """
      Get the highest rated tracks in the library.
      
      Args:
          limit: Maximum number of tracks to return
          
      Returns:
          List of top rated tracks
      """
      if not db:
          raise RuntimeError("Database not initialized.")
      
      tracks = await db.get_top_rated_tracks(limit)
      return [track.model_dump() for track in tracks]

• rekordbox_mcp/database.py:322-332 (helper)

  Core implementation logic in RekordboxDatabase class: fetches all active tracks, sorts by rating (desc) then play count, limits to top N, converts to Track models.

  async def get_top_rated_tracks(self, limit: int = 20) -> List[Track]:
      """Get the highest rated tracks."""
      if not self.db:
          raise RuntimeError("Database not connected")
      
      all_content = list(self.db.get_content())
      active_content = [c for c in all_content if getattr(c, 'rb_local_deleted', 0) == 0]
      # Sort by rating descending, then by play count
      sorted_content = sorted(active_content, key=lambda x: (getattr(x, 'Rating', 0) or 0, getattr(x, 'DJPlayCount', 0) or 0), reverse=True)
      
      return [self._content_to_track(content) for content in sorted_content[:limit]]

• rekordbox_mcp/models.py:13-55 (schema)

  Pydantic BaseModel defining the Track schema used for output structures (converted to dicts via model_dump()). Defines all track metadata fields with validation.

  class Track(BaseModel):
      """
      Rekordbox track model with comprehensive metadata.
      """
      
      id: str = Field(..., description="Unique track identifier")
      title: str = Field(..., description="Track title")
      artist: str = Field(..., description="Track artist")
      album: Optional[str] = Field(None, description="Album name")
      genre: Optional[str] = Field(None, description="Musical genre")
      bpm: float = Field(0.0, description="Beats per minute")
      key: Optional[str] = Field(None, description="Musical key (e.g., '5A', '12B')")
      rating: int = Field(0, ge=0, le=5, description="Track rating (0-5)")
      play_count: int = Field(0, ge=0, description="Number of times played")
      length: int = Field(0, ge=0, description="Track length in seconds")
      file_path: Optional[str] = Field(None, description="Path to audio file")
      date_added: Optional[str] = Field(None, description="Date track was added to library")
      date_modified: Optional[str] = Field(None, description="Date track was last modified")
      
      # Additional metadata
      bitrate: Optional[int] = Field(None, description="Audio bitrate in kbps")
      sample_rate: Optional[int] = Field(None, description="Audio sample rate in Hz")
      color: Optional[str] = Field(None, description="Track color tag")
      comments: Optional[str] = Field(None, description="Track comments")
      
      @field_validator('key')
      @classmethod
      def validate_key(cls, v):
          """Validate musical key format."""
          if v and v not in []:  # Add valid key formats
              # Basic validation - could be more sophisticated
              pass
          return v
      
      def duration_formatted(self) -> str:
          """Get track duration in MM:SS format."""
          if self.length <= 0:
              return "0:00"
          
          minutes = self.length // 60
          seconds = self.length % 60
          return f"{minutes}:{seconds:02d}"