Protools MCP Server

🚀 Pro Tools MCP Server

このMCP（Model Context Protocol）サーバーは、ClaudeなどのAIアシスタントがPTSL（Pro Tools Scripting Library）gRPC APIを介してPro Toolsを制御できるようにします。

⚠️ 実験的なプロジェクト: このプロジェクトは進行中であり、すべてのPro Tools機能が実装されているわけではありません。自己責任で使用してください！

✨ 主な機能

このサーバーは、AIアシスタントに以下の機能を提供します。

• セッション管理 - セッション情報を照会し、セッションを保存し、包括的なセッション概要を取得します。
• タイムラインナビゲーション - ページネーションでトラックとクリップを閲覧し、名前で検索し、タイムラインをナビゲートします（オーディオクリップのみ）。
• トラック制御 - トラックをリストアップ、選択、ミュート、ソロ、管理します。
• クリップ管理 - タイムライン上のオーディオクリップを見つけて操作します。
• 編集操作 - タイムラインの選択範囲でカット、コピー、貼り付け、クリア、元に戻す/やり直しを行います。
• マーカー - セッションマーカーを作成、リストアップ、ナビゲートします。
• トランスポート制御 - 再生、停止、録音、再生制御を行います。
• 視覚的分析 - 波形画像を生成し、オーディオコンテンツを分析します（オンセット、ピーク、無音検出）。
• 生のPTSLアクセス - 高度なユースケースのためにカスタムPTSLコマンドを送信します。
• 診断 - PTSL接続ステータスをテストして検証します。

既知の制限事項

• MIDIクリップ: タイムラインインデックスはオーディオクリップのみをキャプチャします。PTSL APIの制限により、MIDIクリップの位置を照会することはできません。MIDIクリップはクリップリストに表示されますが、そのタイムライン位置は利用できません。

セーフティ機能

このサーバーは、Pro Toolsセッションを保護するために細かい権限システムを使用しています。デフォルトでは、安全なオーディオ分析が有効な読み取り専用モードで実行されます。

デフォルトの権限（設定不要）

常に許可される操作:

• 読み取り操作（照会、トラックリスト、クリップ情報、セッション情報）
• 再生制御（再生、停止、切り替え）
• UI状態の変更（ミュート/ソロ、タイムライン選択、編集ツール）
• クリップボードへのコピー（破壊的ではない）
• 一時ディレクトリへのオーディオエクスポート（オーディオ分析を有効にする）

デフォルトでブロックされる操作（ALLOW_WRITESを設定する必要があります）:

• マーカーの作成/編集（memory）
• カット/貼り付け/クリア操作（clipboard）
• カスタムパスへのエクスポート（export）
• トラックの作成/削除（track_structure）
• セッションの保存/開く（session）
• 録音（recording）

書き込み操作の有効化

ALLOW_WRITES環境変数を使用して、特定の権限グループを有効にします。

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "protools": {
      "command": "node",
      "args": ["/absolute/path/to/protools-mcp-server/dist/index.js"],
      "env": {
        "PTSL_PROTO_PATH": "/absolute/path/to/PTSL.proto",
        "ALLOW_WRITES": "memory,clipboard"
      }
    }
  }
}

コマンドライン:

# マーカーとクリップボードの編集を許可
ALLOW_WRITES=memory,clipboard PTSL_PROTO_PATH=/path/to/PTSL.proto node dist/index.js

# すべての操作を許可（注意して使用）
ALLOW_WRITES=all PTSL_PROTO_PATH=/path/to/PTSL.proto node dist/index.js

権限グループ

グループ	操作	リスクレベル
memory	マーカーの作成/編集/削除	🟢 安全
export	任意の場所にオーディオをエクスポート	🟡 中程度
clipboard	オーディオのカット/貼り付け/クリア	🟠 破壊的
track_structure	トラックの作成/削除	🟠 破壊的
session	セッションの保存/開く/閉じる	🔴 高
recording	オーディオの録音	🔴 高

