livechat-mcp

Сервер протокола контекста модели (MCP), который позволяет вести непрерывный голосовой диалог с вашим ИИ-ассистентом для программирования. Вы говорите, ваша речь локально транскрибируется с помощью Whisper, и каждое высказывание передается ассистенту так, как если бы вы напечатали его вручную. Никакого переключения вкладок, копирования/вставки или пакетной записи.

Работает с любым MCP-хостом. Поддержка первого класса для:

• Claude Code

• Codex CLI

• Gemini CLI

Требования

• macOS, Linux или Windows (нативно через PowerShell или в WSL2 / Git Bash).

• Python 3.10+

• Установленный MCP-хост (Claude Code, Codex, Gemini и т. д.)

• Исправный микрофон

• ~500 МБ дискового пространства для кэша модели Whisper + зависимости

• uv для управления проектом (рекомендуется)

Быстрая установка (рекомендуется)

Из клона репозитория:

# macOS / Linux / Git Bash on Windows
./install.sh

# Native Windows PowerShell
.\install.ps1

Скрипт начальной загрузки определяет ОС, при необходимости устанавливает portaudio (brew / apt / dnf / pacman / zypper — в Windows-сборках он уже включен), устанавливает uv, если он отсутствует, запускает uv sync, помещает мастер настройки в ~/.local/bin и запускает интерактивный мастер настройки.

Windows: нативная блокировка использует msvcrt, а сигнал о перехвате основан на файлах, поэтому зависимость fcntl не требуется. Интерактивный мастер — это bash-скрипт, install.ps1 вызывает его через Git Bash, который он предложит установить через winget, если он отсутствует.

Ручная настройка

Если вы предпочитаете устанавливать пошагово, вот что делает install.sh:

1. Установка portaudio

sounddevice требует portaudio.

• macOS: brew install portaudio

• Debian/Ubuntu: sudo apt-get install libportaudio2 portaudio19-dev

• Fedora/RHEL: sudo dnf install portaudio portaudio-devel

• Arch: sudo pacman -S portaudio

2. Установка uv, если он отсутствует

curl -LsSf https://astral.sh/uv/install.sh | sh

3. Клонирование и установка зависимостей

cd livechat-mcp
uv sync

Это создаст .venv/ и установит mcp, faster-whisper, sounddevice, silero-vad, torch и т. д.

4. Запуск мастера настройки

install -m 0755 bin/livechat-mcp ~/.local/bin/livechat-mcp
livechat-mcp setup

Мастер выполнит следующее:

1. Спросит, для каких ассистентов выполнить установку (Claude Code / Codex / Gemini, любая комбинация).

2. Скопирует слэш-команды /livechat и /endlivechat для хостов, поддерживающих пользовательские слэш-команды. Для Codex он устанавливает как устаревшие файлы промптов, так и навык livechat, поскольку текущие версии Codex CLI не предоставляют пользовательские промпты как /livechat.

3. Зарегистрирует MCP-сервер в файле конфигурации каждого хоста.

4. Проведет вас через настраиваемые переменные окружения (порог тишины, модель Whisper и т. д.) — нажмите Enter, чтобы оставить значения по умолчанию.

Убедитесь, что ~/.local/bin находится в вашем PATH (это уже так, если вы использовали официальный установщик uv).

Если вы предпочитаете настроить все вручную, шаги для каждого хоста приведены ниже.

5. Предоставление разрешения на использование микрофона

• macOS: при первой попытке сервера захватить аудио macOS запросит у вашего терминального приложения (Terminal, iTerm, Ghostty, Warp и т. д.) доступ к микрофону. Если вы пропустили запрос, включите его вручную:

  Системные настройки → Конфиденциальность и безопасность → Микрофон → включите для вашего терминала

  Если пропустить этот шаг, захват аудио будет молча возвращать тишину, и ничего не будет транскрибироваться.

• Windows: Параметры → Конфиденциальность и защита → Микрофон → разрешить классическим приложениям доступ к микрофону (и убедитесь, что вашему терминалу разрешен доступ).

• Linux: обычно запрос не требуется — просто убедитесь, что у вашего пользователя есть правильный доступ к ALSA / PulseAudio / Pipewire (обычно группа audio).

6. Предварительная загрузка модели Whisper (опционально)

При первом запуске загружается base.en (~150 МБ). Вы можете предварительно загрузить её:

uv run python -c "from faster_whisper import WhisperModel; WhisperModel('base.en', device='cpu', compute_type='int8')"

Ручная установка (пропустите, если использовали livechat-mcp setup)

Claude Code

Скопируйте слэш-команды:

mkdir -p ~/.claude/commands
cp commands/livechat.md ~/.claude/commands/
cp commands/endlivechat.md ~/.claude/commands/

Зарегистрируйте MCP-сервер:

claude mcp add livechat -- uv --directory "$(pwd)" run livechat-mcp

Или отредактируйте ~/.claude.json напрямую:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

Codex CLI

Установите навык Codex и устаревшие файлы промптов:

mkdir -p ~/.codex/skills/livechat
cp skills/livechat/SKILL.md ~/.codex/skills/livechat/
mkdir -p ~/.codex/prompts
cp commands/livechat.md ~/.codex/prompts/
cp commands/endlivechat.md ~/.codex/prompts/

Зарегистрируйте MCP-сервер в ~/.codex/config.toml:

