obs-action-history

Un servidor MCP para OBS Studio que puede oír.

Ya existen varios de estos. La mayoría envuelve la superficie de solicitudes de obs-websocket una llamada a la vez y se detiene ahí. Es algo razonable de construir, y produce una herramienta que puede operar OBS con competencia. También produce una herramienta que es, de una manera específica y consecuente, sorda.

Este se suscribe al flujo de eventos, mantiene un registro acotado de lo que sucedió y responde preguntas al respecto.

Cero dependencias. Solo funciones integradas de Node. Windows, macOS y Linux.

La distinción que importa

Una solicitud responde exactamente a un tipo de pregunta: qué es verdad en este instante. Tú preguntas, OBS responde, tú decides. Lo que haya ocurrido entre una llamada y la siguiente se ha ido, y no tienes forma de saber que alguna vez estuvo allí.

Ahora, eso suena como una nota al pie arquitectónica. No lo es. Considera lo que te cuesta.

No hay ninguna solicitud en el protocolo obs-websocket que devuelva un nivel de audio. GetInputVolume te da la posición del fader. GetInputMute te da un booleano. Ninguno tiene nada que decir sobre si el sonido realmente sale de ese micrófono. Los niveles existen en un solo lugar, como InputVolumeMeters, que es un evento.

Así que la pregunta «¿está funcionando mi micrófono ahora mismo?» no puede ser respondida por un servidor construido puramente sobre solicitudes. No respondida mal. No respondida lentamente. No respondida en absoluto. Un servidor que expone 148 herramientas tiene exactamente el mismo punto ciego que uno que expone doce, porque la respuesta no está en la superficie de la que se extrae ninguna de ellas.

Este servidor retiene ese flujo:

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 llega aproximadamente cincuenta veces por segundo por fuente. Nadie quiere tres mil fotogramas brutos de vuelta de una llamada de herramienta. La pregunta que una persona realmente tiene es quién estaba alto, así que los medidores nunca entran en el búfer. Se reducen a un pico por fuente y se devuelven como respuesta.

Lo que esto te compra, concretamente

Un micrófono que está configurado correctamente y no produce nada. Fader en unidad, sin silenciar, y el dispositivo equivocado seleccionado o un cable silenciosamente muerto. Cada ajuste al que una solicitud puede llegar reporta salud perfecta. Esto no es hipotético; es por lo que el equipo del que proviene necesitaba un proceso separado de verificación de micrófono antes de que esto existiera.

Una cámara que sigue la voz. Necesitas saber cuál de dos micrófonos es más fuerte, continuamente, y necesitas compararlos entre sí en lugar de contra algún umbral fijo, porque dos micrófonos en una misma habitación tienen ganancias diferentes y cada uno oye a todos. No hay nada aquí que consultar. La información solo llega a medida que sucede.

Algo vivo y atascado, que es peor que algo muerto. Durante el desarrollo, este servidor inspeccionó cinco fuentes de medios y cada una de ellas reportó PLAYING. Una había avanzado cero milisegundos mientras las otras se movían alrededor de 2,540. Por estado eran indistinguibles. Solo el tiempo transcurrido separaba una alimentación funcional de un cadáver, y esa misma ceguera ya había ocultado diecisiete horas de música silenciosa detrás de un panel que mostraba verde.

Lo que sucedió hace dos minutos. Un sondeador puede describir el presente y nada más. Una vez que algo ha pasado, simplemente no está disponible, y te ves reducido a adivinar sobre el mismo incidente que intentas explicar.

Las descripciones son parte del producto

Una descripción de herramienta no es un lugar para repetir la lista de parámetros. El modelo ya puede leer el esquema. Es donde pones las cosas que de otro modo se aprenderían de la manera costosa:

• El desplazamiento de sincronización de audio de OBS se limita cerca de 960 ms. Los valores más grandes se aplican silenciosamente como nada, así que crees que compensaste un retraso de dos segundos y no compensaste nada.

• El índice 0 del elemento de escena es la parte inferior, y una fuente de lienzo completo situada sobre un fondo lo oculta por completo, sin que se genere ningún error en ningún lugar.

