obs-action-history

Ein MCP-Server für OBS Studio, der hören kann.

Es gibt bereits mehrere davon. Die meisten umhüllen die obs-websocket-Anfrageoberfläche Aufruf für Aufruf und hören dort auf. Das ist eine vernünftige Sache zu bauen, und es erzeugt ein Werkzeug, das OBS kompetent bedienen kann. Es erzeugt aber auch ein Werkzeug, das auf eine spezifische und folgenreiche Weise taub ist.

Dieser abonniert den Ereignisstrom, führt eine begrenzte Aufzeichnung dessen, was passiert ist, und beantwortet Fragen dazu.

Null Abhängigkeiten. Nur Node-Builtins. Windows, macOS und Linux.

Der Unterschied, der zählt

Eine Anfrage beantwortet genau eine Art von Frage: was in diesem Augenblick wahr ist. Du fragst, OBS antwortet, du entscheidest. Was zwischen einem Aufruf und dem nächsten geschah, ist verschwunden, und du hast keine Möglichkeit zu wissen, dass es je da war.

Das klingt nach einer architektonischen Fußnote. Das ist es nicht. Bedenke, was es dich kostet.

Es gibt keine Anfrage im obs-websocket-Protokoll, die einen Audio-Pegel zurückgibt. GetInputVolume liefert dir die Fader-Position. GetInputMute liefert dir einen booleschen Wert. Keines von beiden hat etwas darüber zu sagen, ob tatsächlich Ton aus diesem Mikrofon kommt. Pegel existieren nur an einer Stelle, als InputVolumeMeters, was ein Ereignis ist.

Die Frage „Funktioniert mein Mikrofon gerade jetzt?" kann also nicht von einem Server beantwortet werden, der rein auf Anfragen aufgebaut ist. Nicht schlecht beantwortet. Nicht langsam beantwortet. Überhaupt nicht beantwortet. Ein Server, der 148 Werkzeuge bereitstellt, hat genau denselben blinden Fleck wie einer, der zwölf bereitstellt, weil die Antwort nicht auf der Oberfläche liegt, aus der beide schöpfen.

Dieser Server hält diesen Stream fest:

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 kommt etwa fünfzig Mal pro Sekunde pro Quelle an. Niemand will dreitausend rohe Frames von einem Werkzeugaufruf zurück. Die Frage, die eine Person tatsächlich hat, ist wer laut war, daher gelangen Messwerte nie in den Puffer. Sie werden auf einen Spitzenwert pro Quelle reduziert und als Antwort zurückgegeben.

Was dir das konkret bringt

Ein Mikrofon, das korrekt konfiguriert ist und nichts produziert. Fader auf Eins, nicht stummgeschaltet, und das falsche Gerät ausgewählt oder ein Kabel leise tot. Jede Einstellung, die eine Anfrage erreichen kann, meldet perfekte Gesundheit. Das ist nicht hypothetisch; es ist der Grund, warum das Setup, aus dem das stammt, vorher einen separaten Mikrofonprüfprozess benötigte.

Eine Kamera, die der Stimme folgt. Du musst wissen, welches von zwei Mikrofonen lauter ist, kontinuierlich, und du musst sie gegeneinander vergleichen, nicht gegen einen festen Schwellenwert, weil zwei Mikrofone in einem Raum unterschiedliche Verstärkungen haben und jedes von ihnen alle hört. Es gibt hier nichts abzufragen. Die Information kommt nur an, wenn sie passiert.

Etwas Lebendiges und Verklemmtes, das schlimmer ist als etwas Totes. Während der Entwicklung untersuchte dieser Server fünf Medienquellen, und jede von ihnen meldete PLAYING. Eine war null Millisekunden fortgeschritten, während die anderen sich um etwa 2.540 bewegten. Vom Zustand her waren sie nicht zu unterscheiden. Nur die verstrichene Zeit trennte einen funktionierenden Feed von einer Leiche, und genau diese Blindheit hatte bereits siebzehn Stunden stiller Musik hinter einem grün anzeigenden Dashboard verborgen.

Was vor zwei Minuten passiert ist. Ein Poller kann die Gegenwart beschreiben und sonst nichts. Sobald etwas vorbei ist, ist es einfach nicht verfügbar, und du bist darauf reduziert, über genau den Vorfall zu raten, den du zu erklären versuchst.

Die Beschreibungen sind Teil des Produkts

Eine Werkzeugbeschreibung ist nicht der Ort, um die Parameterliste zu wiederholen. Das Modell kann das Schema bereits lesen. Es ist der Ort, an dem du die Dinge unterbringst, die sonst auf teure Weise gelernt werden:

• OBS-Audio-Sync-Offset kappt bei etwa 960 ms. Größere Werte werden stillschweigend als nichts angewendet, sodass du glaubst, eine Verzögerung von zwei Sekunden kompensiert zu haben, und du hast nichts davon kompensiert.

