obs-action-history

聞くことができるOBS Studio用MCPサーバー

似たようなものはすでにいくつかあります。それらのほとんどはobs-websocketのリクエストサーフェスを一度に1コールずつラップするだけで、そこで止まっています。それは妥当な作り方であり、OBSをきちんと操作できるツールが出来上がります。しかし同時に、特定の、そして重大な意味で「耳の聞こえない」ツールにもなります。

これはイベントストリームを購読し、発生したことの記録を上限付きで保持し、それについての質問に答えるものです。

依存関係ゼロ。Node組み込みのみ。Windows、macOS、Linuxに対応。

重要な違い

リクエストは、ちょうど1種類の質問にしか答えられません。すなわち「この瞬間に何が真実か」です。あなたが尋ね、OBSが答え、あなたが判断する。ある呼び出しと次の呼び出しの間に何が起ころうと、それは消え去り、それがそこにあったことを知るすべはありません。

さて、これは設計上の些細な注記のように聞こえるかもしれません。しかし、そうではありません。それがどれほどの代償を払うことになるかを考えてみてください。

obs-websocketプロトコルには、オーディオレベルを返すリクエストは存在しません。 GetInputVolumeはフェーダー位置を返します。GetInputMuteは真偽値を返します。どちらも、そのマイクから実際に音が出ているかどうかについては何も教えてくれません。レベルが存在するのは、InputVolumeMetersというイベントとしての1箇所だけです。

つまり「私のマイクは今ちゃんと動いているか」という質問には、純粋にリクエストだけで構築されたサーバーは答えられないのです。下手に答えるのでも、遅く答えるのでもありません。まったく答えられないのです。148個のツールを公開するサーバーも、12個のツールを公開するサーバーとまったく同じ盲点を持ちます。なぜなら、その答えはどちらのサーバーが参照するサーフェスにも存在しないからです。

このサーバーは、そのストリームを保持します：

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はソースごとに毎秒約50回届きます。ツール呼び出しで生のフレームを3000個返してほしい人はいません。人が実際に知りたいのは誰がうるさかったかであり、メーターはバッファに一切入りません。それらはソースごとのピークに集約され、回答として返されます。

これで具体的に何ができるようになるか

正しく設定されているのに何も出力しないマイク。 フェーダーはユニティ、ミュートなし、なのに間違ったデバイスが選択されていたり、ケーブルが静かに断線していたりするケース。リクエストで到達できるすべての設定は完璧な健康状態を報告します。これは仮定の話ではありません。これが生まれる前、この元となった装置では、マイクチェック用の別プロセスが必要だったのは、まさにこのためです。

声に追従するカメラ。 2つのマイクのどちらが大きいかを継続的に知る必要があり、固定のしきい値ではなく、互いを比較する必要があります。なぜなら、同じ部屋の2つのマイクはゲインが異なり、それぞれが全員の声を拾うからです。ここにはポーリングするものは何もありません。情報は発生した瞬間にしか得られないのです。

死んでいるより厄介な、生きていて詰まっている状態。 開発中、このサーバーは5つのメディアソースを調査しましたが、そのすべてがPLAYINGを報告していました。1つは0ミリ秒しか進んでいないのに、他は約2,540ミリ秒進んでいました。状態では区別がつきません。正常に動いているフィードと死体を分けたのは経過時間だけであり、そのまさに盲目さが、17時間の無音の音楽を、緑色を示すダッシュボードの背後に隠していたのです。

2分前に何が起きたか。 ポーラーは現在を説明できても、それ以外は何もできません。何かが過ぎ去ってしまうと、それは単に利用できなくなり、説明しようとしているまさにその出来事について推測するしかなくなります。

説明文も製品の一部

ツールの説明文は、パラメータリストを言い換えるための場所ではありません。モデルはすでにスキーマを読むことができます。それは、そうでなければ高い代償を払って学ぶことになる事柄を書いておく場所です。

• OBSのオーディオ同期オフセットは約960msで頭打ちになります。それより大きい値は黙って何も適用されないため、2秒の遅延を補正したつもりが、実際には何も補正されていなかった、ということになります。

• シーンアイテムのインデックス0は最背面であり、背景の上に置かれた全画面ソースは、どこにもエラーを出すことなく、それを完全に隠してしまいます。

