MCP Sound Tool

一个实现模型上下文协议（MCP）的工具，用于在Cursor AI及其他兼容MCP环境中的播放音效。此Python实现提供了音频反馈，以增强更互动的编码体验。

特性

• 为各种事件（完成、错误、通知）播放音效
• 使用模型上下文协议（MCP）与Cursor及其他IDE进行标准化集成
• 跨平台支持（Windows, macOS, Linux）
• 可配置的音效

安装

Python 版本兼容性

该包已测试适用于Python 3.8-3.11版本。如果您使用Python 3.12+遇到错误（特别是BrokenResourceError或TaskGroup异常），请尝试使用较早版本的Python。

推荐：通过pipx安装

推荐使用pipx来安装mcp-sound-tool，这可以在隔离环境中安装包同时使命令全局可用：

# Install pipx if you don't have it
python -m pip install --user pipx
python -m pipx ensurepath

# Install mcp-sound-tool
pipx install mcp-sound-tool

这种方法确保了工具拥有自己的隔离环境，避免与其他包发生冲突。

替代方案：通过pip安装

您也可以直接使用pip安装：

pip install mcp-sound-tool

从源码安装

1. 克隆此仓库：

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

2. 从源码目录直接用pipx安装：

   pipx install .
   

   或者使用pip：

   pip install -e .
   

使用方法

添加声音文件

将您的声音文件放置于sounds目录中。预期的声音文件如下：

• completion.mp3 - 在代码生成后播放
• error.mp3 - 当发生错误时播放
• notification.mp3 - 用于一般通知

您可以在如freesound.org等网站上找到免费的声音效果。

运行MCP服务器

运行MCP服务器：

mcp-sound-tool

服务器将启动并通过stdio传输监听来自Cursor或其他兼容MCP客户端的事件。

在Cursor中的配置

要将此服务器与Cursor一起使用，请将其添加到您的MCP配置文件中：

对于macOS：

// ~/Library/Application Support/Cursor/mcp.json
{
  "mcpServers": {
    "sound": {
      "command": "mcp-sound-tool",
      "args": [],
      "type": "stdio",
      "pollingInterval": 5000,
      "startupTimeout": 10000,
      "restartOnFailure": true
    }
  }
}

对于Windows：

// %APPDATA%/Cursor/mcp.json
{
  "mcpServers": {
    "sound": {
      "command": "mcp-sound-tool",
      "args": [],
      "type": "stdio",
      "pollingInterval": 5000,
      "startupTimeout": 10000,
      "restartOnFailure": true
    }
  }
}

当使用pipx安装时，mcp-sound-tool命令会在您的PATH中可用，因此Cursor能够找到并执行它而无需指定完整路径。

音效MCP使用指南针对AI模型

这个MCP服务器为AI交互提供了音频反馈功能。设计目的是通过提供清晰的音频提示来增强用户体验，指示操作状态而不需要用户阅读文本。

何时使用声音反馈

AI代理应在适当时刻主动使用声音工具：

1. 成功提示音 (completion):

   • 在任务或命令成功完成后
   • 当一个重要操作成功完成时
   • 当确认用户的请求已被满足时

2. 错误提示音 (error):

   • 当命令失败或遇到错误时
   • 当警告用户出现问题时
   • 当无法按要求完成操作时

3. 通知提示音 (notification):

   • 当提醒用户注意重要信息时
   • 当提示用户注意或输入时
   • 对长时间运行的操作进行状态更新时

示例用法

# When a command completes successfully
@mcp.tool()
def execute_command(command):
    result = run_command(command)
    if result.success:
        play_sound("completion")  # Indicate success with audio
        return "Command executed successfully"
    else:
        play_sound("error")  # Indicate failure with audio
        return f"Error: {result.error_message}"

可用工具

1. play_sound(sound_type="completion", custom_sound_path=None): 播放声音效果
2. list_available_sounds(): 列出所有可用的声音文件
3. install_to_user_dir(): 将声音文件安装到用户的配置目录中

更多详情，请连接到MCP服务器并查看工具描述。

开发

开发时：

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

致谢

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

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。