by dannguyen9x (community) · Windows, Node.js 20+, Claude Desktop, Claude Code, OpenCode, любой MCP-клиент

TikTok LIVE Studio MCP

Локальный сервер Model Context Protocol для Windows, позволяющий Codex, Claude Code, Claude Desktop и другим клиентам MCP через stdio управлять TikTok LIVE Studio через локальный канал Stream Deck Socket.IO.

Сервер не использует автоматизацию мыши, OCR, автоматизацию браузера или экранные координаты. Он обнаруживает запущенный процесс LIVE Studio и его порт, проверяет протокол, подтверждает каждое действие и проверяет изменяемое состояние.

Сообщество проекта. Не связано с TikTok, ByteDance, Elgato, Anthropic или OpenAI.

Возможности

Двенадцать типизированных инструментов MCP для статуса, сцен, источников, аудио, микрофона, записи, действий и управления LIVE.
Официальный SDK MCP TypeScript с транспортом stdio.
Обнаружение процесса Windows, установленной версии и порта, принадлежащего процессу.
Автоматическое повторное обнаружение при перезапуске LIVE Studio на другом порту.
Идемпотентные операции со сценами/источниками/аудио/микрофоном/записью/LIVE.
Проверка результата действия плюс верификация состояния после действия.
Блокировка мутации между процессами для нескольких локально настроенных клиентов MCP.
Структурированный контракт ошибок и компактные журналы доказательств в формате JSONL.
Мок Socket.IO, контракт MCP, реальная безопасная интеграция, опциональная полная интеграция, собранный stdio, упаковка и контроль релизов.

Требования

Windows 10 или Windows 11.
Node.js 20 или новее.
Установлен TikTok LIVE Studio. Запустите его перед выполнением doctor или проверкой реальной интеграции.

Быстрый старт

git clone https://github.com/dannguyen9x/tiktok-live-studio-mcp.git
cd tiktok-live-studio-mcp
npm.cmd ci
npm.cmd run build
npm.cmd run doctor
npm.cmd run mcp:smoke

Затем подключите ваш клиент MCP, используя руководство по настройке клиента. Для полного руководства, модели безопасности, примеров, обновлений и шагов удаления прочитайте полное руководство пользователя или руководство пользователя на вьетнамском.

Запустите сервер напрямую:

npm.cmd start

MCP использует stdout, поэтому обычные журналы выполнения записываются в artifacts/evidence/runtime.jsonl вместо stdout.

Конфигурация MCP‑клиента

Скопируйте соответствующий пример и замените C:/path/to/tiktok-live-studio-mcp абсолютным путём к клону:

.mcp.json.example
config/claude-desktop.example.json
config/claude-code.example.json
config/codex.example.toml

Общая конфигурация stdio выглядит так:

{
  "mcpServers": {
    "tiktok-live-studio": {
      "command": "node",
      "args": [
        "C:/path/to/tiktok-live-studio-mcp/dist/src/index.js"
      ],
      "env": {
        "TTLS_LOG_PATH": "C:/path/to/tiktok-live-studio-mcp/artifacts/evidence/runtime.jsonl"
      }
    }
  }
}

Перезапустите MCP‑клиент после изменения его конфигурации.

Для текущих команд CLI Codex и Claude Code, настройки Claude Desktop, настройки общего клиента и шагов проверки см. docs/CLIENT_SETUP.md.

Примеры запросов

После подключения сервера задавайте ваш клиент MCP естественно:

Check whether TikTok LIVE Studio is connected and list my scenes.
Switch LIVE Studio to the exact scene "Gameplay".
Hide source "Starting Soon" in scene "Gameplay".
Mute the microphone in LIVE Studio.
Start a local recording, but do not start LIVE.

Для изменения состояния LIVE явно авторизуйте вызов специализированного инструмента:

Start LIVE using studio_start_live with confirm set to true.

Всегда проверяйте состояние аккаунта, аудитории, сцены, аудио и записи перед авторизацией действия LIVE.

Инструменты

Инструмент	Поведение
`studio_get_status`	Чтение статуса запуска, подключения, версии приложения, конечной точки, активной сцены, состояния записи и состояния LIVE.
`studio_list_scenes`	Список сцен и активной сцены.
`studio_switch_scene`	Идемпотентно переключиться на точную сцену и проверить её.
`studio_list_sources`	Список имён источников, внутренних ID и видимости для активной или названной сцены.
`studio_set_source_visibility`	Установить видимость источника без слепого переключателя; при необходимости временно переключить/восстановить сцену.
`studio_set_microphone_mute`	Идемпотентно установить и проверить заглушку агрегированного микрофона.
`studio_set_audio_mute`	Идемпотентно установить и проверить заглушку desktop/audio‑выхода.
`studio_start_recording`	Начать запись только при остановленной и проверить состояние.
`studio_stop_recording`	Остановить запись только при активной и проверить состояние.

