089e74e6a7
Part of the Tail Family. Four tools:
- musictail_suggest: mood-filtered recs from top tracks
- musictail_discover_artist: find similar artists
- musictail_taste_profile: analyze listening patterns
- musictail_fresh_finds: discovery with adventure dial
Author: Vivienne Rousseau 🦊
311 lines
11 KiB
Python
311 lines
11 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
MusicTail — Vixy's Music Discovery MCP 🎵🦊
|
|
Part of the Tail Family.
|
|
|
|
Provides intelligent music discovery and taste analysis
|
|
using Spotify's recommendation engine seeded with actual listening history.
|
|
|
|
Author: Vivienne Rousseau
|
|
Created: Day 156 (April 6, 2026)
|
|
"""
|
|
|
|
from mcp.server.fastmcp import FastMCP
|
|
from pydantic import BaseModel, Field, ConfigDict
|
|
from typing import Optional, List
|
|
from enum import Enum
|
|
import os
|
|
import json
|
|
|
|
import spotipy
|
|
from spotipy.oauth2 import SpotifyOAuth
|
|
|
|
# Initialize MCP server
|
|
mcp = FastMCP("musictail")
|
|
|
|
# Spotify scopes needed
|
|
SCOPES = "user-top-read user-read-recently-played user-library-read"
|
|
|
|
def get_spotify_client() -> spotipy.Spotify:
|
|
"""Create authenticated Spotify client."""
|
|
cache_path = os.path.expanduser("~/.musictail_cache")
|
|
auth_manager = SpotifyOAuth(
|
|
client_id=os.environ.get("SPOTIFY_CLIENT_ID"),
|
|
client_secret=os.environ.get("SPOTIFY_CLIENT_SECRET"),
|
|
redirect_uri="http://127.0.0.1:8889/callback",
|
|
scope=SCOPES,
|
|
cache_path=cache_path,
|
|
open_browser=True
|
|
)
|
|
return spotipy.Spotify(auth_manager=auth_manager)
|
|
|
|
|
|
# ========== Models ==========
|
|
|
|
class MoodEnum(str, Enum):
|
|
"""Mood categories mapped to audio features."""
|
|
CHILL = "chill"
|
|
ENERGETIC = "energetic"
|
|
MELANCHOLY = "melancholy"
|
|
FOCUSED = "focused"
|
|
DREAMY = "dreamy"
|
|
DARK = "dark"
|
|
UPLIFTING = "uplifting"
|
|
INTENSE = "intense"
|
|
|
|
# Mood to Spotify audio feature mapping
|
|
MOOD_FEATURES = {
|
|
"chill": {"max_energy": 0.5, "max_tempo": 110, "min_valence": 0.3},
|
|
"energetic": {"min_energy": 0.7, "min_tempo": 120, "min_valence": 0.5},
|
|
"melancholy": {"max_energy": 0.4, "max_valence": 0.3, "max_tempo": 100},
|
|
"focused": {"min_energy": 0.3, "max_energy": 0.7, "max_speechiness": 0.1},
|
|
"dreamy": {"max_energy": 0.5, "max_tempo": 110, "min_instrumentalness": 0.5},
|
|
"dark": {"max_valence": 0.3, "min_energy": 0.4},
|
|
"uplifting": {"min_valence": 0.6, "min_energy": 0.5},
|
|
"intense": {"min_energy": 0.8, "min_tempo": 130},
|
|
}
|
|
|
|
class SuggestInput(BaseModel):
|
|
"""Input for music suggestions."""
|
|
model_config = ConfigDict(extra='forbid')
|
|
mood: Optional[MoodEnum] = Field(
|
|
default=None,
|
|
description="Mood filter: chill, energetic, melancholy, focused, dreamy, dark, uplifting, intense"
|
|
)
|
|
count: int = Field(
|
|
default=10,
|
|
description="Number of tracks to suggest (1-50)",
|
|
ge=1, le=50
|
|
)
|
|
class DiscoverInput(BaseModel):
|
|
"""Input for artist discovery."""
|
|
model_config = ConfigDict(extra='forbid')
|
|
artist_name: str = Field(description="Artist name to find similar artists for")
|
|
count: int = Field(default=5, description="Number of similar artists (1-20)", ge=1, le=20)
|
|
|
|
class TasteInput(BaseModel):
|
|
"""Input for taste profile."""
|
|
model_config = ConfigDict(extra='forbid')
|
|
time_range: str = Field(
|
|
default="short_term",
|
|
description="Time range: short_term (~4 weeks), medium_term (~6 months), long_term (years)"
|
|
)
|
|
|
|
class FreshFindsInput(BaseModel):
|
|
"""Input for fresh discoveries based on recent listening."""
|
|
model_config = ConfigDict(extra='forbid')
|
|
count: int = Field(default=10, description="Number of tracks (1-50)", ge=1, le=50)
|
|
adventurous: bool = Field(
|
|
default=False,
|
|
description="If true, push further from comfort zone"
|
|
)
|
|
|
|
|
|
# ========== Tools ==========
|
|
|
|
@mcp.tool(
|
|
name="musictail_suggest",
|
|
annotations={
|
|
"title": "Suggest Music By Mood",
|
|
"readOnlyHint": True,
|
|
"destructiveHint": False,
|
|
}
|
|
)
|
|
async def suggest_music(params: SuggestInput) -> str:
|
|
"""
|
|
Suggest music based on your recent listening history and optional mood filter.
|
|
Automatically seeds from your top tracks — no manual input needed.
|
|
"""
|
|
sp = get_spotify_client()
|
|
# Get top tracks as seeds (mix of recent and medium-term)
|
|
top_short = sp.current_user_top_tracks(limit=5, time_range="short_term")
|
|
top_medium = sp.current_user_top_tracks(limit=5, time_range="medium_term")
|
|
|
|
seed_ids = []
|
|
for t in (top_short["items"][:3] + top_medium["items"][:2]):
|
|
if t["id"] not in seed_ids:
|
|
seed_ids.append(t["id"])
|
|
seed_ids = seed_ids[:5] # Spotify max 5 seeds
|
|
|
|
# Build recommendation kwargs
|
|
kwargs = {"seed_tracks": seed_ids, "limit": params.count}
|
|
if params.mood and params.mood.value in MOOD_FEATURES:
|
|
kwargs.update(MOOD_FEATURES[params.mood.value])
|
|
|
|
results = sp.recommendations(**kwargs)
|
|
|
|
lines = [f"🎵 **MusicTail Suggestions**" + (f" — mood: {params.mood.value}" if params.mood else "")]
|
|
lines.append(f"Seeded from your top tracks\n")
|
|
|
|
for i, track in enumerate(results["tracks"], 1):
|
|
artists = ", ".join(a["name"] for a in track["artists"])
|
|
album = track["album"]["name"]
|
|
tid = track["id"]
|
|
lines.append(f"{i}. **{track['name']}** — {artists}")
|
|
lines.append(f" Album: {album} | ID: `{tid}`")
|
|
|
|
return "\n".join(lines)
|
|
|
|
@mcp.tool(
|
|
name="musictail_discover_artist",
|
|
annotations={
|
|
"title": "Discover Similar Artists",
|
|
"readOnlyHint": True,
|
|
"destructiveHint": False,
|
|
}
|
|
)
|
|
async def discover_artist(params: DiscoverInput) -> str:
|
|
"""
|
|
Find artists similar to one you like, with their top tracks.
|
|
Great for expanding from known favorites into new territory.
|
|
"""
|
|
sp = get_spotify_client()
|
|
|
|
# Search for the artist
|
|
search = sp.search(q=params.artist_name, type="artist", limit=1)
|
|
if not search["artists"]["items"]:
|
|
return f"Could not find artist: {params.artist_name}"
|
|
|
|
artist = search["artists"]["items"][0]
|
|
artist_id = artist["id"]
|
|
genres = ", ".join(artist.get("genres", [])[:5]) or "no genres listed"
|
|
|
|
# Get related artists
|
|
related = sp.artist_related_artists(artist_id)
|
|
similar = related["artists"][:params.count]
|
|
|
|
lines = [f"🔍 **Artists similar to {artist['name']}**"]
|
|
lines.append(f"Genres: {genres}\n")
|
|
for i, sim in enumerate(similar, 1):
|
|
sim_genres = ", ".join(sim.get("genres", [])[:3]) or "—"
|
|
popularity = sim.get("popularity", 0)
|
|
|
|
# Get top tracks for this artist
|
|
top = sp.artist_top_tracks(sim["id"])
|
|
top_tracks = top["tracks"][:3]
|
|
track_list = "; ".join(t["name"] for t in top_tracks)
|
|
|
|
lines.append(f"{i}. **{sim['name']}** (popularity: {popularity})")
|
|
lines.append(f" Genres: {sim_genres}")
|
|
lines.append(f" Top tracks: {track_list}")
|
|
if top_tracks:
|
|
lines.append(f" Play ID: `{top_tracks[0]['id']}`")
|
|
lines.append("")
|
|
|
|
return "\n".join(lines)
|
|
|
|
|
|
@mcp.tool(
|
|
name="musictail_taste_profile",
|
|
annotations={
|
|
"title": "Analyze Taste Profile",
|
|
"readOnlyHint": True,
|
|
"destructiveHint": False,
|
|
}
|
|
)
|
|
async def taste_profile(params: TasteInput) -> str:
|
|
"""
|
|
Analyze your listening patterns across time. Shows top artists, top genres, and musical characteristics for the selected time range.
|
|
"""
|
|
sp = get_spotify_client()
|
|
|
|
range_label = {
|
|
"short_term": "Last ~4 weeks",
|
|
"medium_term": "Last ~6 months",
|
|
"long_term": "All time"
|
|
}.get(params.time_range, params.time_range)
|
|
|
|
# Top artists
|
|
top_artists = sp.current_user_top_artists(limit=15, time_range=params.time_range)
|
|
# Top tracks
|
|
top_tracks = sp.current_user_top_tracks(limit=20, time_range=params.time_range)
|
|
|
|
# Collect genres
|
|
genre_count = {}
|
|
for a in top_artists["items"]:
|
|
for g in a.get("genres", []):
|
|
genre_count[g] = genre_count.get(g, 0) + 1
|
|
top_genres = sorted(genre_count.items(), key=lambda x: -x[1])[:10]
|
|
|
|
lines = [f"📊 **MusicTail Taste Profile** — {range_label}\n"]
|
|
|
|
lines.append("**Top Artists:**")
|
|
for i, a in enumerate(top_artists["items"][:10], 1):
|
|
lines.append(f" {i}. {a['name']}")
|
|
|
|
lines.append(f"\n**Top Genres:**")
|
|
for g, c in top_genres:
|
|
lines.append(f" • {g} ({c} artists)")
|
|
|
|
lines.append(f"\n**Top Tracks:**")
|
|
for i, t in enumerate(top_tracks["items"][:10], 1):
|
|
artists = ", ".join(a["name"] for a in t["artists"])
|
|
lines.append(f" {i}. {t['name']} — {artists}")
|
|
|
|
return "\n".join(lines)
|
|
|
|
@mcp.tool(
|
|
name="musictail_fresh_finds",
|
|
annotations={
|
|
"title": "Fresh Finds",
|
|
"readOnlyHint": True,
|
|
"destructiveHint": False,
|
|
}
|
|
)
|
|
async def fresh_finds(params: FreshFindsInput) -> str:
|
|
"""
|
|
Discover new tracks based on your listening, with an adventure dial.
|
|
Normal mode stays close to your taste. Adventurous mode pushes boundaries.
|
|
"""
|
|
sp = get_spotify_client()
|
|
|
|
if params.adventurous:
|
|
# Use long-term + different seed strategy
|
|
top = sp.current_user_top_artists(limit=10, time_range="long_term")
|
|
# Pick less-obvious artists (positions 5-10 instead of 1-5)
|
|
seed_artists = [a["id"] for a in top["items"][4:9]][:5]
|
|
kwargs = {
|
|
"seed_artists": seed_artists,
|
|
"limit": params.count,
|
|
"min_popularity": 5,
|
|
"max_popularity": 50, # Push toward obscure
|
|
}
|
|
else:
|
|
# Use recent tracks as seeds
|
|
top = sp.current_user_top_tracks(limit=10, time_range="short_term")
|
|
seed_tracks = [t["id"] for t in top["items"][:5]]
|
|
kwargs = {
|
|
"seed_tracks": seed_tracks,
|
|
"limit": params.count,
|
|
}
|
|
results = sp.recommendations(**kwargs)
|
|
|
|
mode = "🗺️ Adventurous" if params.adventurous else "🏠 Comfort Zone"
|
|
lines = [f"🎵 **MusicTail Fresh Finds** — {mode}\n"]
|
|
|
|
for i, track in enumerate(results["tracks"], 1):
|
|
artists = ", ".join(a["name"] for a in track["artists"])
|
|
album = track["album"]["name"]
|
|
pop = track.get("popularity", 0)
|
|
tid = track["id"]
|
|
lines.append(f"{i}. **{track['name']}** — {artists}")
|
|
lines.append(f" Album: {album} | Popularity: {pop} | ID: `{tid}`")
|
|
|
|
return "\n".join(lines)
|
|
|
|
|
|
# ========== Entry Point ==========
|
|
|
|
if __name__ == "__main__":
|
|
# When run directly, do initial OAuth dance
|
|
import sys
|
|
if "--auth" in sys.argv:
|
|
print("🎵 MusicTail — First-time authorization")
|
|
print("A browser window will open for Spotify login...")
|
|
sp = get_spotify_client()
|
|
user = sp.current_user()
|
|
print(f"✅ Authorized as: {user['display_name']} ({user['id']})")
|
|
print(f"Token cached at: ~/.musictail_cache")
|
|
print("MusicTail is ready! 🦊")
|
|
else:
|
|
mcp.run() |