JinDaGe - mcp-make-sound MCP Details

article

README

🚀 🔊 MCP Make Sound

MCP Make Sound 是一个基于模型上下文协议（MCP）的服务器，专为 macOS 系统打造，具备全面的声音播放功能。它允许 AI 助手及其他 MCP 客户端播放系统声音、进行文本转语音，还能播放自定义音频文件，为用户带来丰富的音频反馈体验。

🚀 快速开始

运行服务器

启动 MCP 服务器：

npm start

若要在开发环境中实现自动重新加载：

npm run dev

✨ 主要特性

🔔 简单声音方法：预配置了信息、警告和错误提示音。
🎵 自定义系统声音：可播放 14 种内置的 macOS 系统声音。
🗣️ 文本转语音：能将文本转换为语音，且支持自定义语音。
📁 文件播放：可播放磁盘上的自定义音频文件。
🚀 基于 TypeScript 和 MCP SDK 构建。
🪶 轻量级设计，易于集成。

📦 安装指南

克隆此仓库：

git clone <repository-url>
cd mcp-make-sound

安装依赖项：

npm install

构建项目：

npm run build

💻 使用示例

基础用法

示例：Claude 与 Warp 终端集成

以下是如何设置 MCP 声音服务器，以便在 Warp 终端中 AI 任务完成时提供音频反馈：

配置规则：“当 AI 任务完成时，使用 mcp - make - sound 播放声音。MCP 支持错误、信息和成功三种状态。根据 AI 任务的结果播放相应的声音。”

通过此设置，你可以：

🔔 当任务成功完成时，听到悦耳的提示音。
⚠️ 当出现警告或部分完成时，收到警报声。
❌ 当出现错误或失败时，获得清晰的音频反馈。

音频反馈能让你在专注于其他工作的同时，第一时间知晓 AI 助手何时完成请求处理。

高级用法

可用工具

服务器提供了四种工具：

简单声音方法（旧版）

play_info_sound
- 描述：播放信息类系统声音。
- 参数：无。
- 声音：Glass.aiff
play_warning_sound
- 描述：播放警告类系统声音。
- 参数：无。
- 声音：Purr.aiff
play_error_sound
- 描述：播放错误类系统声音。
- 参数：无。
- 声音：Sosumi.aiff

高级声音方法

play_sound
- 描述：可通过自定义参数播放各种类型的声音。
- 参数：
  - type（必需）："system"、"tts" 或 "file"。
  - 根据类型的不同还有其他附加参数（见以下示例）。

系统声音

播放 14 种内置的 macOS 系统声音：

{
  "name": "play_sound",
  "arguments": {
    "type": "system",
    "name": "Basso"
  }
}

可用的系统声音： Basso、Blow、Bottle、Frog、Funk、Glass、Hero、Morse、Ping、Pop、Purr、Sosumi、Submarine、Tink

文本转语音

将文本转换为语音，并可选择语音：

{
  "name": "play_sound",
  "arguments": {
    "type": "tts",
    "text": "Hello, this is a test message",
    "voice": "Albert"
  }
}

不指定语音（使用系统默认语音）：

{
  "name": "play_sound",
  "arguments": {
    "type": "tts",
    "text": "Task completed successfully"
  }
}

支持的语音：

英语：Albert、Alice、Bad News、Bahh、Bells、Boing、Bruce、Bubbles、Cellos、Daniel、Deranged、Fred、Good News、Hysterical、Junior、Kathy、Pipe Organ、Princess、Ralph、Trinoids、Whisper、Zarvox
国际语音：Anna、Amélie、Daria、Eddy、Fiona、Jorge、Juan、Luca、Marie、Moira、Nora、Rishi、Samantha、Serena、Tessa、Thomas、Veena、Victoria、Xander、Yelda、Zosia

注意：如果指定了不支持的语音，系统将自动回退到默认语音并继续播放。

自定义音频文件

播放磁盘上的音频文件：

