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（ラッパーを同梱）
• Spotify Developer アカウント（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"
     

使用方法

サーバーは 2 つのモードで実行できます：

1. 標準入出力モード（デフォルト）： Main.kt の該当する行のコメントを解除して、Ktor と標準入出力を使ってサーバーを実行します：

   // 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 の設定を開きます（設定 > 設定を再度選択）
   • 設定の検索バーで「mcp」を検索します
   • 「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 チャットパネルを開き、エージェントモードを選択します。

4. Copilot が MCP サーバーを自動的に検出して接続します

5. Copilot のインターフェースを通じて Spotify のツールを操作できます

6. Server-Sent Events（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> sealed クラスを使用しています。

• SpotifyResult.Success<T>：成功したレスポンスデータを含みます
• SpotifyResult.Failure<E>：エラーの詳細を含む例外を保持します

API 呼び出しを行う際は、SpotifyResult オブジェクトを返す safeSpotifyApiCall 関数を使用してください。

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 に依存するサービスをテストする際は、依存関係のモック実装を作成し、成功と失敗の両方のシナリオをテストしてください。

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。