obsbotd

OBSBOT Tinyシリーズカメラ向けのLinux MCPデーモン。1つのデーモンがカメラを所有し、Claude Code、LibreChat、カスタムフレームワーク、またはJSONをPOSTできる任意のエージェントが、streamable-httpを介して接続します。

MCP clients (any framework, or bare curl)
        │  streamable-http  http://127.0.0.1:8626/mcp
        ▼
     obsbotd  ──►  V4L2/UVC ioctls (ctypes)   gimbal, zoom, focus, status
              ──►  vendor XU protocol         wake/sleep, AI tracking, exposure
              ──►  ffmpeg                     snapshots (validated), clips, preview

なぜこれが存在するのか

上流のobsbot-mcp npmパッケージは、ベンダープロトコルのリバースエンジニアリングと光学系のキャリブレーションという困難な部分を担当していましたが、そのアーキテクチャ（エージェントセッションごとのstdio MCPサーバー、プリビルドされたネイティブヘルパーバイナリ、セッション間のシングルオーナーIPC選挙）は、マルチエージェントLinuxマシン上で慢性的な運用上の問題を引き起こしました：数週間前のコードを実行する古いオーナープロセス、検証されていない切り詰められたフレーム、そしてバグが潜むクローズドなバイナリ。

obsbotdはプロトコル知識を保持しつつ、アーキテクチャを破棄します：

• 1つのデーモン、多数のクライアント。 選挙も、セッションごとのプロセスも、古いオーナーもありません。systemdユーザーサービスとして実行されます。

• ネイティブバイナリは不要。 V4L2/UVCレイヤーは約200行のctypesです。ioctl番号は構造体サイズから計算されるため、レイアウトの誤りは大きなエラーとなります。

• ホットプラグは無料。 呼び出し間でデバイスハンドルは保持されません。すべてのツール呼び出しは/dev/video*を再発見します（サブミリ秒）。カメラを抜くと、通常の結果として{"ok": false, "camera_present": false}が返されます。再挿入後の次の呼び出しはそのまま動作します。

• フレームは検証されます。 カメラは散発的に、特にウェイク後最悪の場合に、切り詰められたMJPEGフレームを出力します。すべてのスナップショットは、完全なSOI..EOIがチェックされたストリームコピーされた生フレームであり、最大4回再試行され、その後オプションでダウンスケールされます（デフォルト640px — スナップショットピクセルはLLMトークンです）。

• 正直なエラー。 すべての失敗は、エージェントが対処できる構造化された{ok: false, error}です — 不透明なツール例外ではありません。拒否メッセージは代わりに何をすべきかを示します。

• アトミックなパン+チルト。 両軸を1つのVIDIOC_S_EXT_CTRLSで — uvcvideoのコントロールごとのリードモディファイライトは、そうでなければ移動の半分をキャンセルします。

• 測定された光学系。 obsbot_aim_at_pixel / obsbot_zoom_to_fitは、内部パラメータが解かれたFOVモデル（67°ワイドHFOV、0.957垂直補正、倍率 = 3・比率 − 2）と、上流のキャリブレーション作業から継承された合成回転照準を使用したビジュアルサーボを行います。

ハードウェアサポート

Linux（カーネル uvcvideo）上のOBSBOT Tiny 2 Liteに対して開発およびハードウェア検証済み。Tiny 2はベンダープロトコルを共有しており、変更なしで動作するはずです。他のOBSBOTモデルは未テストです。ホストあたり1台のカメラ。

既知のカーネル制限：uvcvideoはCT_PANTILT_ABSOLUTEをキャッシュするため、ジンバル読み戻しは最後に指示された姿勢であり、ライブではありません — ツールはそれに応じてラベル付けされており、意図されたワークフローは視覚的に確認します。

インストール

Python ≥ 3.12、ffmpeg（およびプレビューウィンドウ用のffplay）、カメラの/dev/video*ノード（videoグループ）への読み取り/書き込みアクセスが必要です。

git clone https://github.com/LumenPrima/obsbotd ~/obsbotd
cd ~/obsbotd
uv venv && uv pip install -e .        # or: python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/python -m obsbotd.server    # listens on 127.0.0.1:8626

サービスとして：

cp systemd/obsbotd.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now obsbotd
loginctl enable-linger $USER          # optional: run without an active login

OBSBOTD_HOST / OBSBOTD_PORTでバインドアドレスを上書きします。デフォルトはlocalhostのみで、認証はありません — ポートに到達できる人がカメラを操作して写真を撮れることを理解していない限り、到達可能なインターフェースにバインドしないでください。

エージェントを接続する

MCPネイティブ設定（Claude Code、ほとんどのフレームワーク）：

{ "mcpServers": { "obsbot": { "type": "http", "url": "http://127.0.0.1:8626/mcp" } } }

MCPライブラリがない場合？サーバーはベアJSON-RPC POSTにプレーンJSONで応答します — 単純なエージェントでもcurlで操作できます。**docs/AGENT-GUIDE.md**に完全な統合ガイド、18ツールリファレンス、およびエンゲージメントルール（スリープなし、モーションを視覚的に確認、拒否を指示として扱う）があります。

ツール（18）

obsbot_snapshot · obsbot_status · obsbot_wake · obsbot_sleep · obsbot_gimbal_move · obsbot_gimbal_recenter · obsbot_gimbal_position · obsbot_zoom · obsbot_aim_at_pixel · obsbot_zoom_to_fit · obsbot_ai_track · obsbot_ai_track_speed · obsbot_focus · obsbot_exposure · obsbot_image_adjust · obsbot_image_mode · obsbot_record_clip · obsbot_preview

プロトコルドキュメント

docs/spec-*.mdは、ベンダーワイヤープロトコル（60バイトV3フレーム、CRC-16/USB、オペコードテーブル、60バイトステータスブロック、セレクターマップ）と測定された光学系の完全な文書仕様です — 再実装のリファレンスとして上流のソースから抽出され、これらのカメラを操作する人にとってそれ自体で有用です。ワイヤーレイヤーは、上流の正確なフレームバイトに対してゴールデンテストされています（tests/）。

テスト

tests/はハードウェア不要：.venv/bin/python -m pytest tests/ -q

クレジット

ベンダープロトコルのリバースエンジニアリング、ハードウェアの癖のカタログ、および光学キャリブレーションはすべてobsbot-mcp（MIT、© 2026 Michael Jordan）から提供されています。obsbotdは、その知識を基にしたサービングアーキテクチャの独立したLinuxネイティブ再実装です。

ライセンス

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