# MCP MeloTTS 语音生成器 (MCP MeloTTS Audio Generator)

本项目是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，为 AI 助手提供将文本生成语音音频的能力，基于 MeloTTS。

支持自动将长文本按标点与长度分割为不超过 100 字的小段，逐段生成 WAV 文件，并使用 ffmpeg 无损拼接为完整音频。

## ✨ 功能特性

- 文本转语音：使用 MeloTTS 将文本生成高质量语音
- 自动分段：长文本自动分段，避免一次过长导致失败
- 无损拼接：使用 ffmpeg 将分段 WAV 拼接为完整文件
- 可配置语速、语言、设备与说话人
- 跨平台：Windows、Linux、macOS

## 🚀 安装

### 使用 uvx (推荐)

```bash
docker run -d -p 127.0.0.1:9900:8888 kisaragi29/melotts:latest
uvx mcp-melotts@latest
```

### 使用 pip

```bash
pip install mcp-melotts@latest
```

### 从源码安装

```bash
git clone https://github.com/aardpro/mcp-melotts.git
cd mcp-melotts
pip install -e .
```

## ⚙️ 配置

### 配置

#### 前置条件
开发电脑已安装并可用：
- ffmpeg（用于拼接音频）
- MeloTTS（可通过本地 Python 包 melo.api 或 Docker Gradio 服务）

#### 启动前检查
启用 MCP 时会自动检查以下条件：
- 本机 9900 端口是否启动了 MeloTTS HTTP 服务（用于 HTTP 模式）
- 系统是否可调用 ffmpeg（用于无损拼接）
任一不满足将抛出错误并终止启动

#### 配置文件
内置配置文件位于 src/main/config.json，可设置：
- defaultLanguage：默认语言代码（ZH/EN/JP/ES）
- defaultSpeed：默认语速
- defaultDevice：默认设备（cpu 或 cuda:0）
- defaultSpeaker：默认说话人标签
- chunkSizeLimit：分段长度上限（推荐 100）

### MCP 客户端配置

将以下内容添加到你的 MCP 客户端配置中（例如 Claude Desktop, Cursor）：

#### 选项 1: 使用 uvx 

```json
{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "uvx",
      "args": ["mcp-melotts"]
    }
  }
}
```

#### 选项 2: 使用 pip

```json
{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "mcp-melotts"
    }
  }
}
```

#### 选项 3: Windows 系统 

```json
{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "cmd",
      "args": [
        "/c",
        "chcp 65001 >nul && uvx mcp-melotts"
      ]
    }
  }
}
```

#### 选项 4: Linux/macOS：

```json
{
  "mcpServers": {
    "McpMeloTTS": {
      "command": "python",
      "args": ["-m", "main"]
    }
  }
}
```

## 🛠️ 可用工具

### `mcp_melotts_generate_audio`

将文本生成语音文件。适用于“根据文本生成音频文件”等请求。支持自动分段与 ffmpeg 无损拼接，支持两种调用模式：本地 melo.api 与 Docker Gradio HTTP 接口。

**参数:**
- `text` (string, 必填): 要转换为语音的文本
- `language` (string, 可选): 语言代码（默认 ZH）
- `speaker` (string, 可选): 说话人标签（默认 ZH）
- `speed` (number, 可选): 语速（默认 1.0）
- `device` (string, 可选): cpu 或 cuda:0（默认 cpu）
- `split_sentences` (boolean, 可选): 是否自动分段（默认 true）
- `output_dir` (string, 必填): 输出目录
- `target_filename` (string, 可选): 最终输出文件名，默认时间戳命名
- `use_http_api` (boolean, 可选): 是否使用 Docker Gradio HTTP 接口（默认 false）
- `api_base_url` (string, 可选): HTTP 接口基础地址（如 http://localhost:9900）
- `fn_index` (number, 可选): Gradio 函数索引（默认 1）
- `session_hash` (string, 可选): Gradio 会话哈希（不提供则自动生成）

**调用示例（本地 melo.api 模式）:**

```json
{
  "name": "mcp_melotts_generate_audio",
  "arguments": {
    "text": "我最近在学习machine learning，希望能够在未来的artificial intelligence领域有所建树。",
    "language": "ZH",
    "speaker": "ZH",
    "speed": 1.0,
    "output_dir": "./audio"
  }
}
```

**调用示例（Docker Gradio HTTP 模式）:**
```json
{
  "name": "mcp_melotts_generate_audio",
  "arguments": {
    "text": "请将以下内容朗读为音频……",
    "language": "ZH",
    "speed": 1.0,
    "output_dir": "./audio",
    "use_http_api": true,
    "api_base_url": "http://localhost:9900",
    "fn_index": 1
  }
}
```

> 说明：HTTP 模式需要先运行 Docker 容器并开放 9900 端口，脚本会通过 /queue/join 与 /queue/data 监听生成进度并下载音频。

## ⚡ 快速开始

### 使用虚拟环境运行
```bash
python -m venv .venv
.venv/Scripts/python.exe -m pip install -U pip
.venv/Scripts/pip.exe install -r requirements.txt
.venv/Scripts/python.exe -m main
```

### 一键启动（Windows）
双击或执行项目根目录的 start_server.bat，它会自动创建 .venv、安装依赖并在虚拟环境中启动 MCP。

### 生成音频的测试脚本
```bash
.venv/Scripts/python.exe test-generate-audio.py --input test-text.txt --output-dir output --use-http-api --api-base-url http://localhost:9900
```
打印的路径即生成的 wav 文件（如 output/1767514828_93829.wav）。


## 💡 使用示例

配置完成后，你可以直接让 AI 助手：
- "将这段中文生成音频文件"
- "用日语朗读下面这段文字，语速稍慢"
- "把长文拆分生成语音并合并为一个文件"

## 💻 开发

### 设置开发环境

```bash
git clone https://github.com/aardpro/mcp-melotts.git
cd mcp-melotts
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest
```

### 构建包

build && upload
```bash
rm -rf dist && pip install build && python -m build && pip install twine && twine upload dist/*
```

```bash
pip install build
python -m build
```

### 发布到 PyPI

```bash
pip install twine
twine upload dist/*
```

## 修改后的发布步骤

当对项目进行修改后，按照以下步骤发布更新版本：

1. 在 `pyproject.toml` 中增加版本号
2. 安装构建依赖：
   ```bash
   pip install build twine
   ```
3. 构建包：
   ```bash
   python -m build
   ```
4. 本地测试构建的包（可选但推荐）：
   ```bash
   pip install dist/mcp_melotts-*.whl
   ```
5. 上传到 PyPI：
   ```bash
   twine upload dist/*
   ```

## 📂 项目结构

```
mcp-melotts/
├── src/
│   └── main/
│       ├── __init__.py
│       ├── __main__.py
│       └── server.py
├── pyproject.toml
├── README.md
└── LICENSE
```

## ❓ 常见问题

### 配置问题

请确保已安装 ffmpeg 与 MeloTTS，并能在 Python 中导入 melo.api。

### 音频生成失败

如果音频生成失败，请检查：
1. 是否已正确安装 MeloTTS（Python 包 melo）
2. 是否已正确设置语言与说话人标签
3. ffmpeg 是否在系统 PATH 中可用

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件。

## 🤝 贡献

欢迎提交 Pull Request 来改进这个项目！