AI用のオーディオ分析

ClaudeなどのAIモデルは直接オーディオを聴くことができないため、このサーバーはいくつかの方法を提供して、AIが視覚的およびテキスト的な分析を通じてオーディオコンテンツを「理解」できるようにします。analyze_audioツールは、Pro Toolsセッションの任意の領域をバウンスし、複数の方法で分析することができます。

分析モード

孤立モード: トラックをソロして、領域をバウンスし、分析を生成します。個々の楽器やボーカルを調べるのに最適です。

ミックスモード: Pro Toolsで現在聞こえる完全なミックスを分析し、すべてのミュート/ソロ状態、オートメーション、およびプラグイン処理を考慮します。

分析タイプ

1. 波形可視化

時間経過に伴う振幅を持つ高解像度の波形画像を生成します。可視化には以下が含まれます。

• ステレオチャンネルが別々に表示されます（上/下）
• Pro Toolsタイムコード形式のタイムマーカー（HH:MM:SS:FF）
• dB単位の振幅スケール（-24dBから0dB基準）
• 視覚的な方向付けのためのグリッド線

ユースケース: クリップの境界を特定し、ダイナミクスを確認し、無音または大音量の部分を見つけ、リズムパターンを理解します。

波形出力の例 (4096x2048ピクセル):

2. スペクトログラム可視化

時間経過に伴う周波数コンテンツを示す周波数スペクトル可視化を生成します。色は各周波数での振幅を表します。

ユースケース: 周波数範囲を特定し、高調波を見つけ、音楽的な要素と打楽器的な要素を確認し、共振を検出します。

スペクトログラム出力の例 (2048x1024ピクセル):

3. ピーク/RMS分析

選択したオーディオ領域の全体的な振幅統計を提供します。

ユースケース: 全体的なレベルを確認し、平均音量を理解し、ヘッドルームを検証します。

ピーク分析出力の例:

**全体的なオーディオ統計:**
RMSレベル: -27.46 dB
ピークレベル: -12.09 dB

これは、選択した領域全体の平均音量（RMS）と最大ピークを表します。

4. イベント/オンセット検出

Aubioライブラリを使用して、トランジェントとリズミックなイベント（ドラムヒット、ノートのアタックなど）を検出します。

ユースケース: 編集のためのヒットポイントを見つけ、リズムを理解し、マーカー配置のためのビートを特定します。

イベント検出出力の例:

**イベント/オンセット分析**

モード: ミックス
時間範囲: 00:00:10:00 - 00:00:15:00
検出されたイベント: 24

**オンセット時間:**
1. 00:00:10:02 (サンプル 480,960)
2. 00:00:10:17 (サンプル 488,160)
3. 00:00:11:02 (サンプル 495,360)
4. 00:00:11:17 (サンプル 502,560)
...

5. 無音検出

構成可能な閾値と持続時間に基づいて、無音または低レベルのオーディオ期間を検出します。

ユースケース: テイク間のギャップを見つけ、クリーンアップの機会を特定し、セクションの境界を検出します。

パラメータ:

• silence_threshold_db: 振幅閾値（デフォルト: -40dB）
• silence_min_duration: 最小持続時間（秒）（デフォルト: 0.3秒）

無音検出出力の例:

**無音分析**

モード: 孤立（トラック: バースリードボーカル）
時間範囲: 00:00:00:00 - 00:01:00:00
閾値: -40dB, 最小持続時間: 0.3秒
検出された無音期間: 8

**無音期間:**
1. 00:00:05:12 - 00:00:08:23 (3.37秒)
   サンプル: 259,200 - 421,440
2. 00:00:19:04 - 00:00:20:15 (1.50秒)
   サンプル: 915,840 - 988,800
...

6. 統合分析

利用可能なすべてのテキストベースの分析（ピーク、イベント、および無音）を1つの操作で実行し、オーディオコンテンツの包括的な概要を提供します。

