Spotify MCP OAuth Server

这是对Stytch的MCP消费者待办事项列表示例的一个分支，经过调整以展示如何使用Cloudflare Workers将Spotify OAuth 2.0与模型上下文协议（MCP）集成。

为什么创建这个分支？

原始的Stytch示例为实现MCP服务器的OAuth发现和动态客户端注册提供了一个很好的基础。我们分出这个项目是为了：

1. 利用OAuth发现模式：原始实现展示了如何创建与MCP Inspector兼容的OAuth发现端点。
2. 用Spotify替换Stytch：演示如何与不原生支持动态客户端注册的第三方OAuth提供商（如Spotify）集成。
3. 专注于API层：虽然原始示例包含了一个完整的待办事项应用及其前端组件，但这个分支主要集中在MCP服务器的实现上。

发生了哪些变化

API层更新

• 新增文件：

  • api/SpotifyMCP.ts - 针对Spotify Web API的MCP服务器实现
  • api/SpotifyService.ts - 用于Spotify API交互的服务层
  • api/lib/spotify-auth.ts - Spotify的OAuth流程实现

• 修改文件：

  • api/index.ts - 更新以处理Spotify OAuth流程和MCP端点
  • 环境变量从Stytch更改为Spotify凭据

主要功能

此实现提供了：

• 支持PKCE的OAuth 2.0授权码流
• OAuth发现端点位于/.well-known/oauth-authorization-server
• 动态客户端注册以兼容MCP Inspector
• 自动令牌刷新当访问令牌过期时
• 通过MCP工具完全集成Spotify Web API
• Cloudflare持久对象用于管理MCP服务器状态

架构

该项目使用：

• Cloudflare Workers作为后端API
• Cloudflare持久对象作为MCP服务器实例
• Spotify Web API用于音乐数据和播放控制
• **模型上下文协议（MCP）**用于AI代理集成

重要提示：开发示例

⚠️ 此服务器主要用于开发和测试MCP客户端的OAuth流程。

此实现优化了：

• 使用LibreChat进行测试——一个支持MCP的开源AI聊天平台
• 使用MCP Inspector进行开发——官方MCP调试工具
• 学习如何为MCP服务器实现OAuth发现

不适合生产环境

在部署到生产环境之前，你应该：

1. 添加身份验证验证

   • 在/register端点中实现正确的客户端验证
   • 添加速率限制以防止滥用
   • 将重定向URI与白名单进行验证

2. 增强安全性

   • 实现CSRF保护
   • 添加请求签名/验证
   • 使用安全会话管理
   • 实现适当的错误处理，避免泄露敏感信息

3. 添加监控和日志记录

   • 实现全面的日志记录
   • 添加错误跟踪（例如，Sentry）
   • 监控API使用情况和速率限制
   • 跟踪OAuth流程完成率

4. 优化扩展性

   • 实现缓存策略
   • 添加数据库以实现持久存储（而不是KV用于生产数据）
   • 实现适当的连接池
   • 对于速率限制操作，添加请求队列

5. 处理边缘情况

   • 实现带有指数退避的正确重试逻辑
   • 处理Spotify API维护窗口
   • 对非关键特性添加优雅降级
   • 实现适当的超时处理

已经适合生产环境的内容

得益于原始的Stytch实现，此项目已经包括：

✅ Cloudflare Workers部署

• 完整的Workers配置，包括wrangler.jsonc
• 为MCP服务器实例设置持久对象
• Workers KV集成用于数据存储
• 适用于Workers环境的正确TypeScript配置

✅ 基础设施基础

• 实现SSE（服务器发送事件）用于实时MCP通信
• 正确处理CORS
• 环境变量管理
• 构建和部署脚本

这意味着你已经有了一个坚实的基础设施基础——你只需要添加上述提到的安全性和监控层即可用于生产。

生产部署检查清单

如果你计划在生产环境中使用此项目：

• 审查并实施所有安全考虑
• 添加全面的错误处理
• 实现适当的日志记录和监控
• 添加自动化测试
• 设置CI/CD管道
• 安全地配置生产环境变量
• 实现备份和恢复程序
• 添加API版本策略
• 创建特定实现的文档
• 实现用户同意和数据隐私合规

MCP Inspector兼容性

遵循PayPal的MCP服务器模式，此实现提供了：

1. OAuth发现位于/.well-known/oauth-authorization-server
2. 动态客户端注册位于/register端点
3. 授权代理将重定向至Spotify的OAuth系统

这允许MCP Inspector和其他MCP客户端自动发现并注册到我们的服务器，即使Spotify本身不支持动态客户端注册。

设置

1. 创建Spotify应用程序

1. 访问Spotify开发者仪表板
2. 创建一个新的应用程序
3. 记录你的客户端ID和客户端密钥
4. 为你的应用程序添加重定向URI（例如，http://localhost:3000/callback）

