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 本倉庫並在提交前仔細閱讀 貢獻指南。