Protools MCP Server

🚀 Pro Tools MCP 服務器

Pro Tools MCP 服務器是一個基於 MCP（模型上下文協議）的服務器，它允許像 Claude 這樣的 AI 助手通過 PTSL（Pro Tools 腳本庫）gRPC API 來控制 Pro Tools。

⚠️ 重要提示

這是一個正在開發中的實驗性項目，並非所有 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 啦！

注意：服務器默認以只讀模式啟動，這可以防止對會話進行任何修改，非常適合用於探索和學習。如果需要啟用寫操作，請參考 安全特性 部分。

✨ 主要特性

該服務器為 AI 助手提供了以下功能：

• 會話管理 - 查詢會話信息、保存會話、獲取全面的會話概述。
• 時間線導航 - 分頁瀏覽軌道和剪輯、按名稱搜索、在時間線上導航（僅適用於音頻剪輯）。
• 軌道控制 - 列出、選擇、靜音、獨奏和管理軌道。
• 剪輯管理 - 在時間線上查找和處理音頻剪輯。
• 編輯操作 - 對時間線選擇進行剪切、複製、粘貼、清除、撤銷/重做操作。
• 標記管理 - 創建、列出和導航會話標記。
• 傳輸控制 - 播放、停止、錄製和控制播放。
• 視覺分析 - 生成波形圖像並分析音頻內容（起始點、峰值、靜音檢測）。
• 原始 PTSL 訪問 - 發送自定義 PTSL 命令以實現高級用例。
• 診斷功能 - 測試和驗證 PTSL 連接狀態。

已知限制

• MIDI 剪輯：由於 PTSL API 的限制，時間線索引僅能捕獲音頻剪輯，無法查詢 MIDI 剪輯的位置。雖然可以在剪輯列表中看到 MIDI 剪輯，但無法獲取其在時間線上的位置。

📦 安裝指南

npm install
npm run build

💻 使用示例

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 秒”。
  • “停止播放”。
  • “開始錄製”。

📚 詳細文檔

安全特性

服務器採用了細粒度權限系統來保護你的 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.3s）

示例靜音檢測輸出：

**靜音分析**

模式：隔離（軌道：主音軌）
時間範圍：00:00:00:00 - 00:01:00:00
閾值：-40dB，最小持續時間：0.3s
檢測到的靜音時段：8

**靜音時段：**
1. 00:00:05:12 - 00:00:08:23（3.37s）
   樣本：259,200 - 421,440
2. 00:00:19:04 - 00:00:20:15（1.50s）
   樣本：915,840 - 988,800
...

6. 綜合分析 一次性運行所有可用的基於文本的分析（峰值、事件和靜音），提供音頻內容的全面概述。

用例：初步探索不熟悉的音頻、在進行編輯決策之前獲取完整上下文。

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）

服務器將自動檢測哪些工具可用，並在缺少所需依賴項時提供相應的錯誤消息。

可用工具

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 應用程序

項目狀態與路線圖

運行良好的功能

• ✅ 基本會話管理（信息、保存、導航）
• ✅ 軌道控制（列出、選擇、靜音、獨奏）
• ✅ 時間線導航和搜索（僅適用於音頻剪輯）
• ✅ 傳輸控制（播放、停止、錄製）
• ✅ 基本編輯操作（剪切、複製、粘貼、清除、撤銷/重做）
• ✅ 標記管理（創建、列出、編輯、刪除、導航）
• ✅ 音頻分析（波形、頻譜圖、峰值、事件、靜音檢測）
• ✅ 時間線選擇管理

已知問題與限制

• ⚠️ 由於 PTSL API 限制，無法對 MIDI 剪輯的時間線位置進行索引。
• ⚠️ 一些高級 Pro Tools 功能尚未通過 PTSL 公開。
• ⚠️ 音頻分析需要外部依賴項（ffmpeg、aubio）。
• ⚠️ 由於 MCP 消息大小限制，原始音頻傳輸限制為 10 秒。

潛在的未來增強功能

• 🔮 插件參數控制
• 🔮 自動化讀寫
• 🔮 發送/輔助路由管理
• 🔮 輸入/輸出配置
• 🔮 混音器快照
• 🔮 批量處理操作
• 🔮 會話模板創建
• 🔮 擴展 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 版本和操作系統詳細信息。
• 如果報告行為問題，請提供會話詳細信息。
• 適當時，包括錯誤消息和日誌。

貢獻代碼

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 文檔：參考 Avid SDK 中的官方 PTSL 文檔。

本項目是實驗性的且由社區驅動。通過貢獻代碼、報告問題或分享使用案例，幫助我們把項目變得更好！