ユースケース: 不慣れなオーディオの初期探索、編集決定を行う前に完全なコンテキストを取得します。

7. 生のオーディオ配信

領域をWAV形式にバウンスし、base64エンコードされたデータとして返します（MCPメッセージサイズ制限により、最大10秒まで）。

ユースケース: アーカイブ、外部処理、または将来のオーディオ対応AIモデルでの使用。

注意: Claudeや現在のほとんどのAIモデルは、直接オーディオファイルを分析することはできません。このモードは、将来の互換性と外部ツールの統合のために含まれています。

必要条件

• ffmpeg: 波形、スペクトログラム、ピーク、および無音検出に必要です。
  • インストール: brew install ffmpeg (macOS) または apt-get install ffmpeg (Linux)
• aubio: イベント/オンセット検出に必要です。
  • インストール: brew install aubio (macOS) または apt-get install aubio (Linux)

サーバーは、利用可能なツールを自動的に検出し、必要な依存関係が欠落している場合は適切なエラーメッセージを提供します。

⚠️ 法律上の注意

このプロジェクトには、AvidのSDKからのPTSL.protoファイルは含まれていません。

ライセンス制限により、ユーザーはAvidからPro Tools Scripting Library SDKをダウンロードし、独自のPTSL.protoファイルを提供する必要があります。SDKは登録済みのAvid開発者向けに提供されています。

SDKを取得するには:

1. avid.comでAvid開発者アカウントを登録します。
2. Pro Tools Scripting Library SDKをダウンロードします。
3. SDKからPTSL.protoを抽出します。

前提条件

• Node.js >= 18
• Pro Tools 2024.10以降
• Pro Tools Scripting Library SDK（PTSL.proto用）
• Pro Toolsが実行中である必要があります。

PTSLサーバー

Avidのドキュメントによると、Pro Toolsが実行中のときにPTSLサーバーは自動的に利用可能になります - 特別な設定は必要ありません。サーバーはデフォルトでlocalhost:31416で実行されます。

注意: 接続を試みる前に、Pro Toolsが実際に実行中であることを確認してください！

🚀 クイックスタート

5分で起動して実行できます。

1. PTSL SDKを取得する - Avidからダウンロードし、PTSL.protoを抽出します。
2. クローンしてビルドする:

   git clone <repository-url>
   cd protools-mcp-server
   npm install
   npm run build
   

3. 接続をテストする:

   npm run test-cli -- /path/to/PTSL.proto
   

4. Claude Desktopを設定する - claude_desktop_config.jsonに追加します。

   {
     "mcpServers": {
       "protools": {
         "command": "node",
         "args": ["/absolute/path/to/protools-mcp-server/dist/index.js"],
         "env": {
           "PTSL_PROTO_PATH": "/absolute/path/to/PTSL.proto"
         }
       }
     }
   }
   

5. Claude Desktopを再起動して、AIでPro Toolsを使用し始めましょう！

注意: サーバーはデフォルトで読み取り専用モードで起動し、セッションへの変更を防止します。これは、探索や学習に最適です。準備ができたら、セーフティ機能セクションを参照して、書き込み操作を有効にしてください。

📦 インストール

npm install
npm run build

接続のテスト

MCPサーバーを使用する前に、Pro Toolsに接続できることをテストします。

# PTSL.protoファイルのパスを指定してテストCLIを実行
npm run test-cli -- /path/to/PTSL.proto

# 例（SDKがptsl_sdkディレクトリにある場合）
npm run test-cli -- ptsl_sdk/Source/PTSL.proto

テストCLIは以下のことを行います。

1. localhost:31416のPTSLサーバーに接続します。
2. 接続を登録します。
3. セッション情報を照会します。
4. トラックをリストアップします。

Pro Toolsが実行中でないか、PTSLが有効になっていない場合、接続エラーが表示されます。

