Spotify MCP Server

🚀 用于 Spotify 的 Kotlin MCP 服务器

这是一个用 Kotlin 实现的 Model Context Protocol (MCP) 服务器，它集成了 Spotify Web API。该服务器提供了一系列实用工具，可用于控制 Spotify 播放、管理播放列表，还能通过标准化接口获取用户信息。

🚀 快速开始

本服务器是一个用 Kotlin 实现的 Model Context Protocol (MCP) 服务器，集成了 Spotify Web API。它提供了控制 Spotify 播放、管理播放列表以及获取用户信息等功能，通过标准化接口方便与外部工具交互。

✨ 主要特性

• Spotify 认证：管理 Spotify API 令牌和认证。
• 播放控制：可实现暂停/恢复播放、跳转上下首、调整播放位置、设置音量、设置循环模式、获取当前队列等操作。
• Playlist 管理：能获取用户播放列表、获取播放列表项、创建播放列表、添加/删除播放列表中的曲目。
• 用户信息：获取用户资料。
• MCP 集成：提供标准化接口与外部工具交互。

📦 安装指南

先决条件

• JDK 1.8 或更高版本。
• Kotlin 1.6.0 或更高版本。
• Gradle 5.0 或更高版本。
• Spotify 开发者账号（用于获取 API 凭证）。

克隆仓库

git clone [仓库地址]
cd mcp-spotify-server

创建配置文件

在项目根目录下创建 config/application.properties 文件，添加以下内容：

# Spotify API 配置
spotify.client.id=[你的客户端ID]
spotify.client.secret=[你的客户端密钥]
spotify.redirect.uri=[重定向 URI]

# MCP 服务器配置
server.port=8080

获取 Spotify 开发者凭证

登录 Spotify Developer Dashboard，创建新应用以获取 CLIENT_ID 和 CLIENT_SECRET。

💻 使用示例

标准 I/O 模式

# 运行服务器
./gradlew run

# 生成可执行文件
./gradlew build

要通过 VS Code 连接到 MCP 服务器，请按以下步骤配置：

1. 打开 VS Code 设置（File -> Settings）。
2. 点击 Terminal，选择 Run on startup。
3. 在启动命令中添加 cd [项目路径] && ./gradlew run。

SSE 模式

# 启动服务器
./gradlew run --args="--sse"

# 停止服务器
curl -X POST http://localhost:8080/stop

📚 详细文档

项目结构

src/main/kotlin/
├── mcpserver/spotify/
│   ├── services/          # Spotify API 调用服务
│   └── tools/            # MCP 工具实现
└── mcpserver/spotifymcp/
    └── tools/            # 第三方工具接口

可用工具

播放控制

• 暂停播放
• 恢复播放
• 跳转到下一首
• 跳转到上一首
• 调整播放位置
• 设置音量
• 设置循环模式
• 获取当前队列

Playlist 管理

• 获取用户播放列表
• 获取播放列表项
• 创建播放列表
• 添加曲目到播放列表
• 从播放列表删除曲目

用户信息

• 获取当前用户的资料信息

开发指南

错误处理

项目使用自定义 SpotifyResult<T, E> 密封类进行错误处理：

• SpotifyResult.Success<T>：包含成功的响应数据。
• SpotifyResult.Failure<E>：包含异常和错误详情。

使用 safeSpotifyApiCall 函数来进行 API 调用：

val result = safeSpotifyApiCall<ResponseType, ErrorType> {
    // 具体的 API 调用代码
}

添加新工具

要添加新的工具到 MCP 服务器，请按照以下步骤操作：

1. 在 mcpserver/spotifymcp/tools 包下创建一个新的 Kotlin 文件。
2. 定义一个函数，接受 Server 实例和必要的服务作为参数。
3. 使用 server.addTool() 注册工具，指定名称、描述和输入 schema。
4. 在回调中实现工具的具体功能。

测试指南

运行测试

# 运行所有测试
./gradlew test

# 运行特定测试类
./gradlew test --tests "mcpserver.spotify.services.playerservice.SpotifyPlayerServiceImplTest"

# 运行特定测试方法
./gradlew test --tests "mcpserver.spotify.services.playerservice.SpotifyPlayerServiceImplTest.playTrack should return success when API call succeeds"

编写测试

项目使用 JUnit 5 进行测试。测试代码应置于 src/test/kotlin 目录下，与主代码结构保持一致。

对于需要模拟 HTTP 请求的测试，建议使用 Ktor 的 MockEngine 来模拟不同的响应场景，并对 API 调用的成功和失败情况分别进行测试。

项目贡献

欢迎贡献代码！请 fork 本仓库并在提交前仔细阅读 贡献指南。