obs-action-history

MCP-сервер для OBS Studio, который умеет слышать.

Уже есть несколько таких. Большинство из них оборачивают поверхность запросов obs-websocket по одному вызову за раз и на этом останавливаются. Это разумная вещь для создания, и она даёт инструмент, который может умело управлять OBS. Но также она даёт инструмент, который в конкретном и важном смысле глух.

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

Ноль зависимостей. Только встроенные модули Node. Windows, macOS и Linux.

Различие, которое имеет значение

Запрос отвечает ровно на один вид вопроса: что истинно в данный момент. Вы спрашиваете, OBS отвечает, вы решаете. Всё, что произошло между одним вызовом и следующим, исчезло, и у вас нет способа узнать, что оно вообще было.

Звучит как архитектурное примечание. Это не так. Подумайте, чего это вам стоит.

В протоколе obs-websocket нет запроса, который возвращает уровень аудио. GetInputVolume даёт позицию фейдера. GetInputMute даёт булево значение. Ни один из них ничего не говорит о том, действительно ли звук выходит из этого микрофона. Уровни существуют только в одном месте — как InputVolumeMeters, и это событие.

Поэтому вопрос «работает ли мой микрофон прямо сейчас» не может быть отвечен сервером, построенным чисто на запросах. Не плохо отвечен, не медленно отвечен, а вообще не отвечен. Сервер, предоставляющий 148 инструментов, имеет ровно то же слепое пятно, что и сервер с двенадцатью, потому что ответ не находится на поверхности, из которой они оба черпают.

Этот сервер удерживает этот поток:

obs_who_is_talking  ->  Mic A    peak -36.9 dB   29 samples
                        Mic B    peak -37.8 dB   29 samples
                        Music    peak -54.2 dB   29 samples

InputVolumeMeters приходит примерно пятьдесят раз в секунду на источник. Никому не нужны три тысячи сырых кадров в ответ на вызов инструмента. Вопрос, который на самом деле есть у человека, — кто был громким, поэтому метры вообще не попадают в буфер. Они сводятся к пику на источник и возвращаются как ответ.

Что это даёт вам конкретно

Микрофон, который настроен правильно и не выдаёт ничего. Фейдер на единице, не заглушён, но выбрано не то устройство или кабель тихо мёртв. Каждая настройка, до которой может дотянуться запрос, сообщает о полном здоровье. Это не гипотеза; именно поэтому установка, из которой это появилось, нуждалась в отдельном процессе проверки микрофона до того, как это появилось.

Камера, которая следует за голосом. Вам нужно знать, какой из двух микрофонов громче, непрерывно, и сравнивать их друг с другом, а не с каким-то фиксированным порогом, потому что два микрофона в одной комнате имеют разное усиление, и каждый из них слышит всех. Здесь нечего опрашивать. Информация приходит только по мере её возникновения.

Что-то живое и застрявшее, что хуже, чем мёртвое. Во время разработки этот сервер обследовал пять медиаисточников, и каждый из них сообщал PLAYING. Один продвинулся на ноль миллисекунд, в то время как другие двигались примерно на 2 540. По состоянию они были неразличимы. Только прошедшее время отделяло работающий поток от трупа, и именно эта слепота уже скрывала семнадцать часов тихой музыки за приборной панелью, показывающей зелёный.

Что произошло две минуты назад. Опросчик может описать настоящее и ничего больше. Как только что-то прошло, оно просто недоступно, и вы вынуждены гадать о самом инциденте, который пытаетесь объяснить.

Описания — часть продукта

Описание инструмента — это не место для повторения списка параметров. Модель уже может прочитать схему. Это место, где вы размещаете вещи, которые в противном случае будут изучены дорогим способом:

• Смещение синхронизации аудио OBS ограничено примерно 960 мс. Большие значения молча применяются как ничто, поэтому вы считаете, что компенсировали двухсекундную задержку, а на самом деле не компенсировали ничего.

• Индекс 0 элемента сцены — это низ, и полноэкранный источник, расположенный над фоном, полностью скрывает его, и нигде не возникает ошибки.

