{
  "markdown": "# obsbot-mcp\n\nA cross-platform [Model Context Protocol](https://modelcontextprotocol.io) server that controls an\n**OBSBOT Tiny 2** camera over its standard UVC/USB interface — pan/tilt/roll the gimbal, zoom, AI\nsubject tracking, focus/exposure/white-balance/image controls, HDR and field-of-view, plus snapshot,\npreview, and recording — without any vendor SDK.\n\n## Install\n\n```bash\nnpm install obsbot-mcp\n```\n\n## MCP client configuration\n\nAdd a stdio server entry pointing at the installed binary (or directly at `dist/index.js`):\n\n```json\n{\n  \"mcpServers\": {\n    \"obsbot\": {\n      \"command\": \"obsbot-mcp\"\n    }\n  }\n}\n```\n\nIf you're running from a local checkout instead of an npm install, point `command`/`args` at\n`node` and the built entry point instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"obsbot\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/obsbot-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Debug / diagnostics tools\n\nBy default the server advertises only the normal control surface. Pass `--debug` to additionally\nexpose the diagnostics surface — the `obsbot_debug_probe` tool (raw XU byte get/set/query) and the\n`raw` 60-byte status block on `obsbot_status`:\n\n```json\n{\n  \"mcpServers\": {\n    \"obsbot\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/obsbot-mcp/dist/index.js\", \"--debug\"]\n    }\n  }\n}\n```\n\nWith the installed binary, use `\"command\": \"obsbot-mcp\"` and `\"args\": [\"--debug\"]`.\n\n## Tools\n\n35 tools on Windows and macOS, 34 on Linux (`obsbot_gimbal_move_speed` is unavailable there — see\n[limitations](#linux-gimbal-position-feedback-is-not-live)). `--debug` adds `obsbot_debug_probe` for\none more. All names below are current as of v0.4.0 — **every tool was renamed in this\nrelease and there is no backward-compatible alias**; see [CHANGELOG.md](./CHANGELOG.md) for the\nfull old→new mapping if you're updating a caller.\n\n### The `camera` selector\n\nEvery camera-addressing tool accepts an optional `camera` parameter: the target camera's serial\nnumber. Omit it with a single camera attached and nothing changes — this matches the server's\npre-v0.4.0, single-camera behaviour exactly. With more than one camera attached, a call that omits\n`camera` fails with an error naming every attached serial, so you always know what to pass next.\n\n**Exempt** (no `camera` parameter, ever): `obsbot_devices` (enumerates the whole fleet),\n`obsbot_capture_stop` / `obsbot_capture_list` (address a `sessionId`, not a device), and\n`obsbot_debug_probe` (operates on the current diagnostics transport). Two more tools honor it only\npartially — see **Capture** below.\n\nMulti-camera support is new in v0.4.0. It's exercised by the unit test suite against fakes; running\ntwo physical Tiny 2s at once has not yet been hardware-verified (see\n[Known limitations](#known-limitations)).\n\n`obsbot_devices` is the way to discover the serials you pass as `camera`: it reports each attached\ncamera's `serial` (where obtainable — reading it requires briefly opening the camera), `name`, and\n`status` (`available` | `bound` | `busy`). A camera another process already holds comes back `busy`\nwith no serial, since it can't be opened to read one.\n\n### Device & power\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_devices` | — | List attached OBSBOT cameras with each one's serial (where obtainable), name, and status (`available`/`bound`/`busy`). A `busy` camera is held by another process. |\n| `obsbot_wake` | `camera`? | Wake the camera/gimbal (sends `\"run\"`). **Moves the camera:** un-stows the gimbal back to level (pitch ~0). Most control commands also wake it implicitly. |\n| `obsbot_sleep` | `camera`? | Sleep the camera/gimbal (sends `\"sleep\"`). **Moves the camera:** stows the gimbal face-down at roughly pitch `84`, so `obsbot_gimbal_position` reads ~84 rather than the pose you left. |\n| `obsbot_status` | `camera`? | Read the live status block: `{ awake, hdr, faceAe, aiMode, trackSpeed, fovMode, zoomPercent, focusMode, focusPosition }` (`faceAe` = auto-exposure metering for a detected face; `fovMode` = `wide`\\|`medium`\\|`narrow`\\|`custom`\\|`unknown`, where `custom` means a continuous zoom overrode the discrete modes; `zoomPercent` = zoom position, `0`-`100`; `focusMode` = `auto`\\|`manual`\\|`unknown`). **`focusPosition` appears only in manual mode**, on the same `0`-`100` scale `obsbot_focus_manual` takes — under autofocus the camera echoes the last written value rather than exposing the motor, so a number there would read as a live focus distance while being stale. Focus is a standard UVC control, not part of the status block, so it costs one extra read; a device that can't answer reports `focusMode: \"unknown\"` rather than failing the whole call. Under `--debug`, also returns the raw 60-byte block as hex. |\n\n### Gimbal (PTZ)\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_gimbal_move` | `yaw`, `pitch`, `roll` (degrees, `roll` defaults `0`), `camera`? | Move the gimbal to an absolute angle. Positive yaw pans to the camera's left, positive pitch tilts down. Yaw clamped to `[-150, 150]`, pitch to `[-90, 90]`. Absolute 1:1 degrees, hardware-verified. |\n| `obsbot_gimbal_move_speed` | `yaw`, `pitch`, `roll` (deg/s, clamped to `±150`, `roll` defaults `0`), `autoStopMs` (default `800`), `camera`? | Drive the gimbal at a speed, then auto-stop after `autoStopMs` so it can't run away. Same yaw/pitch sign convention as `gimbal_move`. Returns the speeds actually used. Past its limit the firmware ignores the command outright rather than saturating — 180 deg/s and above move the gimbal exactly 0° — so requests are clamped into the hardware-verified band. **Not available on Linux** — see [limitations](#linux-gimbal-position-feedback-is-not-live). |\n| `obsbot_gimbal_recenter` | `camera`? | Recenter the gimbal — drives it to yaw `0` / pitch `0`. Returns as soon as the command is sent, so poll `obsbot_gimbal_position` if you need to know it arrived. |\n| `obsbot_gimbal_position` | `camera`? | Read the gimbal's current absolute `{ yaw, pitch }` in degrees via standard UVC Pan/Tilt. Valid during a move as well as after one. On Linux this is the last-*commanded* value, not a live in-flight reading — see [limitations](#linux-gimbal-position-feedback-is-not-live). |\n| `obsbot_aim_at_pixel` | `x`, `y`, `frameWidth`, `frameHeight`, `source` (default `\"device\"`), `camera`? | Point the camera at a pixel from a frame you just captured. Reads the camera's magnification from its own reported state — a discrete FOV mode or a continuous zoom alike — so it needs no FOV or zoom argument and works at any zoom. Refuses while AI tracking is active, when the FOV mode can't be decoded, or when a corrupt zoom reading would resolve to an implausible magnification, and refuses if the camera had to be woken (waking moves the gimbal, invalidating the frame you measured) or if the zoom is still ramping (the frame was captured at a magnification the camera has already left, so wait for the zoom and take a fresh snapshot). `source` **declares** which feed the frame came from (default `device`) — it cannot be inferred from the pixels. A `virtual`/`ndi` frame is accepted, not refused, but only aims correctly if that feed is an unmodified pass-through of the camera; a compositor's rescale or letterbox is invisible in the picture and silently wrong here, so a non-`device` declaration returns a `note` stating that assumption. It reads the live pose to compute the aim, so on Linux it is affected the same way `obsbot_gimbal_position` is — see [limitations](#linux-gimbal-position-feedback-is-not-live). Returns `clamped:true` if the target was outside the gimbal's range, in which case the camera still moves — to the nearest reachable pose. Refuses (`ok:false`) instead of moving when the pixel lies past vertical from the current pose, since the only rotation that reaches it would swing the camera toward the opposite side of the room; tilt toward the pixel first, then re-aim. |\n| `obsbot_zoom_to_fit` | `x`, `y`, `width`, `height`, `frameWidth`, `frameHeight`, `margin` (default `0.1`), `source` (default `\"device\"`), `camera`? | Frame a region of a frame you just captured: centre the gimbal on it and zoom so the region fills the frame. Same refusal conditions as `obsbot_aim_at_pixel` (AI tracking, undecodable FOV/zoom, a woken camera, a zoom still ramping, an over-the-top target, a non-16:9 frame), and the same `source` declaration, plus a refusal if the region isn't within the frame (edges included) or has non-positive size. `margin` backs the zoom off by that fraction so the region isn't framed edge-to-edge; the *tighter* of the region's two axes sets the zoom, so the whole region stays visible rather than being cropped on one side. Moves the gimbal **before** zooming — zoom is centre-preserving but not target-preserving, so zooming first can push the region out of frame. Zoom ramps rather than jumping, so the tool polls for up to 3s and returns `settled:false` (not an error) if the zoom hadn't arrived in time — check it before trusting a follow-up snapshot. |\n\n#### Aiming at what you can see\n\n`obsbot_capture_snapshot` returns the frame as an image plus its `width`/`height`, so a model can\nlocate something in the picture and then point the camera at it:\n\n1. `obsbot_capture_snapshot` — look at the frame\n2. `obsbot_aim_at_pixel` — pass the target's pixel and that frame's dimensions\n3. `obsbot_capture_snapshot` again — confirm it landed, and repeat if needed\n\nPass the `frameWidth`/`frameHeight` from the same snapshot the pixel came from. Mixing a pixel from\none frame with dimensions from another aims at the wrong place, and nothing can detect it.\n\n**The snapshot must be `source: \"device\"`.** `obsbot_capture_snapshot` can also read from\n`source: \"virtual\"` or `\"ndi\"`, which come from OBSBOT Center's own output rather than the camera's\nraw stream. Those are framed and cropped by OBSBOT Center, not by this camera's optics, so the\nmeasured field-of-view constants this tool relies on don't describe them — aiming from a virtual or\nNDI frame lands in the wrong place with no way to detect it. Only use a `device`-source snapshot's\npixel and dimensions here.\n\nThe tool reads the camera's magnification itself — a discrete FOV mode or a continuous zoom alike\n(`m = 3*ratio-2`, measured on hardware to better than 0.05%) — so there is no FOV or zoom argument to\nget wrong, and it works at any zoom. It refuses rather than guessing when AI tracking is on (tracking\ndrives the gimbal and would fight the aim), when the FOV mode can't be decoded, when a corrupt zoom\nreading would resolve to an implausible magnification, or when the camera had to\nbe woken from sleep (waking moves the gimbal, so the frame you measured no longer matches where the\ncamera is pointing — take a fresh snapshot and retry).\n\n#### Framing what you can see\n\n`obsbot_zoom_to_fit` extends the same idea from a point to a region: instead of just centring on a\npixel, it also zooms so that region fills the frame.\n\n1. `obsbot_capture_snapshot` — look at the frame\n2. Pick a bounding box around whatever should fill the frame (a face, a whiteboard, ...)\n3. `obsbot_zoom_to_fit` — pass the box (`x`, `y`, `width`, `height`) and that frame's dimensions\n4. `obsbot_capture_snapshot` again — confirm the framing, and repeat if needed\n\nIt shares `obsbot_aim_at_pixel`'s refusals (AI tracking, undecodable FOV/zoom, a woken camera, a zoom still ramping, a\nnon-16:9 frame), and adds one of its own: the region must lie within the frame — edges included, so a\nregion that already IS the full frame is valid — with a positive width and height, or the call refuses\nrather than guess what a negative width or an off-frame box was supposed to mean.\n\n`margin` (default `0.1`, i.e. 10%) backs the requested zoom off by that fraction so the region isn't\nframed exactly edge-to-edge — some breathing room around it survives small aim/zoom error. The\nregion's two axes rarely need the same zoom to fill the frame; the tool always picks the *smaller* of\nthe two required magnifications, because zooming to the larger one would fill one axis by cropping the\nother. The result is clamped to the camera's `[1x, 4x]` magnification range (reported via `clamped`) —\na region demanding more zoom than the camera has still gets the closest fit available, rather than\nbeing refused outright.\n\nThe gimbal moves before the zoom is commanded. Zoom re-centres what's already in frame but does not\nkeep a specific pixel under the crosshair as it changes — zooming first can push the region's centre\nout of frame entirely, which would make the subsequent move aim at a pixel that no longer means what\nit did when the caller measured it.\n\nZoom is not instantaneous: on this hardware it ramps toward the commanded value rather than jumping to\nit, so a status read taken immediately after commanding it can catch it mid-transit (observed:\ncommanding ratio 1.5 read back partway there before settling). `obsbot_zoom_to_fit` polls for up to 3\nseconds waiting for the zoom to arrive and returns `settled:false` — not an error — if it didn't. A\nframe captured while the zoom is still moving is at an unknown magnification, so check `settled`\nbefore trusting a follow-up snapshot; a `false` just means the camera was moving slower than expected,\nnot that anything failed.\n\n### Gimbal presets\n\nThree on-device preset slots (1–3). Slots are **create-once**: `obsbot_preset_save` requires an\nempty slot (delete first to reuse one); every other preset tool requires the slot to already be\noccupied. Each tool re-reads the slot list after writing and returns a structured `{ ok:false }`\nfailure if the device didn't land the change.\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_preset_list` | `camera`? | Read the three preset slots: occupied/empty, name, and pose in degrees. |\n| `obsbot_preset_save` | `slot` (`1`\\|`2`\\|`3`), `camera`? | Save the gimbal's current live pose into an **empty** slot. |\n| `obsbot_preset_recall` | `slot` (`1`\\|`2`\\|`3`), `camera`? | Recall an **occupied** slot, driving the gimbal to its saved pose. |\n| `obsbot_preset_update` | `slot` (`1`\\|`2`\\|`3`), `camera`? | Overwrite an **occupied** slot with the gimbal's current live pose. |\n| `obsbot_preset_rename` | `slot` (`1`\\|`2`\\|`3`), `name`, `camera`? | Rename an **occupied** slot (names over 40 bytes are truncated). |\n| `obsbot_preset_delete` | `slot` (`1`\\|`2`\\|`3`), `camera`? | Delete an **occupied** slot, freeing it for `obsbot_preset_save`. |\n\n### Zoom\n\nTwo tools, not one — they ride different transports (standard UVC vs. the vendor command frame)\nand produce different physical zoom at the same commanded `ratio`, so merging them would silently\nchange what `ratio` means. Pick by which behaviour you need.\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_zoom_uvc` | `ratio` (`1.0`–`2.0`), `camera`? | Standard UVC zoom: set an absolute zoom ratio, clamped to `[1.0, 2.0]`. Snaps to the requested target exactly. Waits for the zoom to arrive and returns `settled` — the ramp is not instant (a full `1.0`→`2.0` sweep takes about 2.4s), and `obsbot_aim_at_pixel` / `obsbot_zoom_to_fit` refuse while it is in flight, so returning early would only move the failure downstream. `settled:false` means it hadn't arrived within the timeout; the command was still sent. |\n| `obsbot_zoom_vendor` | `ratio` (`1.0`–`2.0`), `speed` (default `0`), `camera`? | Vendor zoom path with adjustable speed: zoom to a ratio at a chosen speed (`0` = device default, `1`–`10` slow→fast, `255` = maximum). **Its ratio scale differs from `obsbot_zoom_uvc`'s** and may not land exactly on the requested target — see [Known limitations](#known-limitations). |\n\n### AI tracking\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_ai_track` | `enabled` (bool), `mode` (default `\"normal\"`), `camera`? | Enable/disable AI tracking and choose the mode: a human framing (`normal \\| upper-body \\| close-up \\| headless \\| lower-body`) or a scene mode (`group \\| whiteboard \\| desk \\| hand`). Polls status and returns `{ verified, matched }` (`matched:false` = no subject tracked yet). |\n| `obsbot_ai_track_speed` | `speed`: `\"standard\" \\| \"sport\"`, `camera`? | Set the tracking-speed preset (Center's Standard/Sport): `standard` (slower follow) or `sport` (snappier). |\n| `obsbot_focus_face` | `enabled` (bool), `camera`? | Enable or disable face-priority autofocus. |\n\n### Image & lens\n\nFocus, white balance, and exposure each split into a dedicated `_auto` and `_manual` tool in\nv0.4.0 (previously one tool with a mode parameter) — auto and manual take different parameters, so\nsplitting them lets each schema say exactly what it needs.\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_image_fov` | `fov`: `\"wide\" \\| \"medium\" \\| \"narrow\"`, `camera`? | Set the field of view: wide (86°), medium (78°), narrow (65°). |\n| `obsbot_image_hdr` | `enabled` (bool), `camera`? | Toggle HDR/WDR imaging on or off. |\n| `obsbot_focus_auto` | `camera`? | Enable continuous autofocus. |\n| `obsbot_focus_manual` | `position` (`0`–`100`, default `50`), `camera`? | Set the focus motor to `position` (near→far). |\n| `obsbot_image_exposure_auto` | `priority` (`\"global\" \\| \"face\"`, optional), `camera`? | Enable auto-exposure; optional `priority` selects global vs face metering. |\n| `obsbot_image_exposure_manual` | `level` (`0`–`100`, default `50`), `camera`? | Set exposure `level` (0 darkest → 100 brightest). |\n| `obsbot_image_wb_auto` | `camera`? | Enable auto white balance. |\n| `obsbot_image_wb_manual` | `temperature` (Kelvin, default `5000`), `camera`? | Set a colour temperature (clamped to device range). |\n| `obsbot_image_adjust` | `control`, `level` (`0`–`100`), `camera`? | Adjust `brightness \\| contrast \\| hue \\| saturation \\| sharpness \\| gain \\| backlight-compensation`; `level` maps onto the device range. **`gain` and `backlight-compensation` are not implemented on the Tiny 2** (it reports them as zero-length controls) and are refused with an error; the other five work. |\n\n### Capture\n\n**`obsbot_capture_record` and `obsbot_capture_preview` do not take `camera`.** They select a device\nby `source` (`device`/`virtual`/`ndi`) through ffmpeg/ffplay, not by serial — there is no\nserial-to-ffmpeg-device mapping yet. **`obsbot_capture_snapshot` honors `camera` only for\n`source:\"device\"`**; for `source:\"virtual\"`/`\"ndi\"` the pixel source is still resolved by device\nname, independent of `camera`.\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_capture_snapshot` | `resolution` (`256`–`1920`, default `640`), `quality` (`1`–`100`, default `80`), `settleMs` (`0`–`15000`, default `600`), `source` (default `\"device\"`), `camera`? (source:\"device\" only) | Grab one still frame and return it as an image (for framing/lighting/exposure checks). `resolution` is the longest edge in pixels — larger costs proportionally more tokens. `source`: `device \\| virtual \\| ndi`. Also returns `sourceFormat` — the format the capture graph negotiated, e.g. `MJPG 1920x1080@30.00` — because **frame rate selects the field of view on this camera** (see limitations); Windows only, absent means unknown. A source that connects lazily (NDI) may need a larger `settleMs`. |\n| `obsbot_capture_record` | `durationSec` (optional), `audio` (default `true`), `outputPath` (optional), `source` (default `\"device\"`) | Start recording to MP4. Open-ended recordings auto-stop after 60 min; audio uses the OBSBOT mic; defaults to `~/Videos/OBSBOT` on every platform, including macOS, where that is not the usual `~/Movies`. Returns a `sessionId`. **Needs ffmpeg.**¹ No `camera`. |\n| `obsbot_capture_preview` | `source` (default `\"device\"`) | Open a live preview window. Returns a `sessionId`. **Needs ffplay.**¹ No `camera`. `device` is pinned to 1080p60 mjpeg for smooth motion — which costs field of view (see limitations). `virtual`/`ndi` negotiate instead, since neither offers mjpeg and pinning it there prevents the device opening at all. |\n| `obsbot_capture_stop` | `sessionId` | Stop a recording or preview session (recordings are finalized gracefully). No `camera`. |\n| `obsbot_capture_list` | — | List active recording/preview sessions. No `camera`. |\n\n### Diagnostics (`--debug` only)\n\n| Tool | Parameters | Description |\n|------|------------|-------------|\n| `obsbot_debug_probe` | `mode`: `\"get\" \\| \"set\" \\| \"query\"`, plus `selector`, `length`, `hex`, `opcode`, `payloadHex` | RE/diagnostics only — raw XU byte get/set and framed table queries. Advertised only under `--debug`. No `camera`. |\n\n¹ `record`/`preview` shell out to **ffmpeg**/**ffplay** (install: `winget install Gyan.FFmpeg`\non Windows, `brew install ffmpeg` on macOS, `apt install ffmpeg` on Linux). `snapshot` does **not**\nneed ffmpeg — it grabs the frame through the native helper.\n\n## Supported platforms\n\n- **Windows x64** — supported today. The native helper is built from source in `native/windows/`\n  (CMake + MSVC); the published npm package ships a prebuilt binary so end users need no toolchain.\n- **Linux x64** — supported from v0.2. The native helper is in `native/linux/` (CMake + GCC);\n  it uses **V4L2** for standard UVC controls (zoom, focus, exposure, pan/tilt, white balance,\n  image controls) and `UVCIOC_CTRL_QUERY` for vendor Extension Unit commands (gimbal speed/AI\n  tracking, wake/sleep, HDR, FOV). Snapshots capture a MJPEG or YUYV frame via V4L2 mmap streaming\n  and encode to JPEG using **libjpeg**. The `linux-x64` prebuilt binary ships with the published npm\n  package. Build dependencies: `build-essential cmake libjpeg-dev libv4l-dev`.\n\n  Gimbal *position* reads (`obsbot_gimbal_position`) reflect the last-commanded value, not live\n  in-flight position — see [\"Linux gimbal position feedback\"](#linux-gimbal-position-feedback-is-not-live)\n  below for why, and what would fix it.\n- **macOS 14+ (Apple Silicon and Intel)** — supported. The native helper is in `native/macos/`\n  (Objective-C + **IOKit**/**AVFoundation**). It uses IOKit USB control transfers for both standard\n  UVC controls and vendor Extension Unit commands, and AVFoundation for enumeration and snapshots.\n  Both `darwin-arm64` and `darwin-x64` prebuilt binaries ship with the published npm package\n  (`darwin-x64` also covers Apple Silicon running Node under Rosetta, where `process.arch` reports\n  `x64`). macOS 14 is the floor because the helper uses `AVCaptureDeviceTypeExternal`; the build\n  pins `-mmacosx-version-min` so the binary does not inherit the build machine's OS as its\n  minimum.\n\n  Note on macOS specifically: `UVCAssistant` (a DriverKit system extension) owns the camera's UVC\n  *interfaces* exclusively, so `USBInterfaceOpen` — and even `USBInterfaceOpenSeize` — fail with\n  `kIOReturnExclusiveAccess`. The helper therefore opens the USB *device*, which is not locked, and\n  issues UVC control requests on its default control endpoint. This coexists with `UVCAssistant`:\n  the camera keeps working as a normal webcam while under control, so no driver-replacement step\n  is needed.\n\n### Building the native helper (Linux)\n\n```bash\ncd native/linux\nmkdir build && cd build\ncmake ..\nmake -j$(nproc)\nmake install  # copies to native/prebuilt/linux-x64/\n```\n\n### Linux gimbal position feedback is not live\n\n`obsbot_gimbal_position` on Linux reports the last position `obsbot_gimbal_move`/\n`obsbot_gimbal_recenter` commanded — not a live, in-flight reading. Hardware testing (2026-07-21)\nconfirmed the OBSBOT Tiny 2's `CT_PANTILT_ABSOLUTE` control genuinely tracks live position — a raw\nUSB read of that same control, bypassing the kernel, showed a real slew progressing in real time.\nThe reason plain V4L2 (`VIDIOC_G_CTRL`) never sees that is that `uvcvideo` caches the control's\nvalue and serves the cache instead of re-querying the device (confirmed via\n`VIDIOC_QUERY_EXT_CTRL`, which reports no `V4L2_CTRL_FLAG_VOLATILE`). The driver invalidates that\ncache when the device sends a UVC Control Change interrupt — which this camera's firmware never\ndoes, and never advertises support for.\n\nGetting a genuinely live reading through V4L2 requires briefly detaching the kernel driver from\nthe camera's control interface and reading the control directly over raw USB — but detaching that\ninterface (even briefly, even without writing anything) breaks any concurrent video capture on this\ndevice: streaming and control share one kernel-managed USB function, so pulling the driver off one\ntakes both down together. That makes a libusb-based workaround incompatible with anything actually\nusing the camera as a webcam at the same time, which ruled it out as a shipped default.\n\n**A kernel patch has been submitted upstream** ([`media: uvcvideo: query pan/tilt position from\nthe device on every read`](https://lore.kernel.org/linux-media/20260725212332.64927-1-jordan.mymail@gmail.com/),\nJuly 2026 — awaiting review, not merged). It marks `CT_PANTILT_ABSOLUTE` volatile so the driver\nqueries the device on every read; verified on this hardware to track a live slew through plain\n`VIDIOC_G_CTRL`, concurrently with streaming. If it is accepted, `obsbot_gimbal_position` becomes\nlive on Linux with no code changes needed here. Until it ships in a kernel near you:\n\n- `obsbot_gimbal_move` and `obsbot_gimbal_recenter` work normally — hardware-verified,\n  repeatedly, via direct V4L2 `VIDIOC_S_CTRL` writes. Their target values are known and clamped\n  before being sent, so they can't exceed the gimbal's mechanical range regardless of the missing\n  feedback.\n- **`obsbot_gimbal_move_speed` is not available on Linux** (hidden from the tool list entirely,\n  not just refused at runtime). A speed×duration burst has no target position to clamp — without a\n  live reading to confirm where the gimbal actually is, there's no way to bound it against the\n  mechanical limits before it gets there. It remains available on Windows/macOS.\n\n### Building the native helper (macOS)\n\n```bash\nmake -C native/macos    # -> native/prebuilt/darwin-arm64/obsbot-helper\n```\n\nRequires the Xcode command line tools. CMake works too (`cmake -S native/macos -B\nnative/macos/build && cmake --build native/macos/build`), which is what CI uses.\n\n## Known limitations\n\nWhat has actually been exercised against hardware, and what hasn't:\n\n| Platform | Status |\n|---|---|\n| `win32-x64` | **Hardware-verified** — mid-session disconnect recovery (`ERROR_DEV_NOT_EXIST`, measured not guessed), camera arrival/removal push events, proactive re-bind across a **same-port** replug with no tool call, white balance, and the ProcAmp control ranges, on a real Tiny 2. A **different-port** replug recovers on the next tool call rather than proactively — see below |\n| `linux-x64` | **Hardware-verified** — gimbal absolute moves and recenter via V4L2 (20 consecutive moves with a live preview running), and the arc-second scaling fix confirmed by physical swing. Gimbal *position* is not live and `obsbot_gimbal_move_speed` is unavailable — see below |\n| `darwin-arm64` | **Hardware-verified** — control, gimbal movement **and per-axis position readback**, zoom, snapshot, USB vid/pid candidacy, serial readback and serial-keyed binding, single-owner IPC coordination, helper-death recovery, and **unaided recovery from an unplug/replug**, on a real Tiny 2 |\n| `darwin-x64` | **Build-verified only** — compiles with the right architecture and deployment target, never executed |\n\n- **The Intel (`darwin-x64`) helper has never been run.** No Intel Mac was available to test it. It\n  cross-compiles cleanly and is packaged, but nothing has confirmed it talks to a camera. It also\n  covers Apple Silicon running Node under Rosetta, where `process.arch` reports `x64` — likewise\n  untested. Reports from Intel users are welcome.\n- **macOS 14 or newer is required**, and macOS runtime is verified on **26.5 only**. The helper uses\n  `AVCaptureDeviceTypeExternal` (macOS 14+), so the build pins `-mmacosx-version-min=14.0`. The\n  binary will *load* on 14 through 25, but behavior there is untested — in particular the UVC\n  control path relies on `UVCAssistant` holding the camera's UVC interfaces while leaving the USB\n  device itself openable. That is how current macOS behaves; older releases are unconfirmed.\n- **The first snapshot on macOS raises a camera permission prompt.** The helper is a plain CLI tool\n  with no bundle identifier, so macOS attributes camera access to whichever app spawned it — your\n  MCP client — and that app is named in the prompt and holds the grant. Approve once; the grant\n  survives helper updates, since it is keyed to the client rather than to the helper's signature.\n- **AI tracking overrides manual gimbal moves.** When AI tracking is active (the Tiny 2's default\n  on wake), a commanded pan/tilt executes and is then pulled back to the tracked subject —\n  `obsbot_gimbal_position` shows the yaw/pitch move out and decay back to rest. This is the camera's\n  behaviour, not a bug: turn tracking off for unopposed manual control.\n- **The camera may not enumerate through a USB hub or dock.** A Tiny 2 connected through a USB-C\n  dock was invisible to `ioreg` and `system_profiler` entirely — not just to this server. If\n  `obsbot_devices` comes back empty, try a direct connection before assuming a software fault.\n- **Only the OBSBOT Tiny 2 is supported.** On Windows and macOS candidacy is gated on the Remo USB\n  vendor ID plus a known-model product ID (`0x3564`/`0xFEF8`), so no other model is detected at\n  all — and a name-matching software source, such as the \"OBSBOT Virtual Camera\" that OBSBOT Center\n  registers, is rejected because it reports no vid/pid. Linux still matches by name, because its\n  helper does not report vid/pid yet, so a different OBSBOT may be *found* there — but the vendor\n  command set is Tiny 2 specific either way. (On macOS the virtual camera cannot appear at all: the\n  helper enumerates USB devices through the IORegistry, which a software camera never enters.)\n- **The vendor reply mailbox is unreliable for several seconds after a replug.** On 2026-07-21 a\n  Tiny 2 was seen returning only the host's own echoed request frame from the vendor reply mailbox\n  (XU selector 2) — magic byte `0xaa` cleared to `0x00`, every other byte identical — for a\n  continuous 3.2 s. `readSerial()` threw, `bind()` found no serial, and every tool needing a bound\n  camera failed with \"no OBSBOT camera found\" while the device was plainly healthy: correct\n  vid/pid, opened fine, XU node 2, live status block on selector 6.\n\n  That was unexplained for a while. It is now reproducible: **immediately after a USB\n  re-enumeration**. Polling `readSerial` every 50 ms across a replug failed 22 times in 80 attempts\n  spread over the first 14 s, against 0 in 120 in steady state; the first read after arrival showed\n  exactly the echoed-request signature above, and later failures showed the reply slot populated\n  but with its magic byte still zeroed. Ruled out as causes: stale per-process device state (the\n  same long-lived helper read a brand-new uniqueID cleanly at t+49 ms), re-opening the device\n  (0/40 either way), and the per-transport sequence counter restarting at 1 (0/80).\n\n  Consequence for callers: a bind attempted in the first seconds after a replug can fail even\n  though the camera is fine. Retrying works. The arrival-driven re-bind now retries on a bounded\n  ladder for this reason, and a `readSerial` failure reports what the mailbox actually held\n  (echoed request / unparseable / a reply to another request) rather than only \"no valid reply\".\n  Ruled out earlier and still ruled out: reply latency (polled 3.2 s), the wrong extension unit\n  (the VideoControl interface exposes exactly one, `bUnitID 2`), the wrong `wLength` (every XU\n  selector is 60 bytes by `GET_LEN`), the reply arriving on another selector (1–19 swept), camera\n  sleep state, and contention from OBSBOT Center.\n- **Recovery after a replug is proactive, but not in every case, and it differs by platform.**\n  The server subscribes to OS camera arrival/removal events, so in the common case a replugged\n  camera re-binds itself with no tool call — `obsbot_devices` reports it `bound` again on its own.\n  Every cell below is hardware-measured:\n\n  | scenario | macOS | Windows | Linux |\n  |---|---|---|---|\n  | same-port replug | proactive | proactive | next tool call |\n  | different-port replug | proactive | next tool call | next tool call |\n\n  Where it says \"next tool call\", nothing is stranded — the call that follows detects the stale\n  binding, prunes it and re-binds. It costs one failed call, which is exactly how every platform\n  behaved before these events existed. The Windows difference comes from its arrival filter\n  requiring a path it has already enumerated, which is also what stops the Tiny 2's *audio*\n  interface from being reported as a second camera; macOS has no equivalent problem because it\n  re-binds by serial and ignores the path. Linux emits no bus events at all yet.\n\n  Note the interaction with the mailbox entry above: a re-bind attempted immediately after a\n  replug can still lose the first attempt, so the server retries on a short bounded ladder.\n\n- **Two-camera operation is not yet hardware-verified.** The `camera` selector and the\n  per-camera device registry are covered by the unit test suite against fake transports; running\n  two physical Tiny 2s attached at once has not been confirmed on real hardware (a second unit\n  wasn't available). Single-camera use is unaffected either way.\n- **Linux gimbal position feedback is not live, and `obsbot_gimbal_move_speed` is unavailable\n  there as a result.** See [\"Linux gimbal position feedback is not live\"](#linux-gimbal-position-feedback-is-not-live)\n  above — a kernel patch fixing this at the source [has been submitted upstream](https://lore.kernel.org/linux-media/20260725212332.64927-1-jordan.mymail@gmail.com/)\n  (July 2026, awaiting review). `obsbot_gimbal_move` and\n  `obsbot_gimbal_recenter` are unaffected; both are hardware-verified to work normally.\n  `obsbot_aim_at_pixel` **is** affected — it depends on a live pose reading to compute the aim, the\n  same way `obsbot_gimbal_position` does.\n- **`obsbot_zoom_vendor`'s ratio scale doesn't match `obsbot_zoom_uvc`'s at the same `ratio`.** A\n  hardware snapshot comparison at `ratio: 2.0` showed the vendor path framed tighter than the UVC\n  path. Whether the vendor-side ratio encoding is off by a scale factor, or the two zoom controls\n  simply have different physical ranges, isn't determined yet — one comparison isn't enough to\n  tell. Tracked separately; use `obsbot_zoom_uvc` if you need the ratio to land exactly.\n\n## No proprietary SDK\n\nThis project speaks the camera's USB protocol directly through the OS's standard UVC driver stack and\ndoes **not** use, link, bundle, or ship any vendor SDK. See [`PROTOCOL.md`](./PROTOCOL.md) for the\nprotocol reference (frame format, checksum, command table).\n\n## How it works\n\nThe camera exposes two independent control surfaces, both reachable through the OS's standard UVC\n(USB Video Class) driver stack — this project never talks to the USB device directly, so the OS keeps\nmediating access and the camera remains usable as a normal webcam at the same time commands are sent:\n\n- **Standard UVC controls** — zoom (`CT_ZOOM_ABSOLUTE`), focus and exposure (`IAMCameraControl`),\n  gimbal position readback (UVC Pan/Tilt), and the image controls plus white balance\n  (`IAMVideoProcAmp`) — are the camera's built-in UVC properties, driven via DirectShow on Windows.\n- **Vendor commands** — gimbal moves, recenter, wake/sleep, AI tracking, HDR, and field of view —\n  are sent through the camera's UVC Extension Unit, driven via `IKsControl::KsProperty` against the\n  XU's topology node on Windows.\n\nBoth are issued through a small native helper process (`obsbot-helper.exe` on Windows, `obsbot-helper`\non Linux) that the Node server spawns and talks to over a line-delimited JSON-RPC protocol on\nstdin/stdout. The helper is the only platform-specific piece; the codec (frame encoding, CRC-16/USB\nchecksum, command table), transport abstraction, device manager, and MCP tool definitions are all pure\nTypeScript/JavaScript and shared across platforms.\n\n## Verifying against real hardware\n\n`scripts/e2e.mjs` drives the built stack (`dist/`) against a physically connected camera: it wakes the\ndevice, zooms in, pans the gimbal, recenters, zooms back out, and puts the camera to sleep, with a short\npause and console log before each step so a human can watch it happen. **This moves the physical gimbal —\nonly run it under supervision:**\n\n```bash\nnpm run build\nnode scripts/e2e.mjs\n```\n\n### Testing changes through the live MCP tools\n\nTwo traps make it easy to test the wrong thing and believe the result. Both cost real time on\n2026-07-25.\n\n**Rebuilding and reloading is not enough — kill stale server processes first.** The MCP server runs\nfrom `dist/`, so a source change is invisible until `npm run build`. But reloading the server in your\nMCP client does *not* guarantee your new code executes: this project coordinates concurrent clients\nby electing a single owner process (see `IPC-DESIGN.md`), and a reload spawns a *new* client that\n**forwards its tool calls to whatever owner is already running**. An orphaned server from a previous\nsession stays the owner, so the new process advertises its own up-to-date tool list while every call\nis executed by old code.\n\nThat failure is deceptive rather than loud: a newly added tool *appears* in the tool list and can be\ncalled, but behaves like the old build. Two reloads in a row will not fix it. Check for orphans\nbefore concluding anything:\n\n```powershell\n# Windows\nGet-CimInstance Win32_Process -Filter \"Name='node.exe'\" |\n  Where-Object { $_.CommandLine -like \"*Obsbot*\" } |\n  Select-Object ProcessId, CreationDate\n```\n\n```bash\n# Linux / macOS\npgrep -af \"obsbot.*dist/index.js\"\n```\n\nKill everything older than your build, then reload. The cheapest positive confirmation is to call a\ntool whose *output* changed — `obsbot_status` gaining a field, say — rather than one whose\ndescription changed, since descriptions come from the new process either way.\n\n**Frame rate selects the field of view, so the preview shows less than snapshots.** At 1920×1080 this\ncamera has two different windows onto the sensor and the *frame rate* picks between them — not the\ncodec. Measured at one pose and one zoom: MJPEG@30 vs YUYV@30 came out at scale 1.00001 over 2382\ninliers, i.e. the same field to within a fifth of a pixel, while MJPEG@60 is a **1.214× crop of both**.\n`obsbot_capture_preview` pins 60fps for smooth motion, so it shows ~21% less of the room than\n`obsbot_capture_snapshot`, which negotiates 1080p30. Framing by eye in the preview and then aiming at a\npixel from a snapshot will not agree. The geometry constants describe the 30fps field. Any measurement\nyou make must state pixel format **and** frame rate; neither a resolution nor a codec alone identifies\nthe field.\n\n**A preview holds the camera stream, so snapshots fail while one is open.** `obsbot_capture_preview`\nand `obsbot_capture_snapshot` both need the device stream, and on Windows the second one gets\n`Camera is in use by another application`. This matters for the aim loop above, which is\nsnapshot → aim → snapshot: stop the preview around each snapshot, or work without one. Gimbal control\nis unaffected — it uses control transfers, not the stream — so `obsbot_aim_at_pixel` itself works fine\nwith a preview running. The error text suggests `source: \"virtual\"` or `\"ndi\"` as a workaround. That is safe for *looking*,\nand safe for *aiming* only if the feed is an unmodified pass-through of the camera — declare it with\nthe `source` parameter on `obsbot_aim_at_pixel` / `obsbot_zoom_to_fit` and read the `note` it returns.\nA compositor that rescales or letterboxes the frame silently invalidates the geometry.\n",
  "bytes": 39958,
  "sha": "1b2a14ab8442c19fc8697920a00ddf2952315ee908ee8715dd34764234466a6f",
  "repo_slug": "lxman/obsbot-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lxman_obsbot_mcp_8a93d085/readme"
}