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 安装

推荐使用 pipx 安装 mcp-sound-tool，它会在隔离的环境中安装软件包，同时使命令在全局可用：

# 如果您没有 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

从源代码安装

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 将能够找到并执行它，而无需指定完整路径。

AI 模型的 Sound MCP 使用指南

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

何时使用声音反馈

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

1. 成功声音 (completion):

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

2. 错误声音 (error):

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

3. 通知声音 (notification):

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

用法示例

# 当命令成功完成时
@mcp.tool()
def execute_command(command):
    result = run_command(command)
    if result.success:
        play_sound("completion")  # 使用音频指示成功
        return "Command executed successfully"
    else:
        play_sound("error")  # 使用音频指示失败
        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 服务器并查看工具描述。

开发

对于开发：

# 安装开发依赖项
pip install -e ".[dev]"

# 运行测试
pytest

致谢

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

许可证

此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。