Spotify MCP Server

🚀 Spotify用Kotlin MCPサーバー

このサーバーは、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 [リポジトリのURL]
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 を取得します。

💻 使用例

標準入出力モード

# サーバーの起動
./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() を使用してツールを登録し、名前、説明、入力スキーマを指定します。
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呼び出しの成功と失敗のケースをそれぞれテストすることをおすすめします。

📄 ライセンス

コードの貢献を歓迎します！このリポジトリをフォークし、コミットする前に 貢献ガイド をよく読んでください。