• Una fuente estacionada fuera del lienzo sigue siendo visible y sigue reproduciendo su audio. Ocultarla en cambio sí corta el audio, por lo que una superposición solo de audio se estaciona en lugar de ocultarse.

• RemoveInput reporta éxito y no elimina una fuente que algo todavía referencia.

• Los campos de límites son inertes a menos que boundsType se establezca primero.

• TriggerHotkeyByName toma un nombre simple, y libobs.mute se registra una vez por fuente de audio, veinticuatro veces en la máquina de referencia. Por lo tanto, los atajos de teclado no pueden dirigirse a una fuente específica, lo que sea que puedas suponer razonablemente.

Cada uno de esos costó algo a alguien. Están escritos porque un modelo que no los conoce actuará con confianza y se equivocará, lo cual es mucho peor que actuar tentativamente y tener razón.

La herramienta que hace posible una máquina nueva

obs_input_property_items enumera las opciones reales detrás de una propiedad de fuente: cada cámara web y cada dispositivo de audio, con los identificadores que OBS realmente espera.

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

No hay nada legible por humanos en eso para adivinar. Sin esta llamada, un asistente solo puede ajustar fuentes que una persona ya creó a mano. Con ella, puede construirlas desde cero.

Lo que está cubierto

67 herramientas en once módulos.

Instalación

Necesitas Node 22 o más reciente, para el WebSocket global, y OBS 31+ con Herramientas → Configuración del servidor WebSocket → Habilitar servidor WebSocket marcado.

Copia .mcp.example.json en la configuración de tu cliente MCP y apunta args a server.js. La contraseña se lee de OBS_WEBSOCKET_PASSWORD cuando está establecida, y de lo contrario de un secrets.json junto al servidor:

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

Ten en cuenta que una contraseña incorrecta no se presenta como una contraseña incorrecta. OBS acepta el socket y luego lo cierra con el código 4009, que la mayoría de los clientes reportan como un tiempo de espera, y pasarás la tarde investigando tu red. Este servidor lo nombra correctamente.

La máquina de referencia

Las cifras citadas a lo largo del texto, como los 43 tipos de filtro, los 411 atajos de teclado de los cuales solo 88 son distintos, el techo de 960 ms, las cinco salidas y dos búferes de repetición, se midieron en OBS 32.2.1 con obs-websocket 5.7.4 en Windows, mientras esa máquina transmitía en vivo a tres plataformas. Eso es a lo que la máquina de referencia se refiere dondequiera que aparezca. Tu instalación diferirá en algunos lugares, y cada uno de esos números se puede verificar con las herramientas aquí, que es el punto de declararlos en lugar de redondearlos en vaguedad.

Dos errores en la documentación publicada de obs-websocket salieron a la luz de esta manera y se evitan. GetSourceFilterKindList devuelve sourceFilterKinds, donde la documentación dice filterKinds. Y SetSourceFilterSettings.overlay por defecto es true, donde un resumen afirmaba false; pasar false llama a obs_source_reset_settings y destruye todos los demás valores ajustados en ese filtro, que es el tipo de error que cometes una vez.

Contribuciones

mcp/tools/index.js contiene el contrato. Un módulo exporta (obs) => [ { name, description, inputSchema, handler } ] y puede usar obs.request(type, data) y nada más.

La carga es deliberadamente a prueba de fallos. Un módulo que falta, que lanza una excepción mientras se construye, que devuelve una herramienta malformada o que duplica un nombre se registra y se omite, y el servidor aún se inicia con todo lo demás intacto. Tu módulo roto es tu problema y no debería convertirse en la transmisión muerta de otra persona.

Antes de abrir una solicitud de extracción:

npm run preflight

Rechaza credenciales, rutas absolutas, direcciones específicas de máquina e identificadores de dispositivos en cualquier parte del árbol, y verifica que cada módulo todavía se cargue.

Estado

0.1.0. Los nombres de las herramientas pueden cambiar antes de 1.0. Fija una versión exacta si estás escribiendo scripts contra ellos.

Licencia

MIT. Ver LICENSE.