💻 使用例

Claude Desktop（推奨）

Claude DesktopでMCPサーバーを使用するには、Claude Desktopの設定ファイルに追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "protools": {
      "command": "node",
      "args": ["/absolute/path/to/protools-mcp-server/dist/index.js"],
      "env": {
        "PTSL_PROTO_PATH": "/absolute/path/to/PTSL.proto"
      }
    }
  }
}

例（macOS）:

{
  "mcpServers": {
    "protools": {
      "command": "node",
      "args": ["/Users/username/protools-mcp-server/dist/index.js"],
      "env": {
        "PTSL_PROTO_PATH": "/Users/username/protools-mcp-server/ptsl_sdk/Source/PTSL.proto"
      }
    }
  }
}

設定を追加した後:

1. Claude Desktopを再起動します。
2. Pro Toolsが実行中であることを確認します。
3. ClaudeにPro Toolsのタスクを依頼しましょう！

Claude Cowork（実験的/未検証）

⚠️ 注意: Coworkコネクタは十分にテストされていません。Claude Desktopを推奨します。

Claude CoworkはHTTPSを必要とします。サーバーはローカル開発用に自己署名SSL証明書を使用します。

1. HTTPSサーバーを起動する:

   export PTSL_PROTO_PATH=/path/to/PTSL.proto
   ./start-cowork.sh
   

2. Claude Coworkで:

   • 「カスタムコネクタを追加」をクリックします。
   • 名前: Pro Tools
   • リモートMCPサーバーURL: https://localhost:3000/sse
   • 「追加」をクリックします。
   • セキュリティ警告を受け入れます（自己署名証明書はローカルホストでは安全です）。

カスタムポート:

PORT=3443 PTSL_PROTO_PATH=/path/to/PTSL.proto npm run start:http
# 次に、https://localhost:3443/sse を使用します。

具体的な使用例

ClaudeにPro Toolsセッションに関する以下のようなことを依頼することができます。

分析とナビゲーション:

• "ボーカルトラックの1分から1分30秒までの波形を表示して"
• "リードボーカルトラックで1秒以上の無音部分をすべて見つけて"
• "8小節から16小節の間のキックトラックのドラムヒットはどこにあるか"
• "30秒から1分の間のタイムライン上にあるクリップは何ですか"

編集と整理:

• "リードボーカルトラックのすべてのボーカルフレーズにマーカーを作成して"
• "名前が 'Guitar Solo 3' のクリップを見つけて選択して"
• "すべてのドラムトラックをミュートして"
• "選択範囲をコピーして2分の位置に貼り付けて"

セッション管理:

• "現在のセッション名とサンプルレートは何ですか"
• "セッション内のすべてのトラックをリストアップして"
• "セッションを保存して"

再生制御:

• "1分から1分30秒まで再生して"
• "再生を停止して"
• "録音を開始して"

利用可能なツール

MCPサーバーは、複数のカテゴリにわたる36のツールを提供します。

セッション管理

• get_session_info - 現在のセッション名、パス、およびサンプルレートを取得します。
• get_session_length - セッションの総時間を取得します。
• get_session_overview - 包括的なセッション情報を取得します。
• save_session - 現在のセッションを保存します。

トラック管理

• get_track_list - すべてのトラックとそのプロパティをリストアップします。
• select_tracks - 名前またはパターンでトラックを選択します。
• set_track_mute - トラックをミュート/ミュート解除します。
• set_track_solo - トラックをソロ/ソロ解除します。

タイムラインとクリップ

• refresh_pro_tools_index - タイムラインキャッシュをPro Toolsセッションと同期します。
• get_timeline_tracks - ページネーションでトラックを閲覧します。
• get_timeline_clips - ページネーションでクリップを閲覧します。
• search_timeline - 名前でトラック/クリップを検索します。
• get_clip_list - クリップビン内のクリップをリストアップします。
• select_clip_on_timeline - タイムライン上の特定のクリップを選択します。
• get_timeline_selection - 現在のタイムライン選択範囲を取得します。
• set_timeline_selection - タイムライン選択範囲を特定の時間範囲に設定します。

