Apple Music到Spotify同步🎵
使用iOS快捷方式将Apple Music中的歌曲无缝同步到Spotify播放列表。该系统使用 Anthropic的代理SDK 使用MCP（模型上下文协议）实现智能、AI驱动的音乐同步。
🚀 现在使用代理SDK： 该项目已迁移到Anthropic的Agent SDK作为主要实现。与之前的时态或独立方法相比，Agent SDK提供了内置的AI推理、自动工具编排和更简单的代码。看 AGENT_INTEGRATION.md 了解详情。
演示
观看一键同步：分享Apple Music中的歌曲→ 点击“添加到Spotify”→ Done!AI智能匹配并将其添加到您的Spotify播放列表中。
为什么这个项目存在
问题：当您取消订阅时，Apple Music会删除您的库
在Apple Music工作了6年后，我转而使用Spotify——结果却发现 当您取消订阅时，Apple Music会在一段时间后删除您的整个音乐库 (查看此Reddit讨论).与Spotify不同，即使没有活动订阅，Spotify也会保留您的库，而苹果则会擦除所有内容。
事情是这样的：
- 📚 6年精心策划的音乐 -取消订阅Apple Music后离开
- 🎵 苹果的推荐引擎仍然知道我的口味 -它记录了我所有的听力历史
- 📱 买了一部有3个月免费Apple Music的新手机 -根据我的旧数据，仍然显示出很好的建议
- 😫 沮丧 -没有简单的方法可以将这些推荐的宝石保存到我的Spotify播放列表中
解决方案：从Apple Music到Spotify的一键同步
这个项目弥合了这一差距。当Apple Music推荐一首我想保留的歌曲时，我现在可以：
- 点击 分享 Apple Music中的按钮
- 选择 “添加到Spotify” 捷径
- 完成！这首歌被智能匹配并添加到我的Spotify播放列表中
不再：
- ❌ 在Spotify上手动搜索
- ❌ 失去对优秀推荐的追踪
- ❌ 在应用程序之间切换以查找同一首歌
- ❌ 担心再次失去我的音乐库
这对以下任何人来说都特别有价值：
- 从Apple Music切换到Spotify
- 由于苹果的删除政策，他们的图书馆丢失了
- 仍然使用Apple Music的推荐引擎
- 希望有一种无缝的方式来跨平台保存发现
特性
- 一键同步 通过iOS快捷方式从Apple Music共享表
- 人工智能驱动的匹配 克劳德的内在推理能力（99%的置信度）
- 自动消歧 翻拍、现场版本和封面
- 即发即弃 即时响应架构
- 基于MCP的工具执行 用于清洁Spotify API集成
- 基于提示的定制 -在不更改代码的情况下更改行为
- 部署简单 -无需Docker或工作流编排
- API快速响应 带背景处理
- ISRC匹配 用于在可用时进行精确的轨迹识别
建筑
当前：代理SDK架构（推荐）
graph LR
A[📱 iOS Shortcuts] -->|HTTP POST| B[🚀 FastAPI Server]
B -->|Background Task| C[🤖 Agent Executor]
C -->|Agent SDK| D[🧠 Claude]
C -->|MCP Protocol| E[🎵 MCP Spotify Server]
E -->|REST API| F[🎶 Spotify API]
D -.->|Built-in AI Reasoning| C
style A fill:#e1f5ff,stroke:#01579b,stroke-width:2px
style B fill:#fff3e0,stroke:#e65100,stroke-width:2px
style C fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style D fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
style E fill:#fce4ec,stroke:#880e4f,stroke-width:2px
style F fill:#e0f2f1,stroke:#004d40,stroke-width:2px它是如何工作的：
- iOS快捷方式将曲目信息发送到FastAPI服务器
- 服务器使用代理执行器生成后台任务
- 代理SDK连接到MCP Spotify服务器
- Claude自动选择并执行MCP工具：
- search_track -在Spotify上查找候选人 - add_track_to_playlist -添加最佳匹配 - verify_track_added -确认成功
- 克劳德的内置推理处理消歧
- 服务器返回99%置信度匹配的结果
📖 文档：
- AGENT_INTEGRATION.md -完整的代理SDK指南(⭐ 从这里开始)
- 建筑.md -详细的架构图
- MIGRATION_GUIDE.md -从旧架构迁移
- 项目_结构.md -文件组织指南
组件
- 📱 iOS快捷方式 -从Apple Music一键同步的用户界面
- 🚀 FastAPI服务器 (
api/app_agent.py)-用于同步请求的HTTP端点 - 🤖 代理执行人 (
agent_executor.py)-编排代理SDK - 🧠 克劳德 -内置AI推理和工具选择（通过Agent SDK）
- 🎵 MCP服务器 (
mcp_server/spotify_server.py)-Spotify API工具 - 🎶 Spotify API -音乐流媒体服务后端
传统架构（已弃用）
⚠️ 注： 时态和独立执行器已被弃用。看 MIGRATION_GUIDE.md 有关迁移的详细信息。
以前的实现：
- 临时工作流 -所需的Docker，复杂的设置（移至
_deprecated/) - 独立执行器 -单独的Claude API调用（移动到
_deprecated/)
为什么选择Agent SDK？
该项目已经通过多种架构发展到目前的Agent SDK实现：
| 特性 | 代理SDK（当前） | 临时（弃用） | 独立（弃用） |
|---|---|---|---|
| 设置复杂性 | ✅ 低 | ❌ 非常高 | ⚠️ 中等 |
| 代码行 | ✅ ~150 | ❌ ~500 | ⚠️ ~300 |
| 依赖项 | ✅ 仅限代理SDK | ❌ Docker+时态 | ⚠️ 许多图书馆 |
| AI集成 | ✅ 内置 | ❌ 单独活动 | ❌ 手动API调用 |
| 匹配质量 | ✅ 99%的置信度⚠️ ~80% | ⚠️ ~80% | |
| 演出 | ⚠️ ~22秒 | ✅ 10-15s | ✅ 8-12秒 |
| 可维护性 | ✅ 基于提示 | ❌ 复杂代码 | ⚠️ 手动逻辑 |
| 推荐 | ✅ 是 | ❌ 否 | ❌ 没有 |
绩效与情报权衡：
- 代理SDK速度较慢（约22秒），但产生的匹配明显更好（99%对约80%的置信度）
- 对于即发即弃iOS快捷方式用例，额外的10秒是可以接受的
- 看 性能_测试_结果.md 进行详细分析
- 看 MIGRATION_GUIDE.md 用于架构比较
快速开始
先决条件
核心要求：
- Python 3.11+
- 紫外线 （推荐）或pip用于包管理
- Spotify开发者帐户(获取凭据)
- 无烟煤API密钥 （Agent SDK需要）- 获取密钥
- 带有iOS快捷方式应用程序的iPhone（可选，用于iOS集成）
安装UV（推荐）：
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"1.克隆和安装
此项目使用 紫外线 用于快速、可靠的Python包管理。
cd spotify-mcp-integration
# Install dependencies with UV
uv sync
# Activate the virtual environment
source .venv/bin/activate # On Windows: .venv\Scripts\activate替代方案（使用pip）：
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt2.配置环境
cp .env.example .env编辑 .env 并添加您的凭据：
# Anthropic API Key (REQUIRED for Agent SDK)
# Get from https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=your_anthropic_key_here
# Spotify API (get from https://developer.spotify.com/dashboard)
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback
# Default Playlist ID (optional, can be provided per-request)
DEFAULT_PLAYLIST_ID=your_playlist_id_here获取Spotify凭据：
- 首选 Spotify开发者仪表板
- 点击 创建应用程序
- 填写应用程序详细信息（名称、描述、重定向URI）
- 添加重定向URI:
http://127.0.0.1:8888/callback
- ⚠️ 重要： 使用 127.0.0.1，不 localhost （Spotify要求） - 使用HTTP（不是HTTPS）进行本地开发
- 复制 客户端ID 和 客户端密钥
获取人类学API密钥：
- 首选 拟人控制台
- 创建新的API密钥
- 复制密钥（以开头
sk-ant-...)
获取播放列表ID:
- 打开Spotify→ 右键单击播放列表→ 分享→ 复制链接
- 从URL提取ID：
spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M→37i9dQZF1DXcBWIGoYBM5M
3.通过Spotify进行身份验证
仅限首次-运行MCP服务器进行身份验证：
python mcp_server/spotify_server.py这将：
- 打开Spotify OAuth浏览器
- 要求您登录并授权该应用程序
- 创建一个
.cache-spotify使用您的身份验证令牌的文件 - 身份验证成功后退出（按Ctrl+C）
4.启动API服务器
启动代理SDK API服务器：
# Simple way (recommended)
./run.sh
# Or with UV
uv run uvicorn api.app_agent:app --host 0.0.0.0 --port 8000 --reload
# Or activate virtual environment first
source .venv/bin/activate
python -m uvicorn api.app_agent:app --host 0.0.0.0 --port 8000 --reload您应该看到：
INFO: Started server process [12345]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000访问API文档：http://localhost:8000/docs
5.测试API
curl -X POST http://localhost:8000/api/v1/sync \
-H "Content-Type: application/json" \
-d '{
"track_name": "Bohemian Rhapsody",
"artist": "Queen",
"album": "A Night at the Opera",
"playlist_id": "YOUR_PLAYLIST_ID"
}'预期响应：
{
"workflow_id": "sync-anonymous-1699564832-a3f9d",
"status": "accepted",
"message": "Sync started for 'Bohemian Rhapsody' by Queen",
"status_url": "/api/v1/sync/sync-anonymous-1699564832-a3f9d"
}检查状态：
curl http://localhost:8000/api/v1/sync/sync-anonymous-1699564832-a3f9diOS快捷方式设置
1.获取服务器IP
在Mac上（相同的WiFi网络）：
ifconfig | grep "inet " | grep -v 127.0.0.1使用所示的IP（例如。， 192.168.1.100)
2.创建快捷方式
- 打开 捷径 iPhone上的应用程序
- 轻按 + 创建新快捷方式
- 添加以下操作：
行动：
- 接收 → 股份表中的任何输入
- 类型：音乐
- 获取音乐的详细信息
- 获取：名称→ 另存为 trackName
- 获取音乐的详细信息
- 获取：艺术家→ 另存为 artistName
- 获取音乐的详细信息
- 获取：专辑名称→ 另存为 albumName
- 词典
- 添加密钥： - track_name：trackName - artist：艺人姓名 - album专辑Name - playlist_id: YOUR_PLAYLIST_ID
- 获取URL内容
- 网址： http://YOUR_IP:8000/api/v1/sync - 方法：POST - 标题： - Content-Type: application/json - 请求正文：JSON→ 上一步的词典
- 显示通知 （可选）
- 标题：“添加到Spotify” - 正文：“按艺人名称同步曲目名称”
- 命名您的快捷方式： “添加到Spotify”
- 启用 在共享表中显示
3.使用快捷方式
- 在Apple Music中播放任何歌曲
- 轻按 分享 按钮
- 选择 添加到Spotify
- 完成！歌曲在背景中同步
配置
AI定制
Agent SDK使用Claude进行所有AI推理。您可以通过在中编辑系统提示来自定义行为 agent_executor.py:
system_prompt = """
You are a music matching assistant. Search Spotify for the given track,
analyze all candidates, and add the best match to the playlist.
Return a structured JSON response with confidence score and reasoning.
"""快速更改允许您：
- 调整匹配的严格程度
- 更喜欢某些曲目版本（原版vs翻拍版）
- 添加自定义业务规则
- 更改响应格式
无需更改代码，只需更新提示即可！
高级选项
可选环境变量：
# MCP Server Configuration
MCP_SERVER_TIMEOUT=60 # Seconds to wait for MCP server startup
# Agent SDK Model
CLAUDE_MODEL=claude-sonnet-4-5 # Use latest Claude model
# Logging
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR监控
健康检查
curl http://localhost:8000/api/v1/health答复：
{
"status": "healthy",
"timestamp": "2025-11-17T10:30:00Z"
}API日志
运行服务器时查看详细日志：
uv run uvicorn api.app_agent:app --log-level debug日志级别：
debug-详细的调试信息info-常规信息消息（默认）warning-仅警告消息error-仅错误消息
性能指标
看 性能_测试_结果.md 用于：
- API响应时间
- 代理执行故障
- 性能优化选项
项目结构
spotify-mcp-integration/
├── api/ # FastAPI server
│ ├── app_agent.py ✅ Agent SDK API server (CURRENT)
│ ├── app.py ⚠️ Temporal API (deprecated)
│ └── models.py # Request/response models
├── agent_executor.py ✅ Agent SDK executor (CURRENT)
├── mcp_server/ # MCP Spotify server
│ └── spotify_server.py ✅ Spotify MCP tools (CURRENT)
├── mcp_client/ # MCP client library
│ └── client.py # Custom MCP client (for testing)
├── models/ # Data models
│ └── data_models.py # Track matching models
├── config/ # Configuration
│ └── settings.py # Environment settings
├── tests/ # Test suite
│ ├── integration/ # Integration tests
│ └── unit/ # Unit tests
├── docs/ # Documentation
│ ├── AGENT_INTEGRATION.md ⭐ Primary guide
│ ├── MIGRATION_GUIDE.md # Migration from old architectures
│ ├── PROJECT_STRUCTURE.md # File organization guide
│ └── ios-shortcuts-setup.md
├── _deprecated/ # Deprecated code (old architectures)
│ ├── workflows/ ⚠️ Temporal workflows
│ ├── workers/ ⚠️ Temporal workers
│ ├── activities/ ⚠️ Temporal activities
│ └── executors/ ⚠️ Standalone executor
├── requirements.txt # Python dependencies
├── pyproject.toml # Project metadata
├── .env.example # Environment template
└── run.sh # Startup script关键文件：
- ✅ 当前（代理SDK） -使用这些
- ⚠️ 已弃用 -仅供参考，请参阅 MIGRATION_GUIDE.md
完整结构： 看 项目_结构.md 有关完整的文件详细信息
故障排除
“MCP服务器启动失败”
检查Python路径：
# In agent_executor.py, ensure correct Python executable
command=sys.executable # Should point to your venv Python直接测试MCP服务器：
python mcp_server/spotify_server.py
# Should print: "✓ Spotify MCP server initialized successfully"“Anthropic API密钥无效”
验证API密钥：
- 检查
.env有ANTHROPIC_API_KEY=sk-ant-... - 验证密钥是否处于活动状态https://console.anthropic.com/settings/keys
- 更新后重新启动API服务器
.env
“OAuth作用域不足”或“Spotify身份验证失败”
重新验证Spotify：
rm .cache-spotify
python mcp_server/spotify_server.py这将：
- 打开浏览器以获取新的OAuth流
- 请求必要的范围（播放列表修改公共，用户库读取）
- 将新令牌保存到
.cache-spotify
“在Spotify上找不到曲目”
可能的原因：
- 您所在地区没有歌曲
- 曲目/艺术家名称中的拼写错误
- 曲目已被区域锁定或从Spotify中删除
调试：
- 尝试在Spotify上手动搜索
- 查看API日志以了解搜索查询详细信息
- 使用测试文件：
python test_agent_performance.py
“代理执行超时”
增加agent_executor.py中的超时时间：
# Default is 60 seconds
result = agent.run(prompt, timeout=120) # Increase to 120s或者减少工具以加快速度：
# Skip verification for faster execution
allowed_tools=[
"mcp__spotify__search_track",
"mcp__spotify__add_track_to_playlist",
# "mcp__spotify__verify_track_added", # Skip this
]iOS快捷方式失败
检查服务器是否可访问：
# On iPhone, open Safari and visit:
http://YOUR_IP:8000/api/v1/health常见问题：
- 防火墙阻止端口8000
- 不同WiFi网络上的iPhone
- 服务器未运行
- 错误的IP地址（使用
ifconfig验证）
性能缓慢
预期时间：
- API接受请求：~0.1s
- 背景处理：~22-25s
- 总用户感知时间：\<0.5秒（即发即弃）
如果低于30秒：
- 检查Anthropic API的网络延迟
- 查看Spotify API费率限制
- 查看重试尝试日志
看 性能_测试_结果.md 用于优化选项
生产部署
部署选项
代理SDK体系结构部署起来很简单，只需使用带有环境变量的API服务器即可。
推荐平台：
- AWS ECS/Fargate
- GCP云运行
- Fly.io
- 铁路
- 渲染
- 数字海洋应用平台
Dockerfile
创建一个 Dockerfile:
# Use UV for fast dependency installation
FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim
WORKDIR /app
# Copy dependency files
COPY pyproject.toml uv.lock ./
# Install dependencies
RUN uv sync --frozen --no-dev
# Copy application code
COPY . .
# Expose port
EXPOSE 8000
# Start API server
CMD ["uv", "run", "uvicorn", "api.app_agent:app", "--host", "0.0.0.0", "--port", "8000"]替代方案（使用pip）：
FROM python:3.11-slim
WORKDIR /app
# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Copy application
COPY . .
EXPOSE 8000
CMD ["uvicorn", "api.app_agent:app", "--host", "0.0.0.0", "--port", "8000"]构建并运行
# Build image
docker build -t spotify-sync-agent .
# Run locally
docker run -p 8000:8000 --env-file .env spotify-sync-agent
# Test
curl http://localhost:8000/api/v1/health环境变量
在部署平台中设置这些：
必修的：
ANTHROPIC_API_KEY-代理SDK需要此SPOTIFY_CLIENT_ID-来自Spotify开发者仪表板SPOTIFY_CLIENT_SECRET-来自Spotify开发者仪表板SPOTIFY_REDIRECT_URI-OAuth回调URL
可选：
DEFAULT_PLAYLIST_ID-同步的默认播放列表LOG_LEVEL-日志记录级别（信息、调试、警告、错误）MCP_SERVER_TIMEOUT-MCP服务器启动超时（默认值：60秒）
Spotify OAuth正在制作中
对于服务器部署：
- 在Spotify开发者仪表板中更新重定向URI：
https://your-domain.com/auth/callback- 实现OAuth回调端点（可选）：
@app.get("/auth/callback")
async def auth_callback(code: str):
# Handle OAuth callback
# Store token securely
return {"status": "authenticated"}- 或者在部署前使用手动身份验证脚本：
python scripts/manual_spotify_auth.py
# Copy .cache-spotify to deployment缩放注意事项
当前实施：
- 单服务器处理后台任务
- 内存结果存储
- 适合个人使用/流量低
对于更高的流量：
- 添加Redis以实现结果持久化
- 实施适当的作业队列（Celery、BullMQ）
- 速率限制API端点
- 监测API的使用/成本
- 考虑缓存搜索结果
成本估算
人类API（Claude Sonnet 4.5）：
- 每次同步约0.01-0.02美元
- 100次同步/天≈30-60美元/月
托管（示例）：
- Fly.io:50美元/月（256MB内存）
- 铁路：免费或每月5-10美元
- AWS Fargate：约15-25美元/月（0.25vCPU，0.5GB RAM）
Spotify API： 免费（有费率限制）
API 参考
POST/api/v1/sync
启动歌曲同步工作流程。
请求：
{
"track_name": "Song Title",
"artist": "Artist Name",
"album": "Album Name",
"playlist_id": "spotify_playlist_id",
"match_threshold": 0.85,
"use_ai_disambiguation": true
}答复（202）：
{
"workflow_id": "sync-user-123-1699564832-a3f9d",
"status": "accepted",
"message": "Sync started...",
"status_url": "/api/v1/sync/{workflow_id}"
}GET/api/v1/sync/{workflow_id}
获取工作流状态。
响应（正在运行）：
{
"workflow_id": "...",
"status": "running",
"progress": {
"current_step": "matching",
"steps_completed": 2,
"steps_total": 4,
"candidates_found": 8,
"elapsed_seconds": 2.4
},
"started_at": "2025-11-09T10:30:32Z"
}回复（已完成）：
{
"workflow_id": "...",
"status": "completed",
"result": {
"success": true,
"message": "Successfully added 'Song' to playlist",
"spotify_track_id": "7tFiyTwD0nx5a1eklYtX2J",
"spotify_track_uri": "spotify:track:...",
"confidence_score": 0.98,
"execution_time_seconds": 4.2,
"match_method": "fuzzy"
},
"started_at": "2025-11-09T10:30:32Z",
"completed_at": "2025-11-09T10:30:36Z"
}文档
📚 时间整合规划
用于增强与时间耐久性模式集成的综合规划文件：
📂 时间规划文件
包括：
- 增强计划 -13个带有代码示例的优先增强功能
- SDK集成指南 -逐步迁移到
temporalio.contrib.openai_agents - MCP问答指南 -关键的MCP服务器集成怪癖和陷阱
- 时间表和时间安排 -时态调度如何与MCP服务器交互
- 现状分析 -对现有时间整合的评估
- 实施路线图 -带时间表的四阶段计划
快速链接：
📖 架构和API文档
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加测试
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件
文档
- AGENT_INTEGRATION.md -完整的Agent SDK集成指南(⭐ 从这里开始)
- MIGRATION_GUIDE.md -从临时/独立迁移
- 项目_结构.md -文件组织结构
- 性能_测试_结果.md -性能分析
- 建筑.md -系统架构详细信息
- docs/ios-shortcuts-setup.md -iOS快捷方式指南
支持
- 问题：
- 讨论：
- 人类学文献： docs.anthopic.com/agent-sdk
- MCP文件： 模型上下文协议.io
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 为新功能添加测试
- 提交拉取请求
看 AGENT_INTEGRATION.md 了解架构细节。
______________________________________________________________________
内置于❤️ 使用Anthropic Agent SDK、FastAPI和MCP