Yandex SpeechKit MCP

MCP Server для интеграции с Yandex Cloud SpeechKit - предоставляет возможности синтеза речи (TTS) и распознавания речи (STT) через Model Context Protocol.

claude mcp add yandex-speechkit-mcp -e YANDEX_API_KEY=AQ... -e YANDEX_FOLDER_ID=... -- npx -y yandex-speechkit-mcp

🎯 Возможности

Text-to-Speech (TTS)

• ✅ Синтез речи из текста с современными голосами
• ✅ SSML поддержка с валидацией и шаблонами
• ✅ Поддержка эмоций и регулируемой скорости речи
• ✅ Batch синтез нескольких текстов
• ✅ Множественные форматы аудио (OGG Opus, LPCM, MP3)
• ✅ Русский, английский и турецкий языки
• ✅ Премиум голоса с высоким качеством

Speech-to-Text (STT)

• ✅ Интеллектуальный выбор оптимальных моделей
• ✅ Confidence scores и временные метки для каждого слова
• ✅ Специализированные модели (общие, карты, даты, имена, числа)
• ✅ Автоматические рекомендации по настройкам
• ✅ Фильтр нецензурной лексики
• ✅ Поддержка множественных аудио форматов
• ✅ Русский, английский и турецкий языки

Утилиты

• ✅ Расширенная аналитика качества распознавания
• ✅ Валидация аудио файлов с детальной информацией
• ✅ ModelRepository для управления моделями
• ✅ Список голосов по языкам и типам (стандарт/премиум)
• ✅ Информация о поддерживаемых форматах и языках
• ✅ Автоматическая очистка временных файлов

📦 Установка

npm install yandex-speechkit-mcp

⚙️ Настройка

Получение учетных данных

Вариант 1: API-ключ (рекомендуется)

1. Перейдите в Yandex Cloud Console
2. Создайте сервисный аккаунт в разделе IAM
3. Назначьте роли ai.speechkit-hybrid.user или editor
4. Создайте API-ключ для сервисного аккаунта
5. Получите ID папки (folder ID) из консоли

Вариант 2: IAM-токен

1. Получите IAM-токен через CLI: yc iam create-token
2. Токен действует 12 часов, требует периодического обновления

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

Добавьте следующую конфигурацию в файл claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-speechkit": {
      "command": "npx",
      "args": ["yandex-speechkit-mcp"],
      "env": {
        "YANDEX_API_KEY": "AQVN...",
        "YANDEX_FOLDER_ID": "b1g...",
        "TEMP_DIR": "./temp",
        "DEFAULT_LANGUAGE": "ru-RU",
        "DEFAULT_VOICE": "oksana"
      }
    }
  }
}

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

| Переменная | Описание | Обязательная | По умолчанию | |------------|----------|--------------|--------------| | YANDEX_API_KEY | API-ключ Yandex Cloud | ✅* | - | | YANDEX_IAM_TOKEN | IAM-токен Yandex Cloud | ✅* | - | | YANDEX_FOLDER_ID | ID папки в Yandex Cloud | ✅ | - | | TEMP_DIR | Директория для временных файлов | ❌ | ./temp | | DEFAULT_LANGUAGE | Язык по умолчанию | ❌ | ru-RU | | DEFAULT_VOICE | Голос по умолчанию | ❌ | oksana |

*Требуется один из двух: API-ключ ИЛИ IAM-токен

🛠 Доступные инструменты

📚 Новые возможности: Подробная документация по SSML, ModelRepository и расширенным функциям доступна в FEATURES.md

Основные инструменты

speechkit_synthesize

Конвертирует текст в речь с использованием современного Yandex Cloud API

Параметры:

• text (обязательный): Текст для синтеза (макс. 5000 символов) или SSML разметка
• voice: Голос (oksana, jane, omazh, zahar, ermil, alena, filipp, john, alyss)
• emotion: Эмоция (good, evil, neutral)
• lang: Язык (ru-RU, en-US, tr-TR)
• format: Формат аудио (oggopus, lpcm, mp3)
• speed: Скорость речи (0.1-3.0, например 1.0)
• ssml: Включить обработку SSML разметки (auto-detect)
• role: Роль голоса (neutral, good, evil)
• pitch: Высота тона (например, "+5%", "-10%")
• volume: Громкость (например, "+6dB", "-3dB")

Пример:

{
  "text": "Привет, мир!",
  "voice": "oksana",
  "emotion": "good",
  "format": "oggopus",
  "speed": 1.0
}

speechkit_recognize

Распознает речь из аудио файла с использованием современного API

Параметры:

• audioPath (обязательный): Путь к аудио файлу
• topic: Тема распознавания (general, maps, dates, names, numbers)
• lang: Язык (ru-RU, en-US, tr-TR)
• profanityFilter: Фильтр нецензурной лексики (true/false)
• format: Формат аудио (oggopus, wav, mp3, flac, speex)
• sampleRateHertz: Частота дискретизации (8000, 16000, 48000)
• model: Модель распознавания (auto-select если не указано)
• audioProcessingType: Тип обработки (full, basic)
• rawResults: Вернуть детальные результаты с confidence scores

Пример:

{
  "audioPath": "/path/to/audio.wav",
  "topic": "general",
  "lang": "ru-RU",
  "profanityFilter": true
}

speechkit_list_voices

Получает список доступных голосов с разделением на стандартные и премиум

Параметры:

• lang: Язык для фильтрации голосов (ru-RU, en-US, tr-TR)

speechkit_supported_formats

Возвращает поддерживаемые аудио форматы для TTS и/или STT

