MCP Make Sound

🚀 🔊 MCP Make Sound

MCP Make Sound 是一個基於模型上下文協議（MCP）的服務器，專為 macOS 系統打造，具備全面的聲音播放功能。它允許 AI 助手及其他 MCP 客戶端播放系統聲音、進行文本轉語音，還能播放自定義音頻文件，為用戶帶來豐富的音頻反饋體驗。

🚀 快速開始

運行服務器

啟動 MCP 服務器：

npm start

若要在開發環境中實現自動重新加載：

npm run dev

✨ 主要特性

• 🔔 簡單聲音方法：預配置了信息、警告和錯誤提示音。
• 🎵 自定義系統聲音：可播放 14 種內置的 macOS 系統聲音。
• 🗣️ 文本轉語音：能將文本轉換為語音，且支持自定義語音。
• 📁 文件播放：可播放磁盤上的自定義音頻文件。
• 🚀 基於 TypeScript 和 MCP SDK 構建。
• 🪶 輕量級設計，易於集成。

📦 安裝指南

1. 克隆此倉庫：

git clone <repository-url>
cd mcp-make-sound

2. 安裝依賴項：

npm install

3. 構建項目：

npm run build

💻 使用示例

基礎用法

示例：Claude 與 Warp 終端集成

以下是如何設置 MCP 聲音服務器，以便在 Warp 終端中 AI 任務完成時提供音頻反饋：

配置規則：“當 AI 任務完成時，使用 mcp - make - sound 播放聲音。MCP 支持錯誤、信息和成功三種狀態。根據 AI 任務的結果播放相應的聲音。”

通過此設置，你可以：

• 🔔 當任務成功完成時，聽到悅耳的提示音。
• ⚠️ 當出現警告或部分完成時，收到警報聲。
• ❌ 當出現錯誤或失敗時，獲得清晰的音頻反饋。

音頻反饋能讓你在專注於其他工作的同時，第一時間知曉 AI 助手何時完成請求處理。

高級用法

可用工具

服務器提供了四種工具：

簡單聲音方法（舊版）

• play_info_sound
  • 描述：播放信息類系統聲音。
  • 參數：無。
  • 聲音：Glass.aiff
• play_warning_sound
  • 描述：播放警告類系統聲音。
  • 參數：無。
  • 聲音：Purr.aiff
• play_error_sound
  • 描述：播放錯誤類系統聲音。
  • 參數：無。
  • 聲音：Sosumi.aiff

高級聲音方法

• play_sound
  • 描述：可通過自定義參數播放各種類型的聲音。
  • 參數：
    • type（必需）："system"、"tts" 或 "file"。
    • 根據類型的不同還有其他附加參數（見以下示例）。

系統聲音

播放 14 種內置的 macOS 系統聲音：

{
  "name": "play_sound",
  "arguments": {
    "type": "system",
    "name": "Basso"
  }
}

可用的系統聲音： Basso、Blow、Bottle、Frog、Funk、Glass、Hero、Morse、Ping、Pop、Purr、Sosumi、Submarine、Tink

文本轉語音

將文本轉換為語音，並可選擇語音：

{
  "name": "play_sound",
  "arguments": {
    "type": "tts",
    "text": "Hello, this is a test message",
    "voice": "Albert"
  }
}

不指定語音（使用系統默認語音）：

{
  "name": "play_sound",
  "arguments": {
    "type": "tts",
    "text": "Task completed successfully"
  }
}

支持的語音：

• 英語：Albert、Alice、Bad News、Bahh、Bells、Boing、Bruce、Bubbles、Cellos、Daniel、Deranged、Fred、Good News、Hysterical、Junior、Kathy、Pipe Organ、Princess、Ralph、Trinoids、Whisper、Zarvox
• 國際語音：Anna、Amélie、Daria、Eddy、Fiona、Jorge、Juan、Luca、Marie、Moira、Nora、Rishi、Samantha、Serena、Tessa、Thomas、Veena、Victoria、Xander、Yelda、Zosia

注意：如果指定了不支持的語音，系統將自動回退到默認語音並繼續播放。

自定義音頻文件

播放磁盤上的音頻文件：

{
  "name": "play_sound",
  "arguments": {
    "type": "file",
    "path": "/Users/username/Music/notification.mp3"
  }
}

