🚀 MCP 声音工具
这是一个基于 Model Context Protocol (MCP) 的实现，旨在为 Cursor AI 以及其他 MCP 兼容环境提供声音效果播放功能。借助这个 Python 实现，用户能够在编码过程中获得音频反馈，从而打造更加互动的编码体验。
🚀 快速开始
本工具能为你的编码环境增添音频反馈，以下是快速使用步骤：
- 安装工具：根据不同需求选择合适的安装方式。
- 添加声音文件：将声音文件放置到对应系统的指定路径。
- 启动服务：运行 MCP 服务器。
- 配置应用：在 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/
📄 许可证
此项目根据 MIT 许可证发布，具体许可证内容请参见 LICENSE 文件。
🙏 致谢
- SIAM-TheLegend 创建了最初的 sound-mcp JavaScript 实现，启发了这个 Python 版本。
- MCP 协议开发人员创建了强大的 AI 工具交互标准。
- 贡献了测试和文档的各位贡献者。