用于 Spotify 的 Kotlin MCP 服务器

一个用 Kotlin 实现的 Model Context Protocol (MCP) 服务器，集成 Spotify Web API。此服务器提供工具来控制 Spotify 播放、管理 playlist、以及通过标准化接口获取用户信息。

功能

• Spotify 认证：管理 Spotify API 令牌和认证
• 播放控制：暂停/恢复播放、跳转上下首、调整播放位置、设置音量、设置循环模式、获取当前队列
• Playlist 管理：获取用户 playlist、获取 playlist 项、创建 playlist、添加/删除 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 管理

• 获取用户 playlist 列表
• 获取特定 playlist 中的曲目
• 创建新 playlist
• 添加曲目到 playlist
• 从 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 本仓库并在提交前仔细阅读 贡献指南。