# MCP Yandex Voice — голосовые ответы в Cursor

MCP-сервер для Cursor: по сообщению из чата получает ответ от **Yandex GPT** (AI Studio) и озвучивает его через **Yandex SpeechKit TTS**. В чате можно вызывать инструмент и получать ответ текстом и аудио.

## Что нужно

- Доступ к [Yandex Cloud AI Studio](https://yandex.cloud/en/services/ai-studio) (Yandex GPT).
- Включённый [SpeechKit](https://cloud.yandex.com/en/docs/speechkit/) (TTS) в том же каталоге (folder).
- API-ключ сервисного аккаунта с ролями в каталоге:
  - `ai.languageModels.user` (Yandex GPT)
  - `ai.speechkit-tts.user` (SpeechKit TTS)

## Настройка доступа к Yandex Cloud

**Подробная инструкция:** [docs/YANDEX-CLOUD-SETUP.md](docs/YANDEX-CLOUD-SETUP.md)

Включает:

- Регистрацию и создание каталога
- Включение AI Studio и SpeechKit
- Создание сервисного аккаунта и добавление ролей в каталоге (`ai.languageModels.user`, `ai.speechkit-tts.user`)
- Создание API-ключа (через консоль или YC CLI)
- Проверку доступа через curl
- Разбор частых ошибок

## Установка

```bash
cd mcp-yandex-voice
npm install
npm run build
```

## Переменные окружения

Скопируйте `.env.example` в `.env` и заполните:

| Переменная | Обязательно | Описание |
|------------|-------------|----------|
| `YANDEX_API_KEY` или `YC_API_KEY` | да | API-ключ сервисного аккаунта |
| `YANDEX_FOLDER_ID` или `YC_FOLDER_ID` | да | ID каталога в Yandex Cloud |
| `YANDEX_MODEL` | нет | Модель (по умолчанию `yandexgpt-lite`) |
| `YANDEX_TTS_VOICE` | нет | Голос TTS (по умолчанию `alena`) |
| `YANDEX_TTS_LANG` | нет | Язык (по умолчанию `ru-RU`) |
| `YANDEX_TTS_FORMAT` | нет | Формат аудио (по умолчанию `oggopus`) |
| `YANDEX_TTS_SPEED` | нет | Скорость речи: 0.1–3.0 (по умолчанию 1.0). 1.2–1.5 — быстрее |
| `YANDEX_GPT_MAX_TOKENS` | нет | Макс. токенов ответа GPT (по умолчанию 350). Меньше — быстрее ответ |

## Подключение в Cursor

В корне репозитория уже есть конфиг **`.cursor/mcp.json`**. Подставьте в нём свои `YANDEX_API_KEY` и `YANDEX_FOLDER_ID` в блоке `env` для сервера `yandex-voice`, затем перезапустите Cursor.

Либо настройте вручную:

1. Откройте **Cursor Settings → MCP** (или конфиг MCP вручную).
2. Добавьте сервер, например в `~/.cursor/mcp.json` или в настройках проекта:

```json
{
  "mcpServers": {
    "yandex-voice": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/leetcode/mcp-yandex-voice/dist/index.js"],
      "env": {
        "YANDEX_API_KEY": "ваш_api_ключ",
        "YANDEX_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}
```

Замените `ABSOLUTE/PATH/TO/leetcode` на полный путь к репозиторию. После `npm run build` исполняемый файл — `dist/index.js`.

Вариант с `tsx` (без сборки):

```json
{
  "mcpServers": {
    "yandex-voice": {
      "command": "npx",
      "args": ["tsx", "/ABSOLUTE/PATH/TO/leetcode/mcp-yandex-voice/src/index.ts"],
      "env": {
        "YANDEX_API_KEY": "ваш_api_ключ",
        "YANDEX_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}
```

3. Перезапустите Cursor или перезагрузите MCP.

## Инструмент `speak_response`

- **Название:** Голосовой ответ (speak_response)
- **Вход:**
  - `message` — вопрос пользователя; Yandex GPT генерирует ответ и озвучивает.
  - `textToSummarize` — текст ответа ассистента; Yandex GPT кратко пересказывает (2–3 предложения) и озвучивает. Используй для озвучивания своих ответов.
  - `systemPrompt` (опционально) — системный промпт (роль, стиль). При `textToSummarize` не используется.
- **Выход:** текст и аудио (base64). Cursor может отобразить текст и воспроизвести аудио.

Нужен один из `message` или `textToSummarize`. Режим `textToSummarize` — для краткого озвучивания длинных ответов Cursor.

## Инструмент `playback_control`

- **Название:** Остановка / пауза воспроизведения (playback_control)
- **Вход:** `action` — `"stop"` или `"pause"` (остановить текущее воспроизведение).
- **Выход:** сообщение об успехе или подсказка.

Работает только на macOS. Останавливает воспроизведение, запущенное через **afplay** (ответы Yandex Voice в формате WAV). Если воспроизведение идёт через приложение по умолчанию (OGG), остановите его вручную. В чате можно написать: «Останови воспроизведение» или «Вызови playback_control с action stop».

### Кнопки управления воспроизведением (пауза/стоп)

Пока MCP-сервер запущен (Cursor с подключённым yandex-voice), на macOS поднимается локальная панель с кнопками:

- Открой в браузере: **http://127.0.0.1:3846**
- Кнопки **Стоп** и **Пауза** останавливают текущее воспроизведение ответа Yandex Voice (работает только для afplay/WAV).

Держи вкладку открытой или добавь в закладки — во время озвучки ответа можно нажать «Стоп» прямо из браузера, без запроса в чате.

## Локальная проверка

Запуск через stdio (для отладки или MCP Inspector):

```bash
export YANDEX_API_KEY=... YANDEX_FOLDER_ID=...
npm run dev
# или после сборки:
npm start
```

Сервер общается по stdin/stdout; для теста можно использовать [MCP Inspector](https://modelcontextprotocol.io/legacy/tools/inspector):  
`npx @modelcontextprotocol/inspector node dist/index.js`

## Ускорение ответов

Чтобы диктор отвечал быстрее:

1. **`YANDEX_TTS_SPEED=1.3`** — ускорить речь (1.2–1.5 — комфортно, до 3.0 — максимально быстро).
2. **`YANDEX_GPT_MAX_TOKENS=250`** — короче ответы GPT → меньше времени на генерацию и синтез.

Чанки TTS обрабатываются параллельно, что ускоряет длинные ответы.

## Ограничения

- SpeechKit TTS: размер одного запроса ограничен (в коде текст разбивается на чанки по 500 символов).
- Для длинных ответов генерация и синтез могут занять несколько секунд.

## Лицензия

MIT.