🚀 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 文件。