2. 配置环境变量

基于.dev.vars.template创建一个.dev.vars文件：

SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

3. 安装依赖项

npm install

4. 本地运行

npm run dev

MCP服务器将在http://localhost:3000/sse可用。

Vite环境变量

vite.config.ts文件支持额外的开发环境变量：

• VITE_PORT：自定义开发服务器端口（默认：3000）

  VITE_PORT=8080 npm run dev
  

• VITE_ALLOWED_HOSTS：指定开发服务器允许的主机（在使用隧道服务时有用）

  VITE_ALLOWED_HOSTS="localhost,your-ngrok-domain.ngrok-free.app" npm run dev
  

HTTPS要求

问题

Spotify Web API要求HTTPS用于OAuth回调，并且现代浏览器强制执行MCP客户端和服务器之间的安全连接，以防止混合内容问题。

根据部署类型的不同解决方案

生产部署（推荐）

✅ Cloudflare Workers解决方案

• MCP服务器：部署到Cloudflare Workers——自动包含HTTPS

  • 部署后的服务器：https://your-worker.workers.dev
  • 永久、稳定的HTTPS URL
  • 不需要额外的SSL配置
  • 全球边缘网络以实现快速响应时间

• MCP客户端：大多数生产MCP客户端已经通过HTTPS运行

• Spotify应用程序：更新重定向URI以使用你的Workers域名（一次性设置）

# 部署以获取永久HTTPS URL
npm run deploy

# 更新Spotify应用程序重定向URI为：
# https://your-worker.workers.dev/callback

本地开发

🔧 ngrok解决方案用于本地测试

在本地开发时，使用ngrok创建HTTPS隧道：

1. 安装ngrok

# 从https://ngrok.com/download下载或使用包管理器
brew install ngrok  # macOS
# 或
snap install ngrok  # Linux

2. 启动本地MCP服务器

# 使用允许的主机配置启动
VITE_ALLOWED_HOSTS="localhost,*.ngrok-free.app" npm run dev

3. 创建HTTPS隧道

对于本地开发，你可能需要为服务器和客户端创建隧道：

# 终端1：为MCP服务器创建隧道（端口3000）
ngrok http 3000

# 终端2：如果本地运行LibreChat，则为LibreChat创建隧道（端口3080）
ngrok http 3080

4. 配置开发会话

启动ngrok后，你会得到临时HTTPS URL：

• MCP服务器：https://abc123.ngrok-free.app
• LibreChat：https://def456.ngrok-free.app

更新你的Spotify应用程序以适应此次开发会话：

1. 访问Spotify开发者仪表板
2. 添加ngrok重定向URI：https://abc123.ngrok-free.app/callback
3. 配置MCP客户端使用：https://abc123.ngrok-free.app/sse

比较：生产 vs 开发

方面	Cloudflare Workers（生产）	ngrok（开发）
HTTPS	✅ 自动，永久	✅ 临时隧道
URLs	✅ 稳定，持久	❌ 重启后改变
设置	✅ 一次部署	❌ 每次会话设置
成本	✅ 提供免费层级	✅ 提供免费层级
性能	✅ 全球边缘网络	❌ 隧道开销
用途	生产，永久测试	本地开发

推荐工作流程

1. 首先使用生产环境：先部署到Cloudflare Workers进行稳定测试
2. 需要时使用本地环境：仅在需要测试本地代码更改时使用ngrok
3. 混合方法：保留生产部署进行稳定测试，使用本地进行积极开发

ngrok限制（仅限开发）

• 临时域名：每次重启URL都会改变（需要更新Spotify应用程序）
• 会话限制：免费计划下2小时会话
• 请求限制：免费计划下每分钟40个请求
• 多个隧道：需要为服务器和客户端分别设置ngrok实例

生产注意事项

✅ Cloudflare Workers优势：

• 自动HTTPS和有效证书
• 全球CDN以实现低延迟
• 内置DDoS防护
• 99.9%正常运行时间SLA
• 易于自定义域名支持

企业使用：

• 自定义域名：mcp.yourcompany.com
• 增强安全性，使用Cloudflare WAF
• 高级分析和监控
• 团队协作功能

OAuth流程

如何与MCP Inspector一起工作

1. 发现：MCP Inspector获取/.well-known/oauth-authorization-server
2. 注册：Inspector在/register端点注册自身
3. 授权：用户被重定向到/authorize，然后重定向到Spotify
4. 用户同意：用户在Spotify页面上授权
5. 令牌交换：Inspector在/token处交换代码
6. 访问MCP：Inspector使用令牌通过SSE访问MCP端点

可用的MCP工具

Spotify MCP服务器暴露以下工具：

搜索

• searchTracks - 搜索曲目
• searchArtists - 搜索艺术家
• searchAlbums - 搜索专辑
• searchPlaylists - 搜索播放列表

