# CosyVoice MCP Server

这是一个基于Model Context Protocol (MCP)的语音合成服务端，支持通过uvx运行。

## 功能特性

- 文本转语音(TTS)合成
- 多种AI角色语音
- 支持流式播放
- 与Claude Desktop集成

## 安装和运行


### 方法：传统Python运行

```bash
# 安装依赖
pip install -r requirements.txt

# 运行服务
python src/mcp_server.py
```

## Claude Desktop配置

在Claude Desktop的配置文件中添加：

<!-- ```json
// {
//   "mcpServers": {
//     "cosyvoice-mcp": {
//       "command": "uvx",
//       "args": [
//         "--env-file",
//         "f:\\MCPProject\\WebMCPServers\\cosyVoice-mcp\\.env",
//         "f:\\MCPProject\\WebMCPServers\\cosyVoice-mcp\\run_mcp.py"
//       ]
//     }
//   }
// }
```
或 -->
```json
{
  "mcpServers": {
    "cosyvoice-mcp": {
      "command": "python",
      "args": [
        "f:\\MCPProject\\WebMCPServers\\cosyVoice-mcp\\src\\mcp_server.py"
      ],
      "cwd": "f:\\MCPProject\\WebMCPServers\\cosyVoice-mcp",
      "env": {
        "DASHSCOPE_API_KEY": "your-api-key",
        "VOICE_FILE_PATH": "f:/MCPProject/WebMCPServers/cosyVoice-mcp/voiceData/voice"
      }
    }
  }
}
```

<!-- 或者直接使用Python文件：

```json
{
  "mcpServers": {
    "cosyvoice-mcp": {
      "command": "uvx",
      "args": [
        "--env-file",
        "f:\\MCPProject\\WebMCPServers\\cosyVoice-mcp\\.env",
        "f:\\MCPProject\\WebMCPServers\\cosyVoice-mcp\\src\\mcp_server.py"
      ]
    }
  }
}
``` -->

## 环境变量配置

在`.env`文件中设置：

```
dashscope_api_key=your-api-key-here
VOICE_FILE_PATH={your-voice-file-save-path}
```

## 可用工具

- `start_voice_service`: 启动语音服务
- `stop_voice_service`: 停止语音服务
- `set_character_role`: 设置AI角色
- `text_to_speech`: 文本转语音
- `get_supported_roles`: 获取支持的角色列表

## 支持的角色

- dongxuelian: 东雪莲
- libai: 李白
- nekogirl: 猫娘
- yunli: 云李
- storyteller: 说书人
- direct_model: 直接模型

## LLM系统Prompt配置

为了让LLM能够正确使用CosyVoice MCP服务，建议在LLM系统初始化时添加相应的prompt指导。本项目提供了两个版本的系统prompt：

### 详细版本
查看 `SYSTEM_PROMPT.md` 文件，包含完整的使用指南、最佳实践和示例场景。

### 简化版本
查看 `SYSTEM_PROMPT_SIMPLE.txt` 文件，适合直接复制粘贴到LLM配置中。

### 核心工作流程

LLM使用服务的标准流程：

1. **获取角色列表**：`get_supported_roles`
2. **设置合适角色**：`set_character_role`
3. **执行语音合成**：
   - 播放语音：`text_to_speech_and_speak`
   - 生成文件：`text_to_speech`

### 角色选择建议

- **故事叙述**：storyteller (说书人)
- **日常对话**：dongxuelian (东雪莲)
- **正式内容**：direct_model (直接模型)
- **轻松娱乐**：nekogirl (猫娘)
- **诗词文学**：libai (李白)
- **清新内容**：yunli (云李)

## MCP Prompts功能

本服务内置了prompts功能，LLM可以通过以下方式动态获取使用指导：

- `list_prompts`：获取所有可用的prompt列表
- `get_prompt`：获取特定prompt的详细内容

可用的prompts：
- `cosyvoice_usage_guide`：完整的服务使用指南
- `role_selection_guide`：角色选择建议和说明

## 开发和调试

### 本地开发
```bash
# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 运行服务
python src/mcp_server.py
```

### 调试模式
设置环境变量 `DEBUG=true` 可以启用调试输出。

## 许可证

本项目采用MIT许可证。详情请查看 `LICENSE` 文件。

## 贡献

欢迎提交Issues和Pull Requests来改进本项目。