MCP 声音工具

模型上下文协议 (MCP) 实现，可为 Cursor AI 和其他兼容 MCP 的环境播放音效。此 Python 实现提供音频反馈，以实现更具互动性的编码体验。

特征

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

安装

Python 版本兼容性

此软件包已使用 Python 3.8-3.11 测试。如果您在使用 Python 3.12+ 时遇到错误（尤其是BrokenResourceError或TaskGroup异常），请尝试使用早期版本的 Python。

推荐：使用 pipx 安装

安装 mcp-sound-tool 的推荐方法是使用pipx ，它会在隔离的环境中安装包，同时使命令在全球范围内可用：

# 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

来自源

克隆此存储库：
git clone https://github.com/yourusername/mcp-sound-tool cd mcp-sound-tool
直接从源目录使用 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 一起使用，请将其添加到您的 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 将能够找到并执行它而无需指定完整路径。

适用于 AI 模型的合理 MCP 使用指南

此 MCP 服务器为 AI 交互提供音频反馈功能。它旨在通过提供清晰的音频提示来指示操作状态，而无需用户阅读文本，从而提升用户体验。

何时使用声音反馈

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

成功声音（ completion ） ：
- 任务或命令成功完成后
- 当重要操作成功完成时
- 当确认用户的请求已得到满足时
错误声音（ error ） ：
- 当命令失败或遇到错误时
- 当警告用户出现问题时
- 当操作无法按要求完成时
通知声音（ 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}"

可用工具

play_sound(sound_type="completion", custom_sound_path=None) ：播放音效
list_available_sounds() ：列出所有可用的声音文件
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 文件。

MCP Sound Tool