🎵 Spotify AI播放列表生成器
智能MCP（模型上下文协议）服务器，使用人工智能生成个性化的Spotify播放列表。该项目将谷歌的Gemini人工智能与Spotify丰富的音乐目录相结合，根据自然语言提示创建精心策划的播放列表。
✨ 特性
- 人工智能驱动的策展：使用Google Gemini生成智能搜索查询并策划曲目选择
- Spotify集成：与Spotify的API完全集成，用于身份验证、搜索和播放列表创建
- 个性化推荐：分析用户的收听历史，以获得更好的建议
- 自然语言处理：使用简单的提示创建播放列表，如“欢快的锻炼音乐”或“周日早晨的凉爽氛围”
- 灵活的持续时间：指定播放列表长度，范围为1到300分钟
- MCP服务器：作为模型上下文协议服务器运行，便于与AI助手集成
- 健康监测：内置健康检查和日志记录
🚀 快速开始
先决条件
- Python 3.8+
- Spotify高级帐户（推荐）
- Spotify开发者应用程序凭据
- Google Gemini API密钥
安装
- 克隆存储库
git clone
cd spotify-playlist-generator- 安装依赖项
pip install -r requirements.txt- 设置环境变量
cp .env.example .env
# Edit .env with your credentials- 运行服务器
python main.py服务器将于启动 http://127.0.0.1:10000 默认情况下。
🔧 配置
环境变量
创建一个 .env 项目根目录中的文件，包含以下变量：
# Spotify API Credentials
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
# Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key
# Server Configuration
PORT=10000
# Optional: Your phone number for validation
MY_NUMBER=+1234567890Spotify开发者设置
- 首选 Spotify开发者仪表板
- 创建新应用程序
- 记下您的客户端ID和客户端密码
- 添加重定向URI:
http://127.0.0.1:10000/callback - 添加所需的范围（由应用程序自动处理）
Google Gemini API设置
- 首选 谷歌人工智能工作室
- 创建新的API密钥
- 将密钥添加到您的
.env文件
📖 用法
1.健康检查
curl http://127.0.0.1:10000/health2.通过Spotify进行身份验证
服务器将提供一个身份验证URL。访问它以授权应用程序。
3.获取用户数据
身份验证后，获取您的Spotify收听历史记录以进行个性化推荐。
4.生成播放列表
使用自然语言提示创建播放列表：
- “45分钟充满活力的健身音乐”
- “为学习而放松独立歌曲”
- “90年代公路旅行摇滚歌曲”
- “雨天的情感歌谣”
🛠️ API终点
MCP工具
服务器公开了以下MCP工具：
health：检查服务器运行状况validate：验证配置authenticate：获取Spotify身份验证URLfetch_data：获取并存储用户的Spotify数据generate_playlist：生成人工智能策划的播放列表
生成播放列表参数
{
"prompt": "string (required) - Description of desired playlist",
"duration_minutes": "integer (optional, default: 60) - Playlist length",
"playlist_name": "string (optional, default: 'AI Generated Playlist') - Playlist name"
}🏗️ 建筑
组件
- 主服务器(
main.py)：FastMCP服务器处理HTTP请求和路由 - Spotify处理器(
spotify_handler.py)：Spotify API集成使用Tekore - 播放列表生成器(
playlist_generator.py)：使用Gemini进行AI驱动的播放列表管理
数据流
- 用户提供自然语言提示
- Gemini AI生成相关搜索查询
- Spotify API搜索匹配曲目
- 系统根据用户历史记录获取其他推荐
- Gemini AI策划最终曲目选择
- 创建并填充Spotify播放列表
文件结构
├── main.py # MCP server and main entry point
├── spotify_handler.py # Spotify API integration
├── playlist_generator.py # AI playlist generation logic
├── requirements.txt # Python dependencies
├── .env.example # Environment variables template
└── README.md # This file📊 数据存储
应用程序为以下对象创建本地JSON文件：
- 用户数据:
user_data_YYYYMMDD_HHMMSS.json-Spotify收听历史 - 播放列表数据:
playlist_YYYYMMDD_HHMMSS.json-生成的播放列表元数据
这些文件用于改进推荐并提供播放列表历史记录。
🔍 日志记录
该应用程序提供全面的日志记录：
- 信息：一般应用流程和成功操作
- 警告：非关键问题（例如，回退到简单模式）
- 错误：关键错误和失败
日志输出到控制台，带有时间戳和日志级别。
⚙️ 回退模式
无Gemini API
如果Gemini API不可用，系统将回退到：
- 基于关键字的简单搜索查询生成
- 基于流行度的随机曲目选择
无用户身份验证
该系统仍然可以：
- 使用Spotify的公共API搜索曲目
- 根据搜索结果创建播放列表（个性化程度有限）
🚨 错误处理
该应用程序包括强大的错误处理功能，用于：
- 身份验证失败：清除错误消息和重试机制
- API费率限制：优雅的降级和重试
- 网络问题：超时处理和回退选项
- 无效输入：输入验证和用户友好的错误消息
🔒 隐私和安全
- 无持久存储：用户令牌仅在会话期间保存在内存中
- 本地数据：所有用户数据都存储在本地计算机上
- 最小范围：仅请求必要的Spotify权限
- 环境变量：存储在环境变量中的敏感凭据
📋 需求
Python依赖关系
fastmcp>=0.1.0
tekore>=4.0.0
google-generativeai>=0.3.0
asyncio
logging
typing
datetime
json
os
random
glob系统要求
- 记忆：最低512MB RAM
- 存储：100MB用于应用程序和数据文件
- 网络：用于API调用的稳定互联网连接
🐛 故障排除
常见问题
- 认证错误
- 在中检查Spotify凭据 .env - 验证Spotify应用程序设置中的重定向URI - 确保启用了所有必需的作用域
- 未找到曲目
- 尝试更具体或不同的提示 - 检查互联网连接 - 验证Spotify API的访问权限
- Gemini API错误
- 验证API密钥是否正确 - 检查API配额限制 - 如果需要，系统将回退到简单模式
- 端口已在使用中
- 更改端口 .env 文件 - 终止端口上的现有进程
调试模式
通过修改中的日志记录级别启用调试日志记录 main.py:
logging.basicConfig(level=logging.DEBUG)🤝 贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
📜 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- Spotify Web API 用于音乐数据和播放列表管理
- 谷歌双子座 用于人工智能驱动的策展
- Tekore 用于Spotify API的优雅集成
- FastMCP 用于MCP服务器实现
📞 支持
如有疑问、问题或功能请求：
- 检查 问题 页
- 创建包含详细信息的新问题
- 报告错误时包括日志和错误消息
______________________________________________________________________
由以下材料制成❤️ 适合音乐爱好者和人工智能爱好者