| studio_trigger_action | Запустить проверенное действие Stream Deck без параметров и требовать подтверждения от LIVE Studio. | | studio_start_live | Требовать confirm:true, запустить LIVE из читаемого офлайн‑состояния и проверить состояние LIVE. | | studio_stop_live | Требовать confirm:true, остановить LIVE и проверить офлайн‑состояние. |

Перечисление общих действий содержит live-pause, highlight, recording-gallery, co-host, treasure-box, say-hi, guess-game, play-together, goody-bag, team, game-rewards, live-goal, multi-guest, vote, promote и viewer-wishes.

Некоторые общие действия условны. LIVE Studio возвращает код результата -1, когда проверенное действие существует, но текущий аккаунт, состояние LIVE, право участия или состояние панели не позволяют его выполнить. Инструмент MCP возвращает это как структурированный результат ACTION_FAILED, а не притворяется, что действие выполнено успешно.

Проверенный локальный протокол

Поле	Значение
Конечная точка	`ws://127.0.0.1:<discovered-process-port>`
Путь Socket.IO	`/socket.io/`
Пространство имен	`/`
Транспорт	`websocket`
Подпротокол WebSocket	`streamdeck_ttls_v1`
Присоединение	`stream_deck/join_room` раз на соединение
Состояние	`stream_deck/sync_settings`
Действие	`stream_deck/action_emit`
Результат действия	`stream_deck/<unique-context>`

Контракт был проверен на LIVE Studio 1.33.2. См. docs/PROTOCOL.md для полезных нагрузок, значений статуса, идентификаторов действий и происхождения доказательств.

Надёжность и модель безопасности

Каждая мутация захватывает блокировку %TEMP%\tiktok-live-studio-mcp.mutation.lock, считывает текущее состояние, выдаёт не более одного действия, проверяет читаемое состояние и освобождает блокировку.
Владелец блокировки, который упал, обнаруживается по PID и восстанавливается.
Операции с источниками восстанавливают исходную сцену в блоке finally.
Мутации типа переключения никогда не повторяются автоматически после неопределённого результата.
Запуск и остановка LIVE требуют буквального confirm:true.
Отключения запускают повторное обнаружение процесса и порта вместо бесконечных попыток соединения с устаревшим конечным пунктом.
Некорректные настройки или ответы действий вызывают PROTOCOL_MISMATCH.

Каждая ошибка инструмента содержит:

code, message, operation, appVersion, endpoint, socketEvent,
attempt, suggestedFix, evidencePath

Тесты

Проверки, безопасные для CI:

npm.cmd run test:ci

Безопасная реальная интеграция с открытым LIVE Studio:

npm.cmd run doctor
npm.cmd run test:integration
npm.cmd run mcp:smoke
npm.cmd run smoke

Безопасный реальный набор переключает/восстанавливает сцену, изменяет/восстанавливает видимость источников и изменяет/восстанавливает отключение микрофона. Он никогда не запускает LIVE.

Для намеренно включённого вручную реального аудио, записи, LIVE и шлюза общего действия прочтите docs/FULL_INTEGRATION.md. Требуется явное подтверждение переменных окружения и формируется отчёт о восстановлении.

Доказательства полного локального релиза

npm.cmd run verify:final

См. docs/VERIFICATION.md, чтобы узнать, что доказывает каждый шлюз.

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

npm.cmd run protocol:research

Это выполняет npm view ttls-controller --json, скачивает опубликованный пакет с помощью npm pack ttls-controller, записывает официальные метаданные Elgato Marketplace и хеширует файлы, несущие протокол, из установленной версии LIVE Studio. Сгенерированная машинозависимая доказательная база исключается из Git; см. artifacts/README.md.

Структура проекта

src/mcp/                 MCP server and schemas
src/domain/              state policy, errors, mutation lock
src/adapters/ttls/       Socket.IO protocol adapter
src/discovery/           Windows process/version/port discovery
src/logging/             structured JSONL logging
tests/unit/              mock Socket.IO and domain tests
tests/contract/          MCP and protocol contract tests
tests/integration/       safe real LIVE Studio integration
scripts/                 doctor, smoke, research, full and release gates
docs/                    protocol, architecture, and verification guides

Вклад и безопасность

Прочтите CONTRIBUTING.md перед отправкой изменения. Сообщайте об уязвимостях через закрытое сообщение об уязвимостях GitHub, как описано в SECURITY.md. Не публикуйте сырые журналы доказательств, учётные данные, записи, данные учётной записи или проприетарные пакеты LIVE Studio.

Документация

Лицензия

MIT. См. LICENSE.