支持常見的音頻格式：.aiff、.wav、.mp3、.m4a 等。

🔒 安全與限制

• 系統聲音：僅允許使用 14 種官方的 macOS 系統聲音。
• 文本轉語音：
  • 文本最大限制為 1000 個字符。
  • 支持語音驗證，若指定不支持的語音，將優雅地回退到系統默認語音。
  • 為確保安全，精心篩選了 43 種以上支持的語音。
• 文件播放：需要絕對路徑，並驗證文件是否存在。

🔗 與 MCP 客戶端集成

此服務器可與任何兼容 MCP 的客戶端集成，例如：

• 🤖 Claude Desktop
• 🛠️ 自定義 MCP 客戶端
• 🧠 支持 MCP 的 AI 助手

MCP 配置示例

將以下內容添加到你的 MCP 客戶端配置中：

{
  "mcp-make-sound": {
    "command": "node",
    "args": [
      "/Users/nocoo/Workspace/mcp-make-sound/dist/index.js"
    ],
    "env": {},
    "working_directory": "/Users/nocoo/Workspace/mcp-make-sound",
    "start_on_launch": true
  }
}

示例工具調用：

{
  "name": "play_info_sound",
  "arguments": {}
}

{
  "name": "play_sound",
  "arguments": {
    "type": "system",
    "name": "Hero"
  }
}

📚 詳細文檔

項目結構

mcp-make-sound/
├── src/
│   ├── index.ts          # 主服務器實現
│   └── __tests__/        # 單元測試
│       └── sound.test.ts # 聲音系統測試
├── dist/                 # 編譯後的 JavaScript 輸出
├── eslint.config.js      # ESLint 配置
├── vitest.config.ts      # Vitest 測試配置
├── package.json          # 項目配置
├── tsconfig.json         # TypeScript 配置
└── README.md            # 本文件

腳本

構建與運行

• npm run build - 🔨 將 TypeScript 編譯為 JavaScript。
• npm start - ▶️ 運行編譯後的服務器。
• npm run dev - 🔄 開發模式，支持自動重新構建和重啟。
• npm run kill - 🛑 停止所有正在運行的 MCP 服務器實例。

代碼質量與測試

• npm run lint - 🔍 檢查代碼風格和錯誤。
• npm run lint:fix - 🔧 修復可自動修復的代碼風格問題。
• npm run test - 🧪 在監視模式下運行測試。
• npm run test:run - ✅ 運行一次測試。
• npm run test:ui - 🎛️ 以交互式 UI 運行測試。

工作原理

1. 服務器使用官方 SDK 實現 MCP 協議。
2. 它提供了四種工具，用於實現不同的聲音功能。
3. 當調用工具時，它會使用 macOS 命令：
   • afplay 用於播放音頻文件（系統聲音和自定義文件）。
   • say 用於文本轉語音合成。
4. 系統聲音位於 /System/Library/Sounds/。
5. 服務器通過標準輸入輸出（stdio）進行通信。

🔧 技術細節

• 🔌 傳輸方式：標準輸入輸出（stdio）
• 📡 協議：模型上下文協議（MCP）
• 🎧 音頻後端：macOS 的 afplay 和 say 命令
• 🎵 聲音文件：系統 .aiff 文件、自定義音頻文件和合成語音

🚨 錯誤處理

服務器包含全面的錯誤處理機制：

• 驗證工具名稱和參數。
• 處理 afplay 和 say 命令失敗的情況。
• 驗證每種聲音類型所需的參數。
• 向客戶端返回適當的錯誤消息。
• 在出現錯誤時優雅地關閉服務器。

📄 許可證

本項目採用 MIT 許可證。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

🎼 聲音功能

簡單方法（舊版）

• 🔔 信息：Glass.aiff - 悅耳的提示音。
• ⚠️ 警告：Purr.aiff - 溫和的警報聲。
• ❌ 錯誤：Sosumi.aiff - 獨特的錯誤提示音。

高級方法（play_sound）

• 🎵 14 種系統聲音：所有內置的 macOS 系統聲音均可使用。
• 🗣️ 50 多種文本轉語音語音：支持多種語言和角色語音。
• 📁 自定義文件：支持 .aiff、.wav、.mp3、.m4a 等多種音頻格式。

這些功能為任何應用需求提供了豐富的音頻反饋選項。