Sound Effects

🚀 MCP 声音工具

这是一个基于 Model Context Protocol (MCP) 的实现，旨在为 Cursor AI 以及其他 MCP 兼容环境提供声音效果播放功能。借助这个 Python 实现，用户能够在编码过程中获得音频反馈，从而打造更加互动的编码体验。

🚀 快速开始

本工具能为你的编码环境增添音频反馈，以下是快速使用步骤：

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 模型

定义声音事件类型

1. 完成声音：在操作完成时播放声音。
2. 错误声音：在检测到错误时播放声音。
3. 通知声音：在需要用户注意时播放声音。

配置示例

编辑你的配置文件（通常是 ~/.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/

📄 许可证

此项目根据 MIT 许可证发布，具体许可证内容请参见 LICENSE 文件。

🙏 致谢

• SIAM-TheLegend 创建了最初的 sound-mcp JavaScript 实现，启发了这个 Python 版本。
• MCP 协议开发人员创建了强大的 AI 工具交互标准。
• 贡献了测试和文档的各位贡献者。