Sound Effects

🚀 MCP 聲音工具

MCP 聲音工具是一個基於 Model Context Protocol (MCP) 的實現，專為 Cursor AI 及其他 MCP 兼容環境打造。它能播放各類聲音效果，為編碼過程增添音頻反饋，顯著提升互動體驗。

🚀 快速開始

MCP 聲音工具能在 Cursor AI 和其他 MCP 兼容環境中播放聲音效果，為你的編碼體驗增添音頻反饋。以下是簡單的使用步驟：

1. 安裝工具（具體安裝方式見下方“📦 安裝指南”）。
2. 添加聲音文件到指定路徑（見“💻 使用示例”）。
3. 啟動 MCP 服務器。
4. 在 Cursor 中進行配置。

✨ 主要特性

• 豐富音效：可播放完成、錯誤、通知等各種事件的聲音效果。
• 標準集成：採用 Model Context Protocol (MCP) 實現標準化集成。
• 跨平臺支持：支持 Windows、macOS、Linux 等多種操作系統。
• 可配置性：聲音效果支持用戶自定義配置。

📦 安裝指南

Python 版本兼容性

此包經過測試，支持 Python 3.8 - 3.11。若使用 Python 3.12+ 時遇到錯誤（特別是 BrokenResourceError 或 TaskGroup 異常），請嘗試使用更早的 Python 版本。

推薦：使用 pipx 安裝

推薦使用 pipx 進行安裝，它會在隔離環境中安裝包，並將命令添加到全局 PATH 中：

# 先安裝 pipx（如果尚未安裝）
python -m pip install --user pipx
python -m pipx ensurepath

# 安裝 mcp-sound-tool
pipx install mcp-sound-tool

這種方法確保工具擁有自己的隔離環境，避免與其他包發生衝突。

替代：使用 pip 安裝

你也可以直接使用 pip 進行安裝：

pip install mcp-sound-tool

從源代碼安裝

如果你有源代碼，可以這樣安裝：

git clone https://github.com/yourusername/mcp-sound-tool.git
cd mcp-sound-tool
pip install -e .

💻 使用示例

基礎用法

添加聲音文件

將聲音文件放置在以下路徑中：

• Windows：%APPDATA%\mcp-sound-tool\resources\sounds
• macOS：~/Library/Application Support/mcp-sound-tool/resources/sounds
• Linux：~/.config/mcp-sound-tool/resources/sounds

運行 MCP 服務器

在終端或命令提示符中運行以下命令啟動 MCP 服務器：

mcp-sound-server

默認情況下，服務器將在端口 5005 上運行。

在 Cursor 中配置

編輯你的配置文件（通常是 ~/.config/cursor/settings.json），添加以下內容到插件部分：

{
  "plugins": {
    "mcp-sound": true
  }
}

然後重啟 Cursor。

高級用法

聲音 MCP 使用指南：AI 模型

定義聲音事件類型

• 完成聲音：在操作完成時播放聲音。
• 錯誤聲音：在檢測到錯誤時播放聲音。
• 通知聲音：在需要用戶注意時播放聲音。

配置示例

編輯你的配置文件（通常是 ~/.config/mcp-sound_TOOL/config.json），添加以下內容：

{
  "sounds": {
    "completion": "assets/complete.mp3",
    "error": "assets/error.mp3",
    "notification": "assets/notification.mp3"
  }
}

然後重啟 MCP 服務。

🔧 技術細節

安裝開發依賴

在終端或命令提示符中運行以下命令安裝開發依賴：

pip install -e ".[dev]"

運行測試

運行以下命令執行測試：

pytest tests/

🙏 致謝

• SIAM-TheLegend 創建了最初的 sound-mcp JavaScript 實現，啟發了這個 Python 版本。
• MCP 協議開發人員創建了強大的 AI 工具交互標準。
• 貢獻了測試和文檔的各位貢獻者。

📄 許可證

此項目根據 MIT 許可證發佈，具體許可證內容請參見 LICENSE 文件。