Параметры:

• service: Тип сервиса (tts, stt, both)

speechkit_supported_languages

Возвращает поддерживаемые языки с количеством голосов

speechkit_validate_audio

Проверяет существование и валидность аудио файла с детальной информацией

Параметры:

• audioPath (обязательный): Путь к аудио файлу

speechkit_supported_topics

Возвращает поддерживаемые темы распознавания с описаниями

Расширенные инструменты

speechkit_batch_synthesize

Массовый синтез нескольких текстов за один запрос

Параметры:

• texts (обязательный): Массив текстов для синтеза
• voice, lang, format, speed: Общие настройки для всех текстов

speechkit_synthesize_template

Синтез с использованием SSML шаблонов

Параметры:

• templateName (обязательный): Имя шаблона (greeting, announcement, number, time, date, phone, emotional)
• variables (обязательный): Переменные для подстановки в шаблон
• voice, lang, format: Дополнительные настройки

speechkit_validate_ssml

Валидация SSML разметки

Параметры:

• ssml (обязательный): SSML текст для проверки

speechkit_get_models

Получение списка доступных моделей распознавания

speechkit_recommend_model

Автоматическая рекомендация оптимальной модели

Параметры:

• audioPath (обязательный): Путь к аудио файлу
• language: Предпочитаемый язык
• topic: Предпочитаемая тема

speechkit_recognize_with_confidence

Распознавание с детальными confidence scores и временными метками

Параметры:

• Аналогично speechkit_recognize
• Автоматически включает rawResults=true и audioProcessingType=full

📊 Поддерживаемые форматы

TTS (вывод)

• oggopus (.ogg) - рекомендуется, наименьший размер
• lpcm (.wav) - несжатый, лучшее качество
• mp3 (.mp3) - широкая совместимость

STT (ввод)

• oggopus - OGG Opus
• wav - WAV (рекомендуется)
• mp3 - MP3
• flac - FLAC lossless
• speex - Speex

🌍 Поддерживаемые языки

• Русский (ru-RU): 7 голосов
  • Стандартные: oksana, jane, omazh, zahar, ermil
  • Премиум: alena, filipp
• Английский (en-US): 2 голоса (john, alyss)
• Турецкий (tr-TR): 2 голоса (erkanyavas, silaerkan)

🔧 Разработка

Сборка из исходников

git clone <repository>
cd yandex-speechkit-mcp
npm install
npm run build

Запуск в режиме разработки

npm run dev

Тестирование с помощью MCP Inspector

npm run build
npm run inspector

📦 Публикация в NPM

Подготовка к публикации

1. Обновление версии

   npm version patch  # для багфиксов (1.1.0 → 1.1.1)
   npm version minor  # для новых функций (1.1.0 → 1.2.0)  
   npm version major  # для breaking changes (1.1.0 → 2.0.0)

2. Проверка конфигурации

   • Убедитесь, что в package.json указаны правильные:
     • name: yandex-speechkit-mcp
     • main: dist/index.js
     • bin: ./dist/index.js
     • files: включены нужные файлы
     • repository, bugs, homepage: ссылки на GitHub

3. Сборка проекта

   npm run build

Публикация

1. Авторизация в NPM (одноразово)

   npm login

2. Публикация пакета

   npm publish

3. Проверка публикации

   npm view yandex-speechkit-mcp

Автоматизация публикации

Скрипт prepublishOnly в package.json автоматически выполняет сборку перед публикацией:

{
  "scripts": {
    "prepublishOnly": "npm run build"
  }
}

Проверка перед публикацией

# Проверить содержимое пакета
npm pack --dry-run

# Установить локально для тестирования  
npm pack
npm install -g ./yandex-speechkit-mcp-1.1.0.tgz

🐛 Troubleshooting

Распространенные проблемы

1. Ошибка аутентификации

   • Убедитесь, что YANDEX_API_KEY или YANDEX_IAM_TOKEN установлены
   • Проверьте правильность YANDEX_FOLDER_ID
   • Для IAM-токена: проверьте, что токен не истек (12 часов)

2. Ошибка "Audio file not found"

   • Проверьте существование файла по указанному пути
   • Убедитесь, что файл не поврежден и имеет поддерживаемый формат

3. Ошибки HTTP 403/401

   • Проверьте права сервисного аккаунта
   • Убедитесь, что назначена роль ai.speechkit-hybrid.user

4. Проблемы с кодировкой

   • Убедитесь, что текст для TTS в правильной кодировке UTF-8

Логи и отладка

Сервер выводит ошибки в stderr:

node dist/index.js 2> debug.log

📄 Лицензия

MIT

🔗 Связанные проекты

• Yandex Cloud SpeechKit
• Model Context Protocol

📈 Версии

v1.1.0 (Текущая) - Enhanced AI Features

• 🆕 SSML поддержка с валидацией и готовыми шаблонами
• 🆕 ModelRepository для интеллектуального выбора моделей STT
• 🆕 Confidence scores и временные метки для каждого слова
• 🆕 Batch синтез нескольких текстов
• 🆕 6 новых MCP инструментов для расширенной функциональности
• 🆕 Автоматические рекомендации по настройкам
• 🆕 Расширенная аналитика качества распознавания

v1.0.0 (Стабильная)

• ✅ Современный Yandex Cloud SpeechKit API
• ✅ Поддержка API-ключей и IAM-токенов
• ✅ Расширенная поддержка языков и голосов
• ✅ Улучшенная обработка ошибок
• ✅ Более детальная валидация и информация

v0.1.0 (Legacy)

• Устаревший Developer API (больше не поддерживается)