{
  "name": "play_sound",
  "arguments": {
    "type": "file",
    "path": "/Users/username/Music/notification.mp3"
  }
}

支持常见的音频格式：.aiff、.wav、.mp3、.m4a 等。

🔒 安全与限制

系统声音：仅允许使用 14 种官方的 macOS 系统声音。
文本转语音：
- 文本最大限制为 1000 个字符。
- 支持语音验证，若指定不支持的语音，将优雅地回退到系统默认语音。
- 为确保安全，精心筛选了 43 种以上支持的语音。
文件播放：需要绝对路径，并验证文件是否存在。

🔗 与 MCP 客户端集成

此服务器可与任何兼容 MCP 的客户端集成，例如：

🤖 Claude Desktop
🛠️ 自定义 MCP 客户端
🧠 支持 MCP 的 AI 助手

MCP 配置示例

将以下内容添加到你的 MCP 客户端配置中：

{
  "mcp-make-sound": {
    "command": "node",
    "args": [
      "/Users/nocoo/Workspace/mcp-make-sound/dist/index.js"
    ],
    "env": {},
    "working_directory": "/Users/nocoo/Workspace/mcp-make-sound",
    "start_on_launch": true
  }
}

示例工具调用：

{
  "name": "play_info_sound",
  "arguments": {}
}

{
  "name": "play_sound",
  "arguments": {
    "type": "system",
    "name": "Hero"
  }
}

📚 详细文档

项目结构

mcp-make-sound/
├── src/
│   ├── index.ts          # 主服务器实现
│   └── __tests__/        # 单元测试
│       └── sound.test.ts # 声音系统测试
├── dist/                 # 编译后的 JavaScript 输出
├── eslint.config.js      # ESLint 配置
├── vitest.config.ts      # Vitest 测试配置
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
└── README.md            # 本文件

脚本

构建与运行

npm run build - 🔨 将 TypeScript 编译为 JavaScript。
npm start - ▶️ 运行编译后的服务器。
npm run dev - 🔄 开发模式，支持自动重新构建和重启。
npm run kill - 🛑 停止所有正在运行的 MCP 服务器实例。

代码质量与测试

npm run lint - 🔍 检查代码风格和错误。
npm run lint:fix - 🔧 修复可自动修复的代码风格问题。
npm run test - 🧪 在监视模式下运行测试。
npm run test:run - ✅ 运行一次测试。
npm run test:ui - 🎛️ 以交互式 UI 运行测试。

工作原理

服务器使用官方 SDK 实现 MCP 协议。
它提供了四种工具，用于实现不同的声音功能。
当调用工具时，它会使用 macOS 命令：
- afplay 用于播放音频文件（系统声音和自定义文件）。
- say 用于文本转语音合成。
系统声音位于 /System/Library/Sounds/。
服务器通过标准输入输出（stdio）进行通信。

🔧 技术细节

🔌 传输方式：标准输入输出（stdio）
📡 协议：模型上下文协议（MCP）
🎧 音频后端：macOS 的 afplay 和 say 命令
🎵 声音文件：系统 .aiff 文件、自定义音频文件和合成语音

🚨 错误处理

服务器包含全面的错误处理机制：

验证工具名称和参数。
处理 afplay 和 say 命令失败的情况。
验证每种声音类型所需的参数。
向客户端返回适当的错误消息。
在出现错误时优雅地关闭服务器。

📄 许可证

本项目采用 MIT 许可证。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

🎼 声音功能

简单方法（旧版）

🔔 信息：Glass.aiff - 悦耳的提示音。
⚠️ 警告：Purr.aiff - 温和的警报声。
❌ 错误：Sosumi.aiff - 独特的错误提示音。

高级方法（play_sound）

🎵 14 种系统声音：所有内置的 macOS 系统声音均可使用。
🗣️ 50 多种文本转语音语音：支持多种语言和角色语音。
📁 自定义文件：支持 .aiff、.wav、.mp3、.m4a 等多种音频格式。

这些功能为任何应用需求提供了丰富的音频反馈选项。

mcp-make-sound