用途
obsbot-mcp 是一个跨平台的模型上下文协议（Model Context Protocol，MCP）服务器，用于控制 OBSBOT Tiny 2 摄像头。它通过摄像头标准的 UVC/USB 接口工作，无需厂商 SDK。同时，它还通过 HTTP/WS API 控制 OBSBOT Tail 2 网络摄像头。
主要能力
在 Windows 和 macOS 上提供 35 个工具，Linux 上 34 个（Linux 缺少 obsbot_gimbal_move_speed）。加上 --debug 参数会额外暴露 obsbot_debug_probe 诊断工具。每个网络中的 Tail 2 摄像头会增加 32 个 obsbot_tail2_* 工具。工具名称以 v0.4.0 为准，所有工具在该版本中重命名，没有向后兼容别名。
控制能力包括：云台平移/倾斜/旋转、变焦、AI 主体跟踪、对焦、曝光、白平衡和图像控制、HDR 和视场切换，以及截图、预览和录制。
使用方式
MCP 客户端配置：添加一个 stdio 服务器条目，指向已安装的二进制文件（或直接指向 dist/index.js）。如果从本地检出运行而不是 npm 安装，则将 command/args 指向 node 和构建入口点。安装二进制后，使用 "command": "obsbot-mcp"。调试模式使用 "args": ["--debug"]。
摄像头选择器：每个摄像头寻址工具都接受一个可选的 camera 参数，即目标摄像头的序列号。单摄像头连接时省略该参数，行为与 v0.4.0 之前完全相同。多摄像头连接时，省略 camera 的调用会失败并列出所有已连接的序列号。例外：obsbot_devices（枚举整个设备群）、obsbot_capture_stop / obsbot_capture_list（寻址 sessionId 而非设备）、obsbot_debug_probe（操作当前诊断传输）。obsbot_capture_record 和 obsbot_capture_preview 不接受 camera，它们通过 source（device/virtual/ndi）选择设备，而不是序列号。obsbot_capture_snapshot 仅在 source:"device" 时遵循 camera。
多摄像头支持是 v0.4.0 新增功能，已通过针对假设备的单元测试验证，但尚未在硬件上同时运行两台物理 Tiny 2 验证。
obsbot_devices 用于发现作为 camera 传递的序列号：报告每个已连接摄像头的序列号（在可获取时——读取需要短暂打开摄像头）、名称和状态（available | bound | busy）。被其他进程占用的摄像头返回 busy 且无序列号。
截图与瞄准：obsbot_capture_snapshot 返回图像帧及其宽度/高度。obsbot_aim_at_pixel 传入目标的像素坐标和该帧的尺寸，然后再次截图确认。必须使用同一快照的 frameWidth/frameHeight，混合不同帧的像素和尺寸会导致瞄准错误且无法检测。快照必须使用 source: "device"，virtual 或 ndi 来自 OBSBOT Center 的输出，其视场常量不适用。该工具自行读取摄像头放大倍率（离散 FOV 模式或连续变焦均可，m = 3*ratio-2，硬件实测误差小于 0.05%）。当 AI 跟踪开启、FOV 模式无法解码、变焦读数损坏导致放大倍率不合理、或摄像头从睡眠中被唤醒时，工具会拒绝而非猜测。
obsbot_zoom_to_fit 将点扩展为区域：传入边界框（x, y, width, height）和该帧尺寸，工具会缩放使该区域填满画面。它共享 obsbot_aim_at_pixel 的拒绝条件，并额外要求区域在帧内、宽高为正。margin（默认 0.1，即 10%）会按该比例缩小请求的变焦，留出余量。工具总是选择两个轴所需放大倍率中较小的一个，结果被限制在摄像头 [1x, 4x] 范围内（通过 clamped 报告）。云台先移动再命令变焦。变焦不是瞬时的，在硬件上会逐步逼近目标值，obsbot_zoom_to_fit 最多轮询 3 秒等待变焦到位，若未到位返回 settled:false（不是错误）。
预设：三个设备端预设槽（1–3）。槽位为一次性创建：obsbot_preset_save 需要空槽（先删除才能重用），其他预设工具需要槽位已被占用。每个工具在写入后重新读取槽位列表，若设备未落实更改则返回结构化 { ok:false } 失败。
变焦有两个工具而非一个，它们使用不同传输（标准 UVC 与厂商命令帧），在相同命令比率下产生不同的物理变焦，因此合并会静默改变比率含义。
对焦、白平衡和曝光在 v0.4.0 中各自拆分为专用的 _auto 和 _manual 工具（之前是一个带 mode 参数的工具）。
适用场景
适用于需要通过 MCP 控制 OBSBOT Tiny 2 或 Tail 2 摄像头的场景，例如自动化视频制作、AI 驱动的摄像头操作、远程控制、截图分析后自动瞄准目标等。
限制
已知限制：Linux 上 obsbot_gimbal_move_speed 不可用。多摄像头仅经单元测试验证，未在硬件上同时运行两台 Tiny 2 验证。Linux 上 obsbot_gimbal_position 反映最后命令值而非实时飞行位置。录像/预览需要 ffmpeg/ffplay（Windows 安装：winget install Gyan.FFmpeg；macOS：brew install ffmpeg；Linux：apt install ffmpeg）。截图不需要 ffmpeg。macOS 14 是下限，因为辅助程序使用 AVCaptureDeviceTypeExternal。Tail 2 的已知缺口：通过 REST 的图像控制写入未探测；截图依赖 OBSBOT Center 启用 SRT 输出（与 NDI 互斥，重启会清除）；该固件下 RTSP 输出从不服务，尽管其启用标志存在。摄像头控制 API 未认证，局域网内任何人都可驱动它，包括关机。
