Live2D MCP Companion

Интерактивный десктопный компаньон с Live2D-моделью, управляемый через MCP (Model Context Protocol). Работает на Windows.

Возможности

• Live2D-персонаж — анимированная модель Hiyori на десктопе (через PyQt6 + OpenGL)
• TTS (Text-to-Speech) — голосовой вывод через Piper TTS (русские голоса: Irina, Denis, Ruslan)
• STT (Speech-to-Text) — распознавание речи через faster-whisper ⚠️ (временно не работает)
• MCP сервер — 36 инструментов для управления персонажем через любой MCP-клиент
• RAG (Retrieval-Augmented Generation) — семантический поиск по документам
• Веб-интерфейс — управление через браузер на http://localhost:8766
• Музыкальный плеер — воспроизведение MP3 через pygame
• Будильник и таймер — с MCP-уведомлениями
• Скриншоты — снимок экрана с реакцией персонажа
• Игровые режимы — прятки, танцы, эмоции и др.
• Дополнительные модели — Nagatoro Sprite (спрайтовая модель в отдельном репозитории)

Системные требования

• Windows 10/11
• Python 3.12+
• Видеокарта с поддержкой OpenGL
• Микрофон (для STT)

Установка

1. Клонировать репозиторий

git clone https://github.com/nukkerman2000/live2d-mcp.git
cd live2d-mcp

2. Установить портабельный Python

Скачайте embeddable Python 3.12 и распакуйте в папку python\.

Либо используйте системный Python.

3. Установить зависимости

Запустите setup_python.bat или выполните вручную:

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
• ru_RU-denis-medium
• ru_RU-ruslan-medium

6. Загрузить Piper TTS бинарники

Скачайте Piper TTS для Windows и распакуйте piper.exe и DLL в папку piper\.

Запуск

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.