使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 的音乐播放器服务器实现。它通过 MCP 协议向 LLM 客户端暴露音乐播放控制能力，例如播放音乐、暂停、停止等。客户端可以通过调用服务器提供的工具，控制音乐播放，从而实现更智能的语音助手功能。

主要功能点

音乐播放: 根据歌曲名或关键字搜索并播放网络音乐。
播放控制: 提供暂停、恢复、停止播放等基本控制功能。
状态查询: 查询当前是否正在播放音乐。
MCP服务器: 实现了 MCP 协议，可以与任何兼容 MCP 协议的客户端进行通信。
工具注册: 通过 MCP 的工具 (Tool) 机制，将音乐播放功能注册为可被 LLM 客户端调用的工具。

安装步骤

安装 uv 工具 (可选但推荐): 根据 'README.md' 建议，为了更高效的包管理，可以先安装 'uv' 工具。在命令行中执行 'pip install uv'。

安装 Python 依赖: 进入 'MCP_AI_Voice_Agent/server/mplayer' 目录，使用 pip 或 uv 安装项目依赖。虽然仓库中没有明确的 requirements.txt 文件，但根据代码内容，你需要安装以下库：

pip install fastmcp pydantic pygame requests
# 或使用 uv
uv pip install fastmcp pydantic pygame requests

运行 MCP 服务器: 在 'MCP_AI_Voice_Agent/server/mplayer' 目录下，直接运行 'main.py' 文件即可启动 MCP 服务器。
```
python main.py
```
或者，如果你使用 'uv':
```
uv run main.py
```
启动后，服务器将在控制台输出 'Server running'，表示服务器已成功启动并监听来自 MCP 客户端的请求。

服务器配置

MCP 服务器主要通过代码 'main.py' 运行，无需额外的配置文件。但为了让 MCP 客户端（例如 'voice.py'）能够连接到此服务器，需要在客户端的配置文件 'mcp_server_config.json' 中配置服务器的启动信息。

以下是一个示例 'mcp_server_config.json' 配置，用于配置连接到 'voice_bot_mcp' 提供的音乐播放器 MCP 服务器：

{
  "mcpServers": {
    "music_player_server": {  // 服务器名称，客户端可以自定义
      "command": "python",   // 启动服务器的命令，这里假设你的 Python 环境可以直接用 python 命令启动
      "args": [              // 启动命令的参数
        "MCP_AI_Voice_Agent/server/mplayer/main.py" // MCP 服务器脚本的路径，请根据实际情况修改
      ]
    }
  }
}

配置说明:

'"music_player_server"': 这是你为这个 MCP 服务器定义的名称，客户端代码中会使用这个名称来引用该服务器。你可以自定义名称。
'"command": "python"': 指定启动 MCP 服务器的命令。这里假设你的 Python 环境可以通过 'python' 命令直接运行。如果你的 Python 执行命令不同（例如 'python3'），请相应修改。
'"args": [...]"': 一个字符串数组，包含了启动命令的参数。
- '"MCP_AI_Voice_Agent/server/mplayer/main.py"': 请务必根据你的实际文件路径修改此项。这是 'main.py' 脚本在你文件系统中的完整或相对路径，确保客户端能够找到并执行服务器脚本。

请注意: 'mcp_server_config.json' 文件位于 'MCP_AI_Voice_Agent/client' 目录下，客户端程序 'voice.py' 会读取这个配置文件来启动和连接 MCP 服务器。你需要在客户端的配置文件中正确配置 'command' 和 'args'，才能成功连接到音乐播放器 MCP 服务器。

基本使用方法

启动 MCP 服务器: 按照上面的 "安装步骤" 和 "服务器配置" 说明，先启动 'voice_bot_mcp' 提供的音乐播放器 MCP 服务器 ('main.py')。

启动 MCP 客户端: 进入 'MCP_AI_Voice_Agent/client' 目录，配置好 'mcp_server_config.json' 和 '1.env' 文件后，运行 'voice.py' 启动 MCP 客户端。

cd MCP_AI_Voice_Agent/client
# 确保 mcp_server_config.json 和 1.env 配置正确
uv run voice.py

通过语音与客户端交互: 客户端 'voice.py' 启动后，会监听语音输入（需要配置 Azure 语音服务），你可以通过语音指令与客户端交互，例如：
- "播放 [歌曲名]" - 客户端会调用 MCP 服务器的 'play_music' 工具播放音乐。
- "暂停播放" - 客户端调用 'pauseplay' 工具暂停音乐。
- "继续播放" - 客户端调用 'unpauseplay' 工具恢复播放。
- "停止播放" - 客户端调用 'stopplay' 工具停止音乐。
- "正在播放吗" - 客户端调用 'isPlaying' 工具查询播放状态。

注意: 'voice.py' 客户端依赖于 Azure OpenAI 和 Azure 语音服务，你需要配置 '1.env' 文件中的相关环境变量才能正常使用客户端的语音交互功能。具体配置项请参考 'voice.py' 代码和 '1.env' 文件示例。

关键词