Kotlin MCP Server for Spotify

Spotify Kotlin MCP 服务

一个与 Spotify Web API 集成的 Model Context Protocol（MCP）服务 Kotlin 实现。此服务通过标准化接口提供控制 Spotify 播放、管理播放列表和获取用户信息的工具。

演示

视频

功能

• Spotify 身份验证：管理 Spotify API 令牌和身份验证
• 播放控制：播放、暂停、跳过曲目、跳转到指定位置、设置音量和控制重复模式
• 播放列表管理：创建播放列表、添加／移除曲目，以及获取播放列表信息
• 用户资料：获取用户资料信息
• MCP 集成：实现 Model Context Protocol，以支持标准化的工具交互

前置条件

• JDK 20 或更高版本
• Kotlin 2.1.10
• Gradle（包含 wrapper）
• Spotify Developer Account（用于 API 访问）

安装和设置

1. 克隆仓库：

   git clone https://github.com/yourusername/kotlin-mcp-server.git
   cd kotlin-mcp-server
   

2. 设置 Spotify Developer 凭据：

   • 前往 Spotify Developer Dashboard
   • 使用你的 Spotify 账户登录，或创建新账户
   • 点击“Create an App”
   • 填写应用名称和描述，然后点击“Create”
   • 在应用的控制面板中记下 Client ID 和 Client Secret
   • 在项目根目录中创建 .env 文件，内容如下：

     SPOTIFY_CLIENT_ID = "your-client-id"
     SPOTIFY_CLIENT_SECRET = "your-client-secret"
     

     例如：

     SPOTIFY_CLIENT_ID = "d4k32j4kl32j4k23j4k23j4k32if"
     SPOTIFY_CLIENT_SECRET = "5gd6f56fdsd6g5a6d7sd5656cvbx"
     

使用方法

服务可以通过两种模式运行：

1. 标准输入／输出模式（默认）： 在 Main.kt 中取消相应行的注释，以使用 Ktor 和 stdio 运行服务：

   // In Main.kt
   fun main() {
       runMcpServerUsingStdio()
       // runSseMcpServerUsingKtorPlugin(8080)
   }
   

   1. 运行以下命令以生成可执行文件：

      ./gradlew installDist
      

      这会在以下位置生成可执行文件：build/install/kotlin-mcp-server/bin/kotlin-mcp-server

   通过 VS Code 的 Copilot 连接： VS Code 的 Copilot 内置了 MCP 客户端，可在标准输入／输出模式下运行时连接到服务。你也可以使用 claude desktop 等其他 MCP 客户端，但我发现 Code 的 Copilot 是最容易上手的。使用方法：

2. 配置 VS Code 以连接到 MCP 服务：

   • 打开 VS Code 设置（Settings > Settings again ）
   • 在设置搜索栏中搜索“mcp”
   • 点击“Edit in settings.json”
   • 添加以下配置（根据你的安装情况调整路径）：

   {
       "security.workspace.trust.untrustedFiles": "open",
       "terminal.integrated.fontFamily": "MesloLGS Nerd Font",
       "mcp": {
           "inputs": [],
           "servers": {
               "spotify-mcp-server": {
                   "command": "/Users/karis/IdeaProjects/kotlin-mcp-server/build/install/kotlin-mcp-server/bin/kotlin-mcp-server",
                   "args": [],
                   "env": {}
               }
           }
       },
       "git.autofetch": true
   }
   

3. 在 VS Code 中打开 Copilot 聊天面板并选择 Agent Mode。

4. Copilot 会自动检测并连接到 MCP 服务

5. 现在，你可以通过 Copilot 界面使用 Spotify 工具

6. 服务器发送事件（SSE）模式： 在 Main.kt 中取消相应行的注释，以使用 Ktor 和 SSE 运行服务：

   // In Main.kt
   fun main() {
       // runMcpServerUsingStdio()
       runSseMcpServerUsingKtorPlugin(8080)
   }
   

   然后运行应用，并使用 MCP 检查器连接到 http://localhost:8080/sse。

项目结构

• src/main/kotlin/mcpserver/spotify/：Spotify API 集成核心代码
  • auth/：身份验证和令牌管理
  • services/：Spotify API 端点的服务实现
  • utils/：实用函数和错误处理
• src/main/kotlin/mcpserver/spotifymcp/：MCP 服务实现
  • tools/：MCP 服务的工具实现

可用工具

此服务提供以下用于与 Spotify 交互的工具：

播放控制

• 暂停播放
• 恢复播放
• 跳到下一首曲目
• 跳到上一首曲目
• 跳转到指定位置
• 设置音量
• 设置重复模式
• 获取当前队列

播放列表管理

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

用户信息

• 获取用户资料

开发指南

错误处理

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

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

使用 safeSpotifyApiCall 函数发起返回 SpotifyResult 对象的 API 调用：

val result = safeSpotifyApiCall<ResponseType, ErrorType> {
    // API call code here
}

添加新工具

要向 MCP 服务添加新工具：

1. 在 mcpserver/spotifymcp/tools 包中创建一个新的 Kotlin 文件
2. 定义一个接收 Server 实例和所有必需服务的函数
3. 使用 server.addTool() 注册工具，并为其指定名称、描述和输入架构
4. 在回调中实现工具的功能

测试

运行测试

# Run all tests
./gradlew test

# Run a specific test class
./gradlew test --tests "mcpserver.spotify.services.playerservice.SpotifyPlayerServiceImplTest"

# Run a specific test method
./gradlew test --tests "mcpserver.spotify.services.playerservice.SpotifyPlayerServiceImplTest.playTrack should return success when API call succeeds"

编写测试

项目使用 JUnit 5 进行测试。测试应放在 src/test/kotlin 目录中，并与主源代码的结构保持一致。

对于 HTTP 客户端模拟，使用 Ktor 的 MockEngine 模拟 HTTP 响应。测试依赖外部 API 的服务时，应创建依赖项的模拟实现，并测试成功和失败两种场景。

贡献

欢迎贡献！请随时提交 Pull Request。