关键词

声音工具Cursor 集成音效反馈跨平台命令行工具

项目简介

本项目实现一个基于 MCP（Model Context Protocol）的服务器端，核心功能是注册并暴露音效相关的工具，供 MCP 客户端（如 Cursor、其他 IDE 集成）调用，通过标准化的 JSON-RPC 方式获取并执行音效相关操作。服务器能够自动定位并使用打包的声音资源，支持将默认声音安装到用户目录，以及在多平台（Windows、macOS、Linux）下播放音效。

主要功能点

  • 注册工具并暴露音效相关的接口：
    • play_sound：根据类型播放对应音效（completion、error、notification、custom）。
    • list_available_sounds：列出当前声音目录中的可用声音文件。
    • install_to_user_dir：将打包的声音文件复制到用户配置目录，便于自定义替换。
  • 资源定位与读取：
    • 优先使用用户目录中的声音（如果存在且包含音频文件）。
    • 其次使用项目目录中的声音文件。
    • 最后回退到打包在包中的默认声音资源。
  • 跨平台声音播放：
    • macOS 使用 afplay。
    • Windows 使用 winsound。
    • Linux 尝试 paplay、aplay、mpg123、mpg321，一旦某个可用就直接播放。
  • 安全与鲁棒性：
    • 处理找不到声音文件、播放失败等情况，返回友好的错误信息。
    • 提供简单的错误处理和日志输出，便于调试与集成。
  • 安装与分发：
    • 通过 pip 安装 mcp-sound-tool，或使用 pipx 进行隔离安装。
    • 提供命令行入口 mcp-sound-tool，用于启动服务器。
  • 服务器启动与运行：
    • 启动后服务器持续运行，接收 MCP 客户端的请求并执行相应操作。

安装步骤

  • 安装依赖与工具
    • 使用推荐的隔离环境安装：pipx install mcp-sound-tool
    • 或直接通过 pip 安装：pip install mcp-sound-tool
  • Python 版本要求
    • 适用于 Python 3.10 及以上版本（项目对 Python 版本有明确要求）。
  • 启动服务器
    • 安装完成后直接在命令行执行 mcp-sound-tool，服务器将基于当前环境启动。

服务器配置（MCP 客户端的使用配置，JSON 描述，非代码）

请在 MCP 客户端的配置中为该服务器提供以下字段信息（JSON 格式描述，实际客户端配置中以文本填充，不需要直接在客户端执行代码）：

  • server name：Sound Tool 🔊
  • command：mcp-sound-tool
  • args：[]
  • type：stdio
  • pollingInterval：5000
  • startupTimeout：10000
  • restartOnFailure：true

说明：以上信息用于 MCP 客户端在启动时正确调用服务器程序，并通过标准输入输出（stdio）与服务器进行 JSON-RPC 交互。实际配置中，客户端会将上述项写入配置文件中的 mcpServers 字段下的 sound 条目，以实现自动化启动和连接。

  • 一个示例的配置结构（文本描述，不是代码块）： mcpServers: { sound: { name: "Sound Tool 🔊", command: "mcp-sound-tool", args: [], type: "stdio", pollingInterval: 5000, startupTimeout: 10000, restartOnFailure: true } }

基本使用方法

  • 启动与连接
    • 在命令行执行 mcp-sound-tool 启动服务器。
    • 将上述 JSON 配置添加到 MCP 客户端的配置中，让客户端能够正确启动并连接到该服务器。
  • 调用工具
    • play_sound：在客户端触发事件时，AI/系统会调用 play_sound，自动选择合适的声音文件并播放。可通过配置自定义声音路径。
    • list_available_sounds：查询当前声音目录中可用的音频文件，方便确认可用选项。
    • install_to_user_dir：将打包的声音文件复制到用户配置目录，便于后续自定义替换。
  • 结果与反馈
    • 成功播放声音时返回“Successfully played <sound_type> sound”等文本提示。
    • 出现错误时返回描述性错误信息，便于排错。

其他注意事项

  • 声音资源定位逻辑在运行时会自动检测用户目录、项目目录以及打包资源，以确保声音文件尽可能可用。
  • 支持多平台播放，便于在不同开发环境中使用。
  • 若需要自定义声音，请将自定义音频文件放入用户配置目录的 sounds 目录中，或者通过 install_to_user_dir 将默认资源复制到该位置后再进行替换。

使用前提与兼容性

  • 确保系统已安装 Python 3.10+。
  • 确保安装了 mcp 相关依赖（该项目在 setup.py 中声明了对 mcp>=1.2.0 的依赖）。
  • MCP 客户端（如 Cursor）需要在配置中正确指向此服务器的命令与参数，以建立通信。

其他实现细节

  • 服务器日志会输出当前正在使用的声音目录、可用声音、以及初始化信息等，便于排错。
  • 提供测试覆盖的核心组件包括 SoundPlayer 的跨平台声音播放、SoundToolServer 的工具注册与声音文件管理等。

关键词

声音工具, Cursor 集成, 音效反馈, 跨平台, 命令行工具

分类ID

8

信息

分类

桌面与硬件

访问项目