Audio Playback MCP Server 使用说明

项目简介

Audio Playback MCP Server 是一个基于 Model Context Protocol (MCP) 实现的服务器，它提供了一组工具，允许连接到该服务器的 LLM 客户端控制服务器所在机器上的音频播放。目前，该服务器支持播放指定路径的 MP3 和 WAV 格式的音频文件，并可以停止当前正在播放的音频。

主要功能点

音频播放: 通过 'play-audio' 工具，LLM 客户端可以指定音频文件路径，服务器会在本地播放该音频文件。支持 MP3 和 WAV 格式。
停止播放: 通过 'stop-audio' 工具，LLM 客户端可以停止当前正在服务器上播放的音频。
工具发现: 服务器实现了 'ListToolsRequestSchema'，客户端可以查询到服务器提供的 'play-audio' 和 'stop-audio' 工具及其描述和参数。
基于标准 MCP SDK: 使用 '@modelcontextprotocol/sdk' 开发，保证了与 MCP 协议的兼容性。
Stdio 传输: 使用标准输入输出 (Stdio) 作为 MCP 服务器的传输协议，简化了部署和集成。

安装步骤

安装 Node.js: 确保你的服务器环境已安装 Node.js 和 npm (Node 包管理器)。
下载代码: 从 GitHub 仓库 https://github.com/mamertofabian/audio-mcp-server 下载 'index.ts' 文件到你的服务器。

安装 SDK 依赖: 在 'index.ts' 文件所在的目录下，打开终端并运行以下命令安装 MCP SDK：

npm install @modelcontextprotocol/sdk
npm install zod
npm install child_process
npm install util
npm install fs

编译 (如果需要): 如果需要，你可以使用 'tsc index.ts' 命令将 TypeScript 代码编译为 JavaScript 代码（'index.js'）。但通常可以直接使用 'node index.ts' 运行 TypeScript 代码，如果你的环境配置允许。

服务器配置

对于 MCP 客户端，你需要配置连接到 Audio Playback MCP Server 的信息。以下是一个 JSON 格式的配置示例，你需要将其配置到你的 MCP 客户端中：

{
  "serverName": "audio-player",
  "command": "node",
  "args": ["index.js"]
}

配置参数说明:

'serverName': 服务器的名称，这里设置为 '"audio-player"'，与代码中服务器实例化的名称一致。
'command': 启动服务器的命令。由于该服务器是 Node.js 应用，所以命令为 'node'。
'args': 命令的参数，这里指定了服务器入口文件 'index.js'。 请确保 'index.js' 文件位于 MCP 客户端启动命令的工作目录下，或者提供正确的相对或绝对路径。 如果客户端和服务器代码在同一目录下，直接使用 'index.js' 即可。如果你编译成了 'index.js'，请使用 'index.js'，否则如果直接运行 'index.ts'，请确保你的环境可以直接执行 'index.ts'，并且这里 'args' 参数也要相应改为 '["index.ts"]'。

注意: 如果你的环境配置不允许直接运行 'index.ts'，请先执行编译步骤生成 'index.js' 文件，并将 'args' 参数配置为 '["index.js"]'。

基本使用方法

启动服务器: 在服务器端，打开终端，进入 'index.ts' (或 'index.js') 文件所在目录，运行以下命令启动 MCP 服务器：
```
node index.js
```
或 (如果直接运行 TypeScript):
```
node index.ts
```
你应该在终端看到 'Audio Player MCP Server running on stdio' 的输出，表示服务器已成功启动并监听 Stdio。
配置 MCP 客户端: 在你的 MCP 客户端应用中，根据客户端的要求配置上述提供的 JSON 配置信息，以连接到 Audio Playback MCP Server。

通过 LLM 客户端调用工具: 连接成功后，你可以通过 LLM 客户端向 Audio Playback MCP Server 发送工具调用请求。

播放音频: 调用 'play-audio' 工具，并提供 'filepath' 参数，指定要播放的音频文件路径。例如：

{
  "tool_calls": [
    {
      "id": "play_audio_1",
      "type": "function",
      "function": {
        "name": "play-audio",
        "arguments": "{\"filepath\": \"/path/to/your/audio.mp3\"}"  // 将 "/path/to/your/audio.mp3" 替换为实际的音频文件路径
      }
    }
  ]
}

注意: '/path/to/your/audio.mp3' 是服务器本地文件系统的路径，LLM 客户端需要告知 LLM 合适的文件路径，或者通过其他方式让 LLM 知道服务器上的可用音频文件。

停止播放: 调用 'stop-audio' 工具，无需参数：

{
  "tool_calls": [
    {
      "id": "stop_audio_1",
      "type": "function",
      "function": {
        "name": "stop-audio",
        "arguments": "{}"
      }
    }
  ]
}

观察结果: 服务器会根据工具调用请求执行相应的音频播放或停止操作，并通过 MCP 协议将执行结果返回给 LLM 客户端。你可以在服务器的终端输出中查看日志信息，以及在客户端接收工具调用的响应。

注意事项

文件路径: 'play-audio' 工具的 'filepath' 参数必须是服务器本地文件系统中有效的音频文件路径，且文件格式必须是 MP3 或 WAV。
依赖: 确保服务器环境已安装所有必要的 npm 依赖。
错误处理: 服务器代码包含基本的错误处理，例如文件格式校验、播放失败处理等。LLM 客户端应根据服务器返回的响应 (特别是 'isError' 字段) 来判断工具调用是否成功。
资源管理: 当前 'ListResourcesRequestSchema' 和 'ReadResourceRequestSchema' 的实现比较简单，资源管理功能未完全实现。在实际应用中，可能需要扩展资源管理功能，例如允许客户端查询服务器上可用的音频资源列表。
平台兼容性: 代码中针对 Windows, macOS 和 Linux 平台使用了不同的音频播放命令 ('start', 'afplay', 'aplay')，以保证在不同操作系统上的兼容性。

关键词