rekordbox-mcp

Instructions

Implementation Reference

• rekordbox_mcp/server.py:131-148 (handler)

  The @mcp.tool()-decorated async function that serves as both the registration and handler for the get_tracks_by_bpm_range tool. It constructs SearchOptions with the provided BPM range, queries the database, and returns matching tracks.
  @mcp.tool() async def get_tracks_by_bpm_range(bpm_min: float, bpm_max: float) -> List[Dict[str, Any]]: """ Get tracks within a specific BPM range. Args: bpm_min: Minimum BPM bpm_max: Maximum BPM Returns: List of tracks within the BPM range """ if not db: raise RuntimeError("Database not initialized.") search_options = SearchOptions(bpm_min=bpm_min, bpm_max=bpm_max, limit=1000) tracks = await db.search_tracks(search_options) return [track.model_dump() for track in tracks]
• rekordbox_mcp/models.py:151-184 (schema)

  Pydantic BaseModel defining SearchOptions with bpm_min and bpm_max fields, including custom validator ensuring bpm_max > bpm_min. Used internally by the tool handler for structured input.
  class SearchOptions(BaseModel): """ Search criteria for track queries. """ query: str = Field("", description="General search query") artist: Optional[str] = Field(None, description="Filter by artist name") title: Optional[str] = Field(None, description="Filter by track title") album: Optional[str] = Field(None, description="Filter by album name") genre: Optional[str] = Field(None, description="Filter by genre") key: Optional[str] = Field(None, description="Filter by musical key") bpm_min: Optional[float] = Field(None, ge=0, description="Minimum BPM") bpm_max: Optional[float] = Field(None, ge=0, description="Maximum BPM") rating_min: Optional[int] = Field(None, ge=0, le=5, description="Minimum rating") rating_max: Optional[int] = Field(None, ge=0, le=5, description="Maximum rating") play_count_min: Optional[int] = Field(None, ge=0, description="Minimum play count") play_count_max: Optional[int] = Field(None, ge=0, description="Maximum play count") limit: int = Field(50, ge=1, le=1000, description="Maximum number of results") @field_validator('bpm_max') @classmethod def validate_bpm_range(cls, v, info): """Ensure bpm_max is greater than bpm_min.""" if v and info.data.get('bpm_min') and v < info.data['bpm_min']: raise ValueError('bpm_max must be greater than bpm_min') return v @field_validator('rating_max') @classmethod def validate_rating_range(cls, v, info): """Ensure rating_max is greater than rating_min.""" if v and info.data.get('rating_min') and v < info.data['rating_min']: raise ValueError('rating_max must be greater than rating_min') return v
• rekordbox_mcp/database.py:115-181 (helper)

  Core helper method in RekordboxDatabase that performs the actual track filtering by BPM range (normalizing BPM by /100, comparing against options.bpm_min/max), applies other filters, limits results, and converts to Track models. Called by the tool handler.
  async def search_tracks(self, options: SearchOptions) -> List[Track]: """ Search for tracks based on the provided options. Args: options: Search criteria and filters Returns: List of matching tracks """ if not self.db: raise RuntimeError("Database not connected") # Get all content from database, filtering out soft-deleted tracks all_content = list(self.db.get_content()) active_content = [c for c in all_content if getattr(c, 'rb_local_deleted', 0) == 0] # Apply filters filtered_tracks = [] for content in active_content: # Get extracted field values for filtering artist_name = getattr(content, 'ArtistName', '') or "" genre_name = getattr(content, 'GenreName', '') or "" key_name = getattr(content, 'KeyName', '') or "" bpm_value = (getattr(content, 'BPM', 0) or 0) / 100.0 rating_value = getattr(content, 'Rating', 0) or 0 # Apply text-based filters if options.query and not any([ options.query.lower() in str(content.Title or "").lower(), options.query.lower() in artist_name.lower(), options.query.lower() in genre_name.lower(), ]): continue if options.artist and options.artist.lower() not in artist_name.lower(): continue if options.title and options.title.lower() not in str(content.Title or "").lower(): continue if options.genre and options.genre.lower() not in genre_name.lower(): continue if options.key and options.key != key_name: continue # Apply numeric filters if options.bpm_min and bpm_value < options.bpm_min: continue if options.bpm_max and bpm_value > options.bpm_max: continue if options.rating_min and rating_value < options.rating_min: continue # Convert to our Track model track = self._content_to_track(content) filtered_tracks.append(track) # Apply limit if len(filtered_tracks) >= options.limit: break return filtered_tracks