トランスポート制御

• play - 再生を開始します。
• stop - 再生/録音を停止します。
• toggle_play - 再生/停止を切り替えます。
• record - 録音を開始します。
• set_playback_mode - ループ/ダイナミックトランスポートモードを設定します。

編集操作

• cut - 選択したオーディオをカットします。
• copy - 選択したオーディオをコピーします。
• paste - クリップボードから貼り付けます。
• clear - 選択したオーディオをクリア/削除します。
• undo - 最後の操作を元に戻します。
• redo - 最後に元に戻した操作をやり直します。

マーカー

• get_markers - すべてのメモリ位置/マーカーをリストアップします。
• create_marker - 指定した時間に新しいマーカーを作成します。
• edit_marker - 既存のマーカーの名前/時間を変更します。
• delete_marker - 特定のマーカーを削除します。
• delete_all_markers - すべてのマーカーを削除します。
• select_marker - マーカーに移動して選択します。

オーディオ分析

• analyze_audio - 複数の分析タイプでオーディオ領域を分析します。
  • 波形可視化
  • スペクトログラム（周波数分析）
  • ピーク/RMS振幅データ
  • イベント/オンセット検出（aubioが必要）
  • 無音検出
  • 統合分析
  • 生のオーディオ配信

高度な機能/診断

• ptsl_command - 生のPTSLコマンドを直接送信します。
• sample_ptsl_responses - サンプルPTSL APIレスポンスを表示します。

開発

# 依存関係をインストール
npm install

# TypeScriptをビルド
npm run build

# PTSL接続をテスト
npm run test-cli -- /path/to/PTSL.proto

# MCPサーバーをテスト
export PTSL_PROTO_PATH=/path/to/PTSL.proto
./test-mcp.sh
./test-tools.sh

# 書き込み保護のセーフティメカニズムをテスト
node test-write-protection.js                           # 読み取り専用モードをテスト
ALLOW_WRITE_OPERATIONS=true node test-write-protection.js  # 書き込みを有効にしてテスト

プロジェクト構造

protools-mcp-server/
├── src/
│   ├── index.ts              # MCPサーバーのエントリポイント
│   ├── test-cli.ts           # PTSL接続のテストCLI
│   ├── grpc/
│   │   ├── client.ts         # PTSL gRPCクライアントラッパー
│   │   └── commands.ts       # CommandId列挙型
│   ├── tools/                # MCPツール（未完成）
│   └── resources/            # MCPリソース（未完成）
├── package.json
├── tsconfig.json
└── README.md

アーキテクチャ

ユーザーリクエスト (Claude/AI)
    ↓
MCPサーバー (TypeScript - このプロジェクト)
    ↓
gRPCクライアント (ユーザーのPTSL.protoから生成)
    ↓
Pro Tools PTSLサーバー (localhost:31416)
    ↓
Pro Toolsアプリケーション

プロジェクトの状態とロードマップ

うまく機能する部分

• ✅ 基本的なセッション管理（情報、保存、ナビゲーション）
• ✅ トラック制御（リストアップ、選択、ミュート、ソロ）
• ✅ タイムラインナビゲーションと検索（オーディオクリップのみ）
• ✅ トランスポート制御（再生、停止、録音）
• ✅ 基本的な編集操作（カット、コピー、貼り付け、クリア、元に戻す/やり直し）
• ✅ マーカー管理（作成、リストアップ、編集、削除、ナビゲート）
• ✅ オーディオ分析（波形、スペクトログラム、ピーク、イベント、無音検出）
• ✅ タイムライン選択管理

既知の問題と制限事項