[mcp_servers.livechat]
command = "uv"
args = ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]

Gemini CLI

Gemini использует TOML для пользовательских команд. Мастер генерирует их для вас; чтобы сделать это вручную, см. commands/gemini/livechat.toml.template (создается после однократного запуска livechat-mcp setup).

Зарегистрируйте MCP-сервер в ~/.gemini/settings.json:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/livechat-mcp", "run", "livechat-mcp"]
    }
  }
}

Использование

Откройте CLI вашего ассистента в любом терминале:

claude    # or: codex    or: gemini

Затем в промпте ассистента:

/livechat            # Claude Code, Gemini CLI
use livechat         # Codex CLI

Требуется перезапуск Codex. Codex загружает навыки и MCP-серверы только при запуске. Если вы запускали мастер, пока Codex был открыт, закройте и перезапустите его перед использованием use livechat.

Codex 0.128.0 не поддерживает пользовательские слэш-команды /livechat; / в настоящее время зарезервирован для встроенных команд Codex. Установка добавляет обнаруживаемый навык livechat, поэтому вы можете ввести use livechat или открыть /skills и выбрать livechat.

Ассистент вызовет get_voice_input и начнет слушать. Говорите как обычно. Когда вы делаете паузу примерно на 1,5 секунды, ваше высказывание завершается, транскрибируется и отправляется как промпт. Ассистент отвечает, а затем сразу же начинает слушать следующее высказывание.

Пока ассистент генерирует ответ, микрофон остается активным — все, что вы скажете в это время, встанет в очередь и будет передано целиком при следующем вызове get_voice_input.

Завершение сессии

Три способа:

1. /endlivechat — самый чистый способ, запускается из промпта ассистента. (Вам нужно будет сначала прервать текущий ход, если он находится в процессе ответа.)

2. Кодовая фраза — скажите terminate voice session now. Транскрипция инициирует завершение работы. Фраза намеренно выбрана неудобной, чтобы избежать совпадений с реальным содержанием обзора. Настраивается через LIVECHAT_END_PHRASE.

3. Ctrl+C — завершает работу MCP-сервера. Ассистент увидит ошибку инструмента при следующем вызове и остановит цикл.

Конфигурация

Все настраиваемые параметры находятся в livechat_mcp/config.py и могут быть переопределены через переменные окружения:

Самый простой способ задать их — livechat-mcp set KEY VALUE — это отредактирует блок env в каждой конфигурации хоста, которую он найдет (Claude / Codex / Gemini).

livechat-mcp show           # print current env block(s)
livechat-mcp set LIVECHAT_SILENCE_SEC 1.5
livechat-mcp unset LIVECHAT_DEBUG

Перезапустите CLI ассистента после любых изменений — переменные окружения MCP считываются сервером при запуске.

Чтобы сделать это вручную, отредактируйте поле env записи livechat MCP в конфигурации каждого хоста. Пример для Claude Code:

{
  "mcpServers": {
    "livechat": {
      "command": "uv",
      "args": ["--directory", "/abs/path", "run", "livechat-mcp"],
      "env": {
        "LIVECHAT_WHISPER_MODEL": "small.en",
        "LIVECHAT_DEBUG": "1"
      }
    }
  }
}

Устранение неполадок

Ничего не происходит, когда я говорю. Проверьте (по порядку): разрешение микрофона для вашего терминального приложения, уровень входного сигнала микрофона (Системные настройки → Звук), установите LIVECHAT_DEBUG=1 и следите за stderr на наличие событий VAD, уменьшите LIVECHAT_VAD_THRESHOLD до 0.3.

Транскрипции неточные. Обновите модель: LIVECHAT_WHISPER_MODEL=small.en или medium.en. medium.en заметно медленнее на CPU (все еще почти в реальном времени), но гораздо лучше справляется с технической лексикой.

Высказывание заканчивается слишком быстро / слишком медленно. Настройте LIVECHAT_SILENCE_SEC (или выполните livechat-mcp set LIVECHAT_SILENCE_SEC 1.5). Диапазон 1.0–4.5 является полезным — меньшее значение ощущается более отзывчивым, но рискует прервать паузы в середине мысли.

uv не найден. Либо установите uv (рекомендуется), либо измените command в конфигурации MCP на прямой вызов python -m livechat_mcp.server из активированного venv.

Сервер запускается, но ассистент никогда не вызывает инструмент. Убедитесь, что /livechat был вызван. Без слэш-команды у ассистента нет инструкции для входа в цикл.

Логи сервера попадают в UI ассистента как мусор / нарушают протокол. Этого не должно происходить — все логи сервера идут в stderr. Если вы это видите, создайте баг-репорт. Убедитесь, что вы не добавили никаких операторов print(...) без file=sys.stderr.

Ошибки portaudio при запуске. Установите его: brew install portaudio. Если он установлен и все еще не работает, попробуйте brew reinstall portaudio и переустановите sounddevice: uv sync --reinstall.

Как это работает (кратко)

[mic] → [Silero VAD] → [Whisper] → [queue] ← [get_voice_input tool] ← [Assistant]
   ↑________background thread, always running________↑

Аудиоконвейер отделен от инструмента MCP, поэтому микрофон всегда активен, пока сервер запущен. Высказывания, произнесенные во время генерации ответа ассистентом, ставятся в очередь и передаются при следующем вызове инструмента.

Лицензия

MIT.