• Источник, размещённый за пределами холста, всё ещё виден и всё ещё воспроизводит свой звук. Скрытие его вместо этого действительно обрезает звук, поэтому аудио-оверлей размещается за пределами, а не скрывается.

• RemoveInput сообщает об успехе и не удаляет источник, на который что-то ещё ссылается.

• Поля границ инертны, если сначала не установлен boundsType.

• TriggerHotkeyByName принимает простое имя, а libobs.mute регистрируется один раз на каждый аудиоисточник, двадцать четыре раза на эталонной машине. Поэтому горячие клавиши не могут адресовать конкретный источник, что бы вы ни предполагали.

Каждый из этих пунктов кому-то чего-то стоил. Они записаны, потому что модель, которая их не знает, будет действовать уверенно и ошибаться, что гораздо хуже, чем действовать неуверенно и быть правой.

Инструмент, который делает возможной новую машину

obs_input_property_items перечисляет реальные варианты за свойством источника: каждую веб-камеру и каждое аудиоустройство с идентификаторами, которые OBS действительно ожидает.

Microphone (Some USB Mic)
  -> {0.0.1.00000000}.{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

В этом нет ничего человекочитаемого, что можно было бы угадать. Без этого вызова ассистент может только настраивать источники, которые человек уже создал вручную. С ним он может создавать их с нуля.

Что покрыто

67 инструментов в одиннадцати модулях.

Установка

Вам нужен Node 22 или новее для глобального WebSocket, и OBS 31+ с отмеченным Tools → WebSocket Server Settings → Enable WebSocket server.

Скопируйте .mcp.example.json в конфигурацию вашего MCP-клиента и укажите args на server.js. Пароль читается из OBS_WEBSOCKET_PASSWORD, когда он установлен, и в противном случае из secrets.json рядом с сервером:

{ "obsPassword": "the value from OBS > Tools > WebSocket Server Settings" }

Имейте в виду, что неправильный пароль не выглядит как неправильный пароль. OBS принимает сокет, а затем закрывает его с кодом 4009, который большинство клиентов сообщают как тайм-аут, и вы проведёте свой день, исследуя свою сеть. Этот сервер называет это правильно.

Эталонная машина

Цифры, упомянутые по всему тексту, такие как 43 вида фильтров, 411 горячих клавиш, из которых только 88 уникальны, потолок 960 мс, пять выходов и два буфера повтора, были измерены на OBS 32.2.1 с obs-websocket 5.7.4 на Windows, пока эта машина вела прямую трансляцию на три платформы. Это то, что эталонная машина означает везде, где она появляется. Ваша установка будет отличаться в некоторых местах, и каждое из этих чисел можно проверить с помощью инструментов здесь, что и является смыслом их указания, а не округления в неопределённость.

Две ошибки в опубликованной документации obs-websocket всплыли таким образом и обходятся. GetSourceFilterKindList возвращает sourceFilterKinds, тогда как документация говорит filterKinds. И SetSourceFilterSettings.overlay по умолчанию true, тогда как сводка утверждала false; передача false вызывает obs_source_reset_settings и уничтожает все остальные настроенные значения на этом фильтре, что является ошибкой, которую вы совершаете один раз.

Вклад

mcp/tools/index.js содержит контракт. Модуль экспортирует (obs) => [ { name, description, inputSchema, handler } ] и может использовать obs.request(type, data) и ничего больше.

Загрузка намеренно отказоустойчива. Модуль, который отсутствует, который выбрасывает ошибку при сборке, который возвращает некорректный инструмент или который дублирует имя, логируется и пропускается, и сервер всё равно запускается со всем остальным. Ваш сломанный модуль — ваша проблема и не должен стать чьей-то мёртвой трансляцией.

Перед открытием pull request:

npm run preflight

Он отказывает в учётных данных, абсолютных путях, машинно-специфичных адресах и идентификаторах устройств в любом месте дерева, и проверяет, что каждый модуль всё ещё загружается.

Статус

0.1.0. Имена инструментов могут ещё измениться до 1.0. Закрепите точную версию, если вы пишете скрипты против них.

Лицензия

MIT. См. LICENSE.