星战科技xingzhan.cloud
返回市场
Spotify微服务核心部件

Spotify微服务核心部件

作者：LibreChat-AI8 星标更新：2025-06-17
安装使用来源：spider==github.com

项目介绍

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系统。

资源