• Szenenelement Index 0 ist der Boden, und eine Vollbild-Quelle, die über einem Hintergrund sitzt, verdeckt ihn völlig, ohne dass irgendwo ein Fehler ausgelöst wird.

• Eine Quelle, die außerhalb der Leinwand geparkt ist, ist weiterhin sichtbar und spielt weiterhin ihr Audio. Sie stattdessen zu verstecken, schneidet das Audio ab, weshalb ein Nur-Audio-Overlay geparkt statt versteckt wird.

• RemoveInput meldet Erfolg und löscht keine Quelle, auf die noch etwas verweist.

• Bounds-Felder sind träge, es sei denn, boundsType wird zuerst gesetzt.

• TriggerHotkeyByName nimmt einen nackten Namen, und libobs.mute ist einmal pro Audioquelle registriert, vierundzwanzig Mal auf der Referenzmaschine. Hotkeys können daher keine bestimmte Quelle ansprechen, was auch immer du vernünftigerweise annehmen magst.

Jeder dieser Punkte hat jemanden etwas gekostet. Sie sind niedergeschrieben, weil ein Modell, das sie nicht kennt, selbstbewusst handeln und falsch liegen wird, was erheblich schlimmer ist, als zögerlich zu handeln und richtig zu liegen.

Das Werkzeug, das eine frische Maschine möglich macht

obs_input_property_items zählt die tatsächlichen Auswahlmöglichkeiten hinter einer Quelleneigenschaft auf: jede Webcam und jedes Audiogerät, mit den Kennungen, die OBS tatsächlich erwartet.

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

Es gibt darin nichts Menschenlesbares, das man erraten könnte. Ohne diesen Aufruf kann ein Assistent nur Quellen anpassen, die eine Person bereits von Hand erstellt hat. Mit ihm kann er sie aus dem Nichts aufbauen.

Was abgedeckt ist

67 Werkzeuge über elf Module.

Installation

Du benötigst Node 22 oder neuer für das globale WebSocket und OBS 31+ mit aktiviertem Tools → WebSocket Server Settings → Enable WebSocket server.

Kopiere .mcp.example.json in die Konfiguration deines MCP-Clients und richte args auf server.js. Das Passwort wird aus OBS_WEBSOCKET_PASSWORD gelesen, wenn es gesetzt ist, andernfalls aus einer secrets.json neben dem Server:

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

Beachte, dass ein falsches Passwort sich nicht als falsches Passwort darstellt. OBS akzeptiert den Socket und schließt ihn dann mit Code 4009, was die meisten Clients als Timeout melden, und du wirst deinen Nachmittag damit verbringen, dein Netzwerk zu untersuchen. Dieser Server benennt es korrekt.

Die Referenzmaschine

Die durchgehend zitierten Zahlen, wie die 43 Filterarten, die 411 Hotkeys, von denen nur 88 eindeutig sind, die 960-ms-Obergrenze, die fünf Ausgänge und zwei Replay-Puffer, wurden auf OBS 32.2.1 mit obs-websocket 5.7.4 unter Windows gemessen, während diese Maschine live auf drei Plattformen sendete. Das ist es, was die Referenzmaschine meint, wo immer sie erscheint. Deine Installation wird sich an manchen Stellen unterscheiden, und jede dieser Zahlen ist mit den hier verfügbaren Werkzeugen überprüfbar, was der Sinn davon ist, sie zu nennen, anstatt sie in Unschärfe zu runden.

Zwei Fehler in der veröffentlichten obs-websocket-Dokumentation traten auf diese Weise zutage und werden umgangen. GetSourceFilterKindList gibt sourceFilterKinds zurück, während die Dokumentation filterKinds sagt. Und SetSourceFilterSettings.overlay standardmäßig auf true, wo eine Zusammenfassung false behauptete; false zu übergeben ruft obs_source_reset_settings auf und zerstört jeden anderen abgestimmten Wert auf diesem Filter, was die Art von Fehler ist, den man einmal macht.

Mitwirken

mcp/tools/index.js hält den Vertrag. Ein Modul exportiert (obs) => [ { name, description, inputSchema, handler } ] und darf obs.request(type, data) und sonst nichts verwenden.

Das Laden ist bewusst ausfallsicher. Ein Modul, das fehlt, das beim Erstellen eine Ausnahme auslöst, das ein fehlerhaftes Werkzeug zurückgibt oder einen Namen dupliziert, wird protokolliert und übersprungen, und der Server startet trotzdem mit allem anderen intakt. Dein defektes Modul ist dein Problem und sollte nicht zur toten Sendung eines anderen werden.

Bevor du einen Pull-Request eröffnest:

npm run preflight

Er lehnt Anmeldeinformationen, absolute Pfade, maschinenspezifische Adressen und Gerätekennungen überall im Baum ab und überprüft, dass jedes Modul noch lädt.

Status

0.1.0. Werkzeugnamen können sich vor 1.0 noch ändern. Pinne eine exakte Version, wenn du Skripte dagegen schreibst.

Lizenz

MIT. Siehe LICENSE.