内容
# Live2D MCP Companion
## 概述
这是一个基于 Live2D 模型的桌面伴侣程序，通过 MCP（Model Context Protocol）进行控制。该程序可在 Windows 上运行。
## 功能
- **Live2D 角色** — 在桌面上显示动画的 Hiyori 模型（通过 PyQt6 + OpenGL）
- **TTS（文本转语音）** — 通过 Piper TTS 进行语音输出（支持中文、英文等多种语言）
- **STT（语音识别）** — 通过 faster-whisper 进行语音识别（暂未实现）
- **MCP 服务器** — 提供 36 种工具来控制角色，支持任何 MCP 客户端
- **RAG（检索增强生成）** — 支持文档语义搜索
- **网页界面** — 通过浏览器在 `http://localhost:8766` 进行控制
- **音乐播放器** — 通过 pygame 播放 MP3 音乐
- **闹钟和计时器** — 支持 MCP 通知
- **截图** — 支持截图并由角色反应
- **游戏模式** — 支持捉迷藏、舞蹈、情绪表达等多种游戏模式
- **额外模型** — [Nagatoro Sprite](https://github.com/nukkerman2000/nagatoru-live2d) （独立仓库中的精灵模型）
## 系统要求
- Windows 10/11
- Python 3.12+
- 支持 OpenGL 的显卡
- 麦克风（用于 STT）
## 安装
### 1. 克隆仓库
```bash
git clone https://github.com/nukkerman2000/live2d-mcp.git
cd live2d-mcp
```
### 2. 安装便携版 Python
下载 [embeddable Python 3.12](https://www.python.org/downloads/windows/) 并解压到 `python\` 目录下。
或者使用系统自带的 Python。
### 3. 安装依赖
运行 `setup_python.bat` 或手动执行：
```bash
python\python.exe get-pip.py
python\Scripts\pip.exe install -r requirements.txt
```
### 4. 配置文件
复制 `config.example.json` 为 `config.json` 并进行个性化配置。
### 5. 下载语音模型
下载 Piper 语音模型到 `voices\` 目录下：
- [ru_RU-irina-medium](https://huggingface.co/rhasspy/piper-voices/resolve/main/ru/ru_RU/irina/medium/ru_RU-irina-medium.onnx)
- [ru_RU-denis-medium](https://huggingface.co/rhasspy/piper-voices/resolve/main/ru/ru_RU/denis/medium/ru_RU-denis-medium.onnx)
- [ru_RU-ruslan-medium](https://huggingface.co/rhasspy/piper-voices/resolve/main/ru/ru_RU/ruslan/medium/ru_RU-ruslan-medium.onnx)
### 6. 下载 Piper TTS 二进制文件
下载 [Piper TTS for Windows](https://github.com/rhasspy/piper/releases) 并解压 `piper.exe` 和 DLL 到 `piper\` 目录下。
## 运行
```bash
start.bat
```
运行后：
- MCP 服务器：`http://127.0.0.1:8765/mcp`
- 网页界面：`http://127.0.0.1:8766`
## MCP 工具
共有 36 种工具来控制角色，支持通过 MCP 客户端进行控制。
### 角色控制
| 工具 | 描述 |
|---|---|
| `switch_model` | 切换模型（hiyori, nagatoro_sprite） |
| `set_emotion` | 设置情绪/表情 |
| `set_mouth_open` | 控制嘴巴张开（唇形同步） |
| `play_motion` | 播放动作动画 |
| `stop_all_motions` | 停止所有动画 |
| `list_motion_groups` | 获取可用动作组列表 |
| `set_eye_position` | 控制眼睛方向 |
| `set_parameter` | 设置 Live2D 模型参数 |
### 角色窗口
| 工具 | 描述 |
|---|---|
| `show` / `hide` | 显示/隐藏角色窗口 |
| `move_window` | 移动窗口到指定坐标 |
| `resize_window` | 调整窗口大小 |
| `center_window` | 将窗口居中于屏幕 |
| `get_status` | 获取角色和窗口状态 |
### TTS / 语音
| 工具 | 描述 |
|---|---|
| `speak` | 通过 TTS 输出文本（带唇形同步） |
| `list_voices` | 获取可用语音列表 |
| `stop_speaking` | 停止语音输出 |
### 音乐
| 工具 | 描述 |
|---|---|
| `list_tracks` | 获取 MP3 曲目列表 |
| `play_track` / `stop_music` | 播放/停止音乐 |
| `next_track` / `prev_track` | 下一曲/上一曲 |
| `play_random_track` | 随机播放曲目 |
| `set_loop` / `set_autoplay` | 设置循环/自动播放模式 |
| `set_music_volume` | 设置音乐音量 |
| `set_mcp_music` | 允许 MCP 控制音乐 |
### 闹钟和计时器
| 工具 | 描述 |
|---|---|
| `set_alarm_text` | 设置闹钟（时间 HH:MM, 文本） |
| `set_timer` | 启动计时器（分钟） |
| `get_alarm_timer_status` | 获取闹钟和计时器状态 |
### 其他
| 工具 | 描述 |
|---|---|
| `take_screenshot` | 截图 |
| `list_available_emotions` | 获取可用情绪列表 |
| `query_documents` | 文档搜索（RAG） |
| `ingest_file` | 将文件索引到 RAG |
| `list_documents` | 获取已索引文档列表 |
| `rag_status` | 获取 RAG 状态 |
## 配置
主要配置在 `config.json` 中：
- TTS 引擎、语音、语速
- MCP 和网页界面端口
- STT、音乐、闹钟的启用/禁用
- 不同模式下的情绪和动画
- 交互对话短语
## 项目结构
```
├── run.py # 入口点
├── mcp_server.py # MCP 服务器
├── live2d_display.py # Live2D 渲染（PyQt6 + OpenGL）
├── talk.py # 对话逻辑和交互性
├── tts.py # TTS 引擎（Piper）
├── stt.py # 语音识别
├── music_player.py # 音乐播放器
├── alarm_timer.py # 闹钟和计时器
├── voice_bridge.py # 语音桥接
├── web_ui.py # 网页界面（Starlette + uvicorn）
├── mcp_client.py # MCP 客户端
├── phrases.py / .json # 角色短语
├── ui.js # 网页界面客户端代码
├── rag/ # RAG 引擎
├── play_modes/ # 游戏模式
└── assets/live2d/ # Live2D 和精灵模型（Hiyori, Nagatoro_sprite）
```
## 安全
该应用程序不会向互联网发送数据（除了首次启动时下载 STT/TTS 模型）。MCP 服务器仅监听 `127.0.0.1`。