用户资料

• getCurrentUserProfile - 获取当前用户的资料

播放控制

• getCurrentPlayback - 获取当前播放状态
• pausePlayback - 暂停播放
• resumePlayback - 恢复播放
• skipToNext - 跳转到下一曲
• skipToPrevious - 跳转到上一曲

播放列表

• getUserPlaylists - 获取用户的播放列表
• getPlaylistTracks - 获取播放列表中的曲目
• createPlaylist - 创建新的播放列表
• addTracksToPlaylist - 向播放列表添加曲目

用户数据

• getRecentlyPlayed - 获取最近播放的曲目
• getTopTracks - 获取用户的热门曲目
• getTopArtists - 获取用户的热门艺术家

示例用法

使用MCP Inspector

1. 打开MCP Inspector：

   npx @modelcontextprotocol/inspector@latest
   

2. 将传输类型设置为SSE
3. 输入URL：http://localhost:3000/sse
4. 点击连接
5. 当被重定向时，跟随OAuth流程

手动令牌使用

如果你希望跳过OAuth流程进行测试：

1. 使用手动流程获取令牌
2. 在MCP Inspector中添加头部：
   • Authorization: Bearer YOUR_ACCESS_TOKEN
   • X-Spotify-Refresh-Token: YOUR_REFRESH_TOKEN

部署

快速部署到Cloudflare Workers

🚀 自动HTTPS解决方案

部署到Cloudflare Workers自动解决了HTTPS需求：

# 1. 设置你的Spotify凭据
wrangler secret put SPOTIFY_CLIENT_ID
wrangler secret put SPOTIFY_CLIENT_SECRET

# 2. 部署（自动获得HTTPS）
npm run deploy

# 3. 更新Spotify应用程序重定向URI为你新的Workers URL
# 示例：https://your-worker.workers.dev/callback

你的MCP服务器将在https://your-worker.workers.dev/sse可用。

⚠️ 注意：这是一个开发示例。参见“重要：开发示例”部分以了解生产注意事项。

生产部署

实际生产使用：

1. 分支此仓库
2. 实现上述列出的安全增强
3. 添加适当的监控和错误处理
4. 考虑使用Cloudflare的付费功能：
   • 使用持久对象以更好地管理状态
   • 使用Workers KV进行缓存
   • 实现速率限制规则
   • 使用Web应用程序防火墙（WAF）

安全注意事项

1. 客户端凭证：永远不要在客户端代码中暴露你的Spotify客户端密钥
2. 令牌存储：安全存储令牌，并使用HTTPS进行所有通信
3. 范围：只请求应用程序所需的最小范围
4. PKCE：此实现支持PKCE以增加安全性
5. 客户端注册：在生产环境中，考虑在注册端点添加验证

Spotify API注意事项

1. HTTPS要求

• Spotify Web API要求HTTPS用于OAuth回调
• 解决方案：部署到Cloudflare Workers以自动获得HTTPS
• 本地开发：使用ngrok进行HTTPS隧道
• 当客户端和服务器使用不同协议时会发生混合内容错误

2. 活跃设备要求

• 播放控制端点（pausePlayback，resumePlayback等）需要活跃的Spotify设备
• 用户必须至少在一个设备（桌面应用、移动或网页播放器）上打开Spotify
• 如果没有可用设备，API会返回404“未找到活跃设备”

3. 高级账户限制

• 许多播放控制功能需要Spotify高级账户
• 免费账户可以读取数据但不能控制播放
• 对于免费账户，API会返回403“需要高级”错误

4. 速率限制

• Spotify在所有端点上实现了速率限制
• 限制因端点而异，但通常允许每分钟180个请求
• 对于429（请求过多）响应，实现指数退避

5. 令牌过期

• 访问令牌在1小时后过期
• 此实现处理自动刷新，但确保刷新令牌已存储
• 如果长时间未使用，刷新令牌可能会失效

6. 范围要求

• 不同的端点需要不同的OAuth范围
• 缺少范围会导致403“禁止”错误
• 常见所需范围：
  • user-read-private - 用户资料访问
  • user-read-playback-state - 当前播放信息
  • user-modify-playback-state - 播放控制
  • playlist-read-private - 访问用户播放列表
  • playlist-modify-public - 创建/修改播放列表

7. 地域限制

• 部分内容受地理市场限制
• API可能会根据用户的国家返回不同的结果
• 搜索时使用market参数以获取区域适当的结果

致谢

此项目基于Stytch MCP消费者待办事项列表示例，该示例展示了如何为MCP服务器实现OAuth发现。我们已经调整了他们的模式以适应Spotify的OAuth系统。

资源

• Spotify Web API文档
• OAuth 2.0授权码流
• 模型上下文协议
• Cloudflare Workers文档
• 原始Stytch示例