• キャンバス外に配置されたソースは、表示されたまま、オーディオも再生され続けます。代わりに非表示にするとオーディオも切れるため、音声専用のオーバーレイは非表示ではなく、キャンバス外に配置されているのです。

• RemoveInputは成功を報告しますが、まだ何かが参照しているソースは削除しません。

• 境界フィールドは、boundsTypeが先に設定されない限り機能しません。

• TriggerHotkeyByNameは裸の名前を取り、libobs.muteはオーディオソースごとに1回、リファレンスマシンでは24回登録されます。したがって、ホットキーは、もっともらしく推測しても、特定のソースを指定することはできません。

これらのそれぞれは、誰かの犠牲の上に成り立っています。これらを知らないモデルは、自信満々に間違った行動をとるでしょう。それは、ためらいながらも正しい行動をとるよりはるかに悪いことです。だからこそ、書き留めてあるのです。

新しいマシンを可能にするツール

obs_input_property_itemsは、ソースプロパティの背後にある実際の選択肢（すべてのウェブカメラとオーディオデバイス）を、OBSが実際に期待する識別子とともに列挙します。

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

推測するような人間が読める情報はそこにはありません。この呼び出しがなければ、アシスタントは人間が手動で作成したソースを調整することしかできません。これがあれば、ゼロからソースを構築できます。

対象範囲

11のモジュール、67のツール。

インストール

Node 22以降（グローバルWebSocket用）と、ツール → WebSocketサーバー設定 → WebSocketサーバーを有効にするにチェックが入ったOBS 31以降が必要です。

.mcp.example.jsonをMCPクライアントの設定にコピーし、argsをserver.jsに向けます。パスワードは、OBS_WEBSOCKET_PASSWORDが設定されている場合はそこから、そうでない場合はサーバーと同じ場所にあるsecrets.jsonから読み取られます：

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

間違ったパスワードは、間違ったパスワードとしては表示されないことに注意してください。OBSはソケットを受け入れ、その後コード4009で閉じます。ほとんどのクライアントはこれをタイムアウトとして報告するため、ネットワークの調査に午後を費やすことになります。このサーバーはそれを正しく表示します。

リファレンスマシン

随所で引用されている数値（43種類のフィルター、そのうち88個だけが一意である411個のホットキー、960msの上限、5つの出力と2つのリプレイバッファ）は、Windows上のOBS 32.2.1とobs-websocket 5.7.4で、そのマシンが3つのプラットフォームにライブ配信中に測定されたものです。これが、リファレンスマシンという言葉が登場するたびに意味するものです。お使いのインストール環境は場所によって異なります。そして、それらの数値はすべて、ここにあるツールで確認できます。漠然と丸めるのではなく、数値を明記したのは、まさにそのためです。

公開されているobs-websocketドキュメントの2つのエラーがこの方法で明らかになり、回避されています。GetSourceFilterKindListは、ドキュメントではfilterKindsとされているところを、sourceFilterKindsを返します。また、SetSourceFilterSettings.overlayは、要約ではfalseと主張されていましたが、デフォルトでtrueです。falseを渡すとobs_source_reset_settingsが呼び出され、そのフィルタの他のすべての調整済みの値が破棄されます。これは一度は経験するタイプのミスです。

コントリビューション

mcp/tools/index.jsが契約を保持しています。モジュールは(obs) => [ { name, description, inputSchema, handler } ]をエクスポートし、obs.request(type, data)のみを使用できます。

ロードは意図的にフェイルセーフになっています。存在しないモジュール、ビルド中にスローするモジュール、不正なツールを返すモジュール、名前が重複するモジュールはログに記録されてスキップされ、サーバーは他のすべてをそのままに起動します。壊れたモジュールはあなた自身の問題であり、他の誰かの放送事故の原因になるべきではありません。

プルリクエストを送信する前に：

npm run preflight

資格情報、絶対パス、マシン固有のアドレス、デバイス識別子がツリー内のどこにもないことを拒否し、すべてのモジュールがまだロードされることを検証します。

ステータス

0.1.0。ツールの名前は1.0より前に変更される可能性があります。スクリプトで使用する場合は、正確なバージョンを固定してください。

ライセンス

MIT。 LICENSE を参照してください。