Apple Music到Spotify同步🎵

使用iOS快捷方式将Apple Music中的歌曲无缝同步到Spotify播放列表。该系统使用 Anthropic的代理SDK 使用MCP（模型上下文协议）实现智能、AI驱动的音乐同步。

🚀 现在使用代理SDK： 该项目已迁移到Anthropic的Agent SDK作为主要实现。与之前的时态或独立方法相比，Agent SDK提供了内置的AI推理、自动工具编排和更简单的代码。看 AGENT_INTEGRATION.md 了解详情。

演示

Demo

观看一键同步：分享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.txt

2.配置环境

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-a3f9d

iOS快捷方式设置

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文档

架构指南 -带有详细图表的系统架构
API 参考 -完整的REST API文档
安装指南 -详细的安装和配置
测试指导 -测试套件文档
代理集成 -Claude代理SDK使用

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
进行更改
添加测试
提交拉取请求

许可证

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

贡献