• ⚠️ MIDIクリップのタイムライン位置をインデックス化できません（PTSL APIの制限）
• ⚠️ 一部の高度なPro Tools機能がまだPTSLを介して公開されていません
• ⚠️ オーディオ分析には外部依存関係（ffmpeg、aubio）が必要です
• ⚠️ 生のオーディオ配信はMCPメッセージサイズの制約により最大10秒までに制限されています

将来的な潜在的な機能強化

• 🔮 プラグインパラメータの制御
• 🔮 オートメーションの読み取り/書き込み
• 🔮 センド/オークスルーティングの管理
• 🔮 I/O設定
• 🔮 ミキサースナップショット
• 🔮 バッチ処理操作
• 🔮 セッションテンプレートの作成
• 🔮 拡張MIDIサポート（PTSL APIが拡張された場合）

トラブルシューティング

"Failed to connect to PTSL server"

• Pro Toolsが実行中であることを確認してください。
• Pro Toolsの設定でPTSLが有効になっていることを確認してください。
• ポート31416を使用している他のアプリケーションがないことを確認してください。

"Request refused. Use the RegisterConnection command first"

• これは通常、Pro Toolsが実行中でないことを意味します。
• Pro Toolsを再起動してみてください。

"SDK_VersionMismatch: The client and host interface versions are incompatible"

• 正しいPTSL.protoバージョンを使用していることを確認してください。
• protoバージョンはPro Toolsのバージョンと一致する必要があります。
• 必要に応じて、Avidから一致するSDKをダウンロードしてください。

Protoファイルのエラー

• 正しいPTSL.protoバージョンを使用していることを確認してください。
• protoファイルはPro Toolsのバージョンと一致する必要があります。
• 必要に応じて、Avidから最新のSDKをダウンロードしてください。

コントリビューション

コントリビューションは大歓迎です！以下の方法で支援できます。

問題の報告

• GitHub Issuesを使用して、バグを報告したり、機能要求を行ったりしてください。
• Pro Toolsのバージョン、PTSL SDKのバージョン、およびOSの詳細を含めてください。
• 動作に関する問題を報告する場合は、セッションの詳細を提供してください。
• 該当する場合は、エラーメッセージとログを含めてください。

コードのコントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更を加え、十分にテストします。
4. 既存のコードスタイル（TypeScript、ESLint）に従ってください。
5. 必要に応じてドキュメントを更新します。
6. 変更をコミットします (git commit -m 'Add amazing feature')。
7. ブランチにプッシュします (git push origin feature/amazing-feature)。
8. プルリクエストを作成します。

開発ガイドライン

• すべての新しいツールは、src/tools/内の既存のツール構造に従う必要があります。
• 適切なエラーハンドリングと検証を追加してください。
• 公開APIにはJSDocコメントを含めてください。
• 可能な場合は、実際のPro Toolsセッションでテストしてください。
• 新しい機能を追加する場合は、READMEを更新してください。

テスト

PRを提出する前に、以下を確認してください。

npm run build          # ビルドが成功すること
npm run test-cli       # PTSL接続が機能すること
./test-mcp.sh          # MCPサーバーが初期化されること
./test-tools.sh        # ツールの登録が機能すること

📄 ライセンス

MITライセンス - LICENSEファイルを参照してください。

謝辞

Pro ToolsとPTSLはAvid Technology, Inc.の商標です。これは独立したオープンソースプロジェクトであり、Avidによって承認または支援されているわけではありません。

サポートとコミュニティ

• 問題報告: GitHub Issuesを使用して、バグを報告したり、機能要求を行ったりしてください。
• ディスカッション: GitHub Discussionsで質問をしたり、ワークフローを共有したりしてください。
• PTSLドキュメント: SDKからのAvidの公式PTSLドキュメントを参照してください。

このプロジェクトは実験的でコミュニティ主導のものです。コードを提供したり、問題を報告したり、ユースケースを共有したりすることで、このプロジェクトをより良くする手助けをしてください！