Search the Soulseek network for files.

Filters (applied post-search, like Nicotine+/sldl/Soularr):

• extensions: only return files with these extensions (e.g. ["flac","mp3"])

• min_bitrate: minimum bitrate in kbps (files with unknown bitrate are kept)

• min_filesize / max_filesize: file size bounds in bytes

• free_slots_only: only return results from peers with free upload slots

• max_queue_size: skip peers with queue larger than this (Soularr default: 50)

• min_speed: minimum peer upload speed in bytes/sec

Download a file from a Soulseek peer.

Files are saved to the directory configured by SLSK_DOWNLOAD_DIR.

IMPORTANT: After calling this, SLEEP for at least 30 seconds (or do other productive work) before calling download_status. P2P connections take time to establish — the peer must accept, negotiate, and begin sending data. Checking immediately wastes tokens and will always show 0%.

The response includes wait_before_poll_secs — you MUST sleep/wait that many seconds before your first status poll. Do not live-poll in a loop.

Poll progress of an active or recent download.

CRITICAL TIMING RULES:

• Do NOT call this within 30 seconds of starting a download.

• status='queued' at 0% is NORMAL for the first 1-2 minutes. P2P takes time.

• Do NOT cancel a download just because it shows queued/0%. Check age_seconds.

• Only consider cancelling if age_seconds > 180 (3 minutes) with no progress.

• The 'message' field contains contextual guidance — READ IT and follow its sleep recommendation before polling again. Do NOT live-poll in a tight loop.

• If status='not_found' or status='session_expired', the download ID is stale (server restarted). You must re-search and re-download.

Abort an in-progress download.

ONLY cancel a download if:

• download_status shows age_seconds > 180 AND status is still 'queued' (stuck)

• download_status shows status='failed'

• You explicitly want to switch to a different peer

Do NOT cancel just because progress is 0% — P2P connections take 1-3 minutes.

List all active/queued/recent downloads in the current session.

Use this to recover state after context compaction or session resume. Returns all tracked downloads with their current status, progress, age_seconds, username, connection_state, and local_path.

Each entry includes the download ID so you can call download_status or cancel_download on specific items.

Check the MCP's Soulseek connection health before starting work.

Call this at the start of every session and after any suspected restart. Returns: connected, passive_mode, session_id, listening_port, p2p_reachable, session_uptime_secs, active_downloads, and a note if something needs attention.

Key fields:

• session_id: increments on each login. If it changed since your last check, all previous download IDs are invalid — re-search and re-download.

• p2p_reachable: false means downloads will likely fail (double-NAT). Warn the user and suggest configuring SLSK_LISTEN_PORT + port forwarding.

• passive_mode: true means no listening port bound. Same implication as above.

Return the MCP's runtime configuration (no secrets).

Use this to check where files are being downloaded, which ports are configured, concurrency limits, and the connected username.

Check a peer's online status, speed, queue, and free slots before downloading.