# soundcloud-mcp

SoundCloud 公式 API ([API Guide](https://developers.soundcloud.com/docs/api/guide)) を
[Model Context Protocol](https://modelcontextprotocol.io) サーバとして提供します。
Claude Code などの MCP クライアントから、SoundCloud の検索・トラック/プレイリスト/ユーザー情報の取得、
ログインユーザーのライブラリ操作 (いいね / リポスト / フォロー / コメント / プレイリスト編集 / アップロード) が行えます。

付属の Claude Code スキル `.claude/skills/soundcloud/` が、ツールの使い分け・認証・ページング・
書き込み操作の安全確認をモデルに指示します。

## 構成

| パス | 内容 |
|---|---|
| `src/auth.ts` | OAuth 2.1 (認可コード + PKCE / クライアントクレデンシャル / リフレッシュ)。複数アカウントのトークンをファイルに永続化 |
| `src/client.ts` | HTTP クライアント。401 時の自動リフレッシュ、5xx リトライ、`linked_partitioning` ページング、`/resolve` の 302 追跡 |
| `src/tools/*.ts` | MCP ツール定義 (auth / discovery / tracks / playlists / users / me / social / generic) |
| `src/format.ts` | API レスポンスをトークン効率の良い要約に整形 |
| `src/login.ts` | 端末から実行するログイン CLI (`npm run login`) |
| `.claude/skills/soundcloud/` | スキル本体 (`SKILL.md`) と参照資料 (`references/tools.md`, `references/api-reference.md`) |
| `.mcp.json` | Claude Code のプロジェクトスコープ MCP 設定 |

## セットアップ

1. SoundCloud のアプリを登録し、Client ID / Client Secret を取得します: https://soundcloud.com/you/apps
   Redirect URI に `http://localhost:8976/callback` を登録してください (変更する場合は `SOUNDCLOUD_REDIRECT_URI` も合わせる)。
2. 依存関係をインストールします (`prepare` スクリプトにより `dist/` が自動でビルドされます)。

   ```bash
   git clone https://github.com/auxa-m45/soundcloud-mcp.git
   cd soundcloud-mcp
   npm install
   ```

3. 認証情報を設定します。`.env` (このディレクトリ、git 管理外) か環境変数のどちらでも構いません。

   ```bash
   cp .env.example .env
   # SOUNDCLOUD_CLIENT_ID / SOUNDCLOUD_CLIENT_SECRET を記入
   ```

## Claude Code から使う

### A. このリポジトリ内で使う (プロジェクトスコープ)

`.mcp.json` が同梱されているので、このディレクトリで `claude` を起動すると `soundcloud` サーバの承認を求められます。
承認すると `soundcloud_*` ツールと `.claude/skills/soundcloud/` のスキルが自動で有効になります。

```bash
cd soundcloud-mcp
claude            # 初回に "soundcloud" サーバの使用を承認する
/mcp              # 接続状態を確認
```

`.mcp.json` は `${SOUNDCLOUD_CLIENT_ID:-}` のように環境変数を展開し、未設定なら空のままサーバに渡します。
空の場合はサーバが `.env` を読むので、`.env` に書いておけば環境変数は不要です。

### B. どのプロジェクトからも使う (ユーザースコープ)

```bash
claude mcp add --scope user soundcloud \
  -e SOUNDCLOUD_CLIENT_ID=xxx -e SOUNDCLOUD_CLIENT_SECRET=yyy \
  -- node /absolute/path/to/soundcloud-mcp/dist/index.js
```

`-e` を省略した場合も、サーバは自分のパッケージディレクトリにある `.env` を読みます。
スキルも全プロジェクトで使うには次のようにコピー (またはシンボリックリンク) します。

```bash
mkdir -p ~/.claude/skills
cp -r /absolute/path/to/soundcloud-mcp/.claude/skills/soundcloud ~/.claude/skills/soundcloud
```

### C. クローンせずに使う

npm が GitHub から取得してビルドします (初回は数十秒かかります)。

```bash
claude mcp add --scope user soundcloud \
  -e SOUNDCLOUD_CLIENT_ID=xxx -e SOUNDCLOUD_CLIENT_SECRET=yyy \
  -- npx -y github:auxa-m45/soundcloud-mcp
```

### 動作確認

```bash
/mcp                                   # Claude Code 内: soundcloud が connected か
```

Claude に「SoundCloud で lofi を検索して」と頼むと `soundcloud_search_tracks` が呼ばれます。
いいねやアップロードなどユーザー権限が必要な操作は、Claude が `soundcloud_auth_login` を実行して
表示する URL をブラウザで承認してください。

## 他の MCP クライアント

stdio で起動します。

```json
{
  "mcpServers": {
    "soundcloud": {
      "command": "node",
      "args": ["/absolute/path/to/soundcloud-mcp/dist/index.js"],
      "env": { "SOUNDCLOUD_CLIENT_ID": "xxx", "SOUNDCLOUD_CLIENT_SECRET": "yyy" }
    }
  }
}
```

## 認証モード

| モード | 取得方法 | できること |
|---|---|---|
| app (クライアントクレデンシャル) | Client ID / Secret があれば自動 | 検索、resolve、公開トラック / プレイリスト / ユーザーの取得、ストリーム URL |
| user (認可コード + PKCE) | 下記ログイン | 上記に加え `/me` 系、いいね、リポスト、フォロー、コメント、アップロード、プレイリスト編集 |

ログインは 2 通りあります。

- **MCP ツールから**: `soundcloud_auth_login` を呼ぶと `authorize_url` が返るので、ブラウザで開いて承認します。
  サーバ内のローカルリスナーがコールバックを受け取り、`soundcloud_auth_status` でログイン済みになります。
- **端末から**: `npm run login` を実行するとブラウザが開き、承認後にトークンが保存されます。

トークンは `~/.config/soundcloud-mcp/tokens.json` (mode 600) に保存されます。`SOUNDCLOUD_TOKEN_FILE` で変更できます。
リフレッシュトークンは単回使用のため、更新のたびに保存し直しています。
クライアントクレデンシャルのトークンは発行上限 (12 時間に 50 回 / アプリ) があるため、期限までキャッシュして再利用します。

## マルチアカウント

複数の SoundCloud アカウントを同時にログインさせておき、使い分けられます。

- 各アカウントは **alias** (既定はログイン後に `/me` から取得した SoundCloud のハンドル = プロフィール URL の末尾) で識別します。
  `soundcloud_auth_login` の `alias` (例: `label`) で任意の名前を付けられます。
- ログイン済みアカウントのうち 1 つが **既定 (active) アカウント** です。`account` を指定しないツール呼び出しと、
  公開情報の読み取りはこのアカウントのトークンを使います。新しくログインしたアカウントは既定になります
  (`make_default: false` で変更しない)。
- ユーザー権限が必要なツール (`soundcloud_me`, `soundcloud_list_my_content`, いいね / リポスト / フォロー /
  コメント、アップロード、トラック / プレイリストの編集と削除、`soundcloud_api_request`) は `account`
  (alias / ユーザー名 / user URN) で呼び出しごとにアカウントを切り替えられます。
- `soundcloud_auth_switch_account` で既定アカウントを変更、`soundcloud_auth_logout` で 1 つ (既定) または
  `all: true` で全アカウントを削除します。
- 別アカウントを追加するときは、ブラウザ側で soundcloud.com からサインアウトしてから (またはプライベート
  ウィンドウで) 承認 URL を開いてください。同じ SoundCloud ユーザーで再ログインすると既存エントリを更新します。

端末からは次のように追加します。

```bash
npm run login -- --alias label            # alias を指定して追加 (既定になる)
npm run login -- --alias sub --no-default # 既定は変えずに追加
```

旧バージョンの単一ユーザー形式のトークンファイルは、初回読み込み時に alias `default` として自動移行されます。

## ツール一覧

| 分類 | ツール |
|---|---|
| 認証 | `soundcloud_auth_status`, `soundcloud_auth_login`, `soundcloud_auth_complete`, `soundcloud_auth_switch_account`, `soundcloud_auth_logout` |
| 検索 / 解決 | `soundcloud_resolve`, `soundcloud_search_tracks`, `soundcloud_search_playlists`, `soundcloud_search_users`, `soundcloud_next_page` |
| トラック | `soundcloud_get_track`, `soundcloud_get_track_streams`, `soundcloud_get_track_comments`, `soundcloud_get_related_tracks`, `soundcloud_get_track_engagement`, `soundcloud_upload_track`, `soundcloud_update_track`, `soundcloud_delete_track`, `soundcloud_set_track_storefront` |
| プレイリスト | `soundcloud_get_playlist`, `soundcloud_get_playlist_tracks`, `soundcloud_get_playlist_reposters`, `soundcloud_create_playlist`, `soundcloud_update_playlist`, `soundcloud_add_playlist_tracks`, `soundcloud_remove_playlist_tracks`, `soundcloud_delete_playlist` |
| ユーザー | `soundcloud_get_user`, `soundcloud_list_user_content` |
| 自分 | `soundcloud_me`, `soundcloud_list_my_content` |
| ソーシャル | `soundcloud_set_like`, `soundcloud_set_repost`, `soundcloud_set_follow`, `soundcloud_comment_on_track` |
| 汎用 | `soundcloud_api_request` (未ラップのエンドポイント用) |

識別子 (`track` / `playlist` / `user` / `target`) には URN (`soundcloud:tracks:123`)、数値 ID、
soundcloud.com の URL のいずれも渡せます。URL は内部で `/resolve` を呼んで URN に変換します。
一覧系のツールは `next_href` を返すので、`soundcloud_next_page` で続きを取得します。

各ツールの引数と戻り値は `.claude/skills/soundcloud/references/tools.md` を参照してください。

## 開発

```bash
npm run typecheck   # 型チェック
npm test            # ユニットテスト (fetch をモックした認証 / クライアントのテストを含む)
npm run dev         # tsx で stdio サーバを起動
npm run smoke       # ビルド済みサーバを MCP クライアントから起動し、ツール一覧と auth_status を表示
npm run smoke -- "lofi"   # 認証情報があれば検索まで実行
```

## 制限とレート制限

- ストリーム URL の取得: 24 時間あたり 15,000 リクエスト / client_id
- クライアントクレデンシャルのトークン発行: 12 時間あたり 50 回 / アプリ、1 時間あたり 30 回 / IP
- アップロード: 4 GB、24 時間まで。対応形式 AIFF, WAVE, FLAC, OGG, MP2, MP3, AAC, AMR, WMA。アートワークは PRO アカウントのみ
- 429 応答には `rate_limit.reset_time` が含まれ、ツールのエラーメッセージにも表示されます

## ライセンス

MIT