obsbot-mcp 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +170 -170
- package/native/prebuilt/win32-x64/obsbot-helper.exe +0 -0
- package/package.json +53 -33
package/README.md
CHANGED
|
@@ -1,170 +1,170 @@
|
|
|
1
|
-
# obsbot-mcp
|
|
2
|
-
|
|
3
|
-
A cross-platform [Model Context Protocol](https://modelcontextprotocol.io) server that controls an
|
|
4
|
-
**OBSBOT Tiny 2** camera over its standard UVC/USB interface — pan/tilt/roll the gimbal, zoom, AI
|
|
5
|
-
subject tracking, focus/exposure/white-balance/image controls, HDR and field-of-view, plus snapshot,
|
|
6
|
-
preview, and recording — without any vendor SDK.
|
|
7
|
-
|
|
8
|
-
## Install
|
|
9
|
-
|
|
10
|
-
```bash
|
|
11
|
-
npm install obsbot-mcp
|
|
12
|
-
```
|
|
13
|
-
|
|
14
|
-
## MCP client configuration
|
|
15
|
-
|
|
16
|
-
Add a stdio server entry pointing at the installed binary (or directly at `dist/index.js`):
|
|
17
|
-
|
|
18
|
-
```json
|
|
19
|
-
{
|
|
20
|
-
"mcpServers": {
|
|
21
|
-
"obsbot": {
|
|
22
|
-
"command": "obsbot-mcp"
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
}
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
If you're running from a local checkout instead of an npm install, point `command`/`args` at
|
|
29
|
-
`node` and the built entry point instead:
|
|
30
|
-
|
|
31
|
-
```json
|
|
32
|
-
{
|
|
33
|
-
"mcpServers": {
|
|
34
|
-
"obsbot": {
|
|
35
|
-
"command": "node",
|
|
36
|
-
"args": ["path/to/obsbot-mcp/dist/index.js"]
|
|
37
|
-
}
|
|
38
|
-
}
|
|
39
|
-
}
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
### Debug / diagnostics tools
|
|
43
|
-
|
|
44
|
-
By default the server advertises only the normal control surface. Pass `--debug` to additionally
|
|
45
|
-
expose the diagnostics surface — the `obsbot_probe` tool (raw XU byte get/set/query) and the
|
|
46
|
-
`raw` 60-byte status block on `obsbot_get_status`:
|
|
47
|
-
|
|
48
|
-
```json
|
|
49
|
-
{
|
|
50
|
-
"mcpServers": {
|
|
51
|
-
"obsbot": {
|
|
52
|
-
"command": "node",
|
|
53
|
-
"args": ["path/to/obsbot-mcp/dist/index.js", "--debug"]
|
|
54
|
-
}
|
|
55
|
-
}
|
|
56
|
-
}
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
With the installed binary, use `"command": "obsbot-mcp"` and `"args": ["--debug"]`.
|
|
60
|
-
|
|
61
|
-
## Tools
|
|
62
|
-
|
|
63
|
-
### Device & power
|
|
64
|
-
|
|
65
|
-
| Tool | Parameters | Description |
|
|
66
|
-
|------|------------|-------------|
|
|
67
|
-
| `obsbot_list_devices` | — | List connected OBSBOT-compatible video capture devices. |
|
|
68
|
-
| `obsbot_set_run_status` | `state`: `"run" \| "sleep"` | Wake (`"run"`) or sleep the camera/gimbal. |
|
|
69
|
-
| `obsbot_get_status` | — | Read the live status block: `{ awake, hdr, aiMode, trackSpeed }`. Under `--debug`, also returns the raw 60-byte block as hex. |
|
|
70
|
-
|
|
71
|
-
### Gimbal (PTZ)
|
|
72
|
-
|
|
73
|
-
| Tool | Parameters | Description |
|
|
74
|
-
|------|------------|-------------|
|
|
75
|
-
| `obsbot_ptz_move_angle` | `yaw`, `pitch`, `roll` (degrees, `roll` defaults `0`) | 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. |
|
|
76
|
-
| `obsbot_ptz_move_speed` | `yaw`, `pitch`, `roll` (deg/s, `roll` defaults `0`), `autoStopMs` (default `800`) | Drive the gimbal at a speed, then auto-stop after `autoStopMs` so it can't run away. Same yaw/pitch sign convention as `move_angle`. |
|
|
77
|
-
| `obsbot_gimbal_recenter` | — | Recenter the gimbal (return to home position). |
|
|
78
|
-
| `obsbot_gimbal_position` | — | Read the gimbal's current absolute `{ yaw, pitch }` in degrees via standard UVC Pan/Tilt. May lag a move still in progress. |
|
|
79
|
-
|
|
80
|
-
### Zoom
|
|
81
|
-
|
|
82
|
-
| Tool | Parameters | Description |
|
|
83
|
-
|------|------------|-------------|
|
|
84
|
-
| `obsbot_zoom_absolute` | `ratio` (`1.0`–`2.0`) | Set absolute zoom ratio, clamped to `[1.0, 2.0]`. |
|
|
85
|
-
| `obsbot_zoom_speed` | `ratio` (`1.0`–`2.0`), `speed` (default `0`) | Zoom to a ratio at a chosen speed: `0` = device default, `1`–`10` slow→fast, `255` = maximum. |
|
|
86
|
-
|
|
87
|
-
### AI tracking
|
|
88
|
-
|
|
89
|
-
| Tool | Parameters | Description |
|
|
90
|
-
|------|------------|-------------|
|
|
91
|
-
| `obsbot_ai_tracking` | `enabled` (bool), `mode` (default `"normal"`) | Enable/disable AI subject tracking and choose framing: `normal \| upper-body \| close-up \| headless \| lower-body`. Polls status and returns `{ verified, matched }` (`matched:false` = no subject tracked yet). |
|
|
92
|
-
| `obsbot_ai_track_speed` | `speed`: `"standard" \| "sport"` | Set the tracking-speed preset (Center's Standard/Sport): `standard` (slower follow) or `sport` (snappier). |
|
|
93
|
-
| `obsbot_face_focus` | `enabled` (bool) | Enable or disable face-priority autofocus. |
|
|
94
|
-
|
|
95
|
-
### Image & lens
|
|
96
|
-
|
|
97
|
-
| Tool | Parameters | Description |
|
|
98
|
-
|------|------------|-------------|
|
|
99
|
-
| `obsbot_fov` | `fov`: `"wide" \| "medium" \| "narrow"` | Set the field of view: wide (86°), medium (78°), narrow (65°). |
|
|
100
|
-
| `obsbot_hdr` | `enabled` (bool) | Toggle HDR/WDR imaging on or off. |
|
|
101
|
-
| `obsbot_focus` | `mode`: `"auto" \| "manual"`, `position` (`0`–`100`, default `50`) | `auto` = continuous autofocus; `manual` = set the focus motor to `position` (near→far). |
|
|
102
|
-
| `obsbot_exposure` | `mode`: `"auto" \| "manual"`, `level` (`0`–`100`, default `50`) | `auto` = auto-exposure; `manual` = set `level` (0 darkest → 100 brightest). |
|
|
103
|
-
| `obsbot_white_balance` | `mode`: `"auto" \| "manual"`, `temperature` (Kelvin, default `5000`) | `auto` = auto white balance; `manual` = set a colour temperature (clamped to device range). |
|
|
104
|
-
| `obsbot_image_control` | `control`, `level` (`0`–`100`) | Adjust `brightness \| contrast \| hue \| saturation \| sharpness \| gain \| backlight-compensation`; `level` maps onto the device range. |
|
|
105
|
-
|
|
106
|
-
### Capture
|
|
107
|
-
|
|
108
|
-
| Tool | Parameters | Description |
|
|
109
|
-
|------|------------|-------------|
|
|
110
|
-
| `obsbot_snapshot` | `maxDim` (`256`–`1920`, default `1024`), `quality` (`1`–`100`, default `80`), `settleMs` (default `600`), `source` (default `"device"`) | Grab one still frame and return it as an image (for framing/lighting/exposure checks). `source`: `device \| virtual \| ndi`. |
|
|
111
|
-
| `obsbot_record_start` | `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 under `Videos/OBSBOT`. Returns a `sessionId`. **Needs ffmpeg.**¹ |
|
|
112
|
-
| `obsbot_preview_start` | `source` (default `"device"`) | Open a live preview window. Returns a `sessionId`. **Needs ffplay.**¹ |
|
|
113
|
-
| `obsbot_capture_stop` | `sessionId` | Stop a recording or preview session (recordings are finalized gracefully). |
|
|
114
|
-
| `obsbot_capture_list` | — | List active recording/preview sessions. |
|
|
115
|
-
|
|
116
|
-
### Diagnostics (`--debug` only)
|
|
117
|
-
|
|
118
|
-
| Tool | Parameters | Description |
|
|
119
|
-
|------|------------|-------------|
|
|
120
|
-
| `obsbot_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`. |
|
|
121
|
-
|
|
122
|
-
¹ `record`/`preview` shell out to **ffmpeg**/**ffplay** (install: `winget install Gyan.FFmpeg`
|
|
123
|
-
on Windows, `brew install ffmpeg` on macOS, `apt install ffmpeg` on Linux). `snapshot` does **not**
|
|
124
|
-
need ffmpeg — it grabs the frame through the native helper.
|
|
125
|
-
|
|
126
|
-
## Supported platforms
|
|
127
|
-
|
|
128
|
-
- **Windows x64** — supported today. The native helper is built from source in `native/windows/`
|
|
129
|
-
(CMake + MSVC); the published npm package ships a prebuilt binary so end users need no toolchain.
|
|
130
|
-
- **Linux / macOS** — not yet implemented. The design is platform-agnostic (see [`PROTOCOL.md`](./PROTOCOL.md));
|
|
131
|
-
adding support means writing an equivalent native helper for each OS's UVC control APIs
|
|
132
|
-
(`V4L2` on Linux, `AVFoundation`/`IOKit` on macOS) behind the same JSON-RPC-over-stdio contract used by
|
|
133
|
-
the Windows helper. Contributions welcome.
|
|
134
|
-
|
|
135
|
-
## No proprietary SDK
|
|
136
|
-
|
|
137
|
-
This project speaks the camera's USB protocol directly through the OS's standard UVC driver stack and
|
|
138
|
-
does **not** use, link, bundle, or ship any vendor SDK. See [`PROTOCOL.md`](./PROTOCOL.md) for the
|
|
139
|
-
protocol reference (frame format, checksum, command table).
|
|
140
|
-
|
|
141
|
-
## How it works
|
|
142
|
-
|
|
143
|
-
The camera exposes two independent control surfaces, both reachable through the OS's standard UVC
|
|
144
|
-
(USB Video Class) driver stack — this project never talks to the USB device directly, so the OS keeps
|
|
145
|
-
mediating access and the camera remains usable as a normal webcam at the same time commands are sent:
|
|
146
|
-
|
|
147
|
-
- **Standard UVC controls** — zoom (`CT_ZOOM_ABSOLUTE`), focus and exposure (`IAMCameraControl`),
|
|
148
|
-
gimbal position readback (UVC Pan/Tilt), and the image controls plus white balance
|
|
149
|
-
(`IAMVideoProcAmp`) — are the camera's built-in UVC properties, driven via DirectShow on Windows.
|
|
150
|
-
- **Vendor commands** — gimbal moves, recenter, wake/sleep, AI tracking, HDR, and field of view —
|
|
151
|
-
are sent through the camera's UVC Extension Unit, driven via `IKsControl::KsProperty` against the
|
|
152
|
-
XU's topology node on Windows.
|
|
153
|
-
|
|
154
|
-
Both are issued through a small native helper process (`obsbot-helper.exe` on Windows) that the Node
|
|
155
|
-
server spawns and talks to over a line-delimited JSON-RPC protocol on stdin/stdout. The helper is the
|
|
156
|
-
only platform-specific piece; the codec (frame encoding, CRC-16/USB checksum, command table), transport
|
|
157
|
-
abstraction, device manager, and MCP tool definitions are all pure TypeScript/JavaScript and shared across
|
|
158
|
-
platforms.
|
|
159
|
-
|
|
160
|
-
## Verifying against real hardware
|
|
161
|
-
|
|
162
|
-
`scripts/e2e.mjs` drives the built stack (`dist/`) against a physically connected camera: it wakes the
|
|
163
|
-
device, zooms in, pans the gimbal, recenters, zooms back out, and puts the camera to sleep, with a short
|
|
164
|
-
pause and console log before each step so a human can watch it happen. **This moves the physical gimbal —
|
|
165
|
-
only run it under supervision:**
|
|
166
|
-
|
|
167
|
-
```bash
|
|
168
|
-
npm run build
|
|
169
|
-
node scripts/e2e.mjs
|
|
170
|
-
```
|
|
1
|
+
# obsbot-mcp
|
|
2
|
+
|
|
3
|
+
A cross-platform [Model Context Protocol](https://modelcontextprotocol.io) server that controls an
|
|
4
|
+
**OBSBOT Tiny 2** camera over its standard UVC/USB interface — pan/tilt/roll the gimbal, zoom, AI
|
|
5
|
+
subject tracking, focus/exposure/white-balance/image controls, HDR and field-of-view, plus snapshot,
|
|
6
|
+
preview, and recording — without any vendor SDK.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm install obsbot-mcp
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## MCP client configuration
|
|
15
|
+
|
|
16
|
+
Add a stdio server entry pointing at the installed binary (or directly at `dist/index.js`):
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"mcpServers": {
|
|
21
|
+
"obsbot": {
|
|
22
|
+
"command": "obsbot-mcp"
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
If you're running from a local checkout instead of an npm install, point `command`/`args` at
|
|
29
|
+
`node` and the built entry point instead:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"mcpServers": {
|
|
34
|
+
"obsbot": {
|
|
35
|
+
"command": "node",
|
|
36
|
+
"args": ["path/to/obsbot-mcp/dist/index.js"]
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Debug / diagnostics tools
|
|
43
|
+
|
|
44
|
+
By default the server advertises only the normal control surface. Pass `--debug` to additionally
|
|
45
|
+
expose the diagnostics surface — the `obsbot_probe` tool (raw XU byte get/set/query) and the
|
|
46
|
+
`raw` 60-byte status block on `obsbot_get_status`:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"mcpServers": {
|
|
51
|
+
"obsbot": {
|
|
52
|
+
"command": "node",
|
|
53
|
+
"args": ["path/to/obsbot-mcp/dist/index.js", "--debug"]
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
With the installed binary, use `"command": "obsbot-mcp"` and `"args": ["--debug"]`.
|
|
60
|
+
|
|
61
|
+
## Tools
|
|
62
|
+
|
|
63
|
+
### Device & power
|
|
64
|
+
|
|
65
|
+
| Tool | Parameters | Description |
|
|
66
|
+
|------|------------|-------------|
|
|
67
|
+
| `obsbot_list_devices` | — | List connected OBSBOT-compatible video capture devices. |
|
|
68
|
+
| `obsbot_set_run_status` | `state`: `"run" \| "sleep"` | Wake (`"run"`) or sleep the camera/gimbal. |
|
|
69
|
+
| `obsbot_get_status` | — | Read the live status block: `{ awake, hdr, aiMode, trackSpeed }`. Under `--debug`, also returns the raw 60-byte block as hex. |
|
|
70
|
+
|
|
71
|
+
### Gimbal (PTZ)
|
|
72
|
+
|
|
73
|
+
| Tool | Parameters | Description |
|
|
74
|
+
|------|------------|-------------|
|
|
75
|
+
| `obsbot_ptz_move_angle` | `yaw`, `pitch`, `roll` (degrees, `roll` defaults `0`) | 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. |
|
|
76
|
+
| `obsbot_ptz_move_speed` | `yaw`, `pitch`, `roll` (deg/s, `roll` defaults `0`), `autoStopMs` (default `800`) | Drive the gimbal at a speed, then auto-stop after `autoStopMs` so it can't run away. Same yaw/pitch sign convention as `move_angle`. |
|
|
77
|
+
| `obsbot_gimbal_recenter` | — | Recenter the gimbal (return to home position). |
|
|
78
|
+
| `obsbot_gimbal_position` | — | Read the gimbal's current absolute `{ yaw, pitch }` in degrees via standard UVC Pan/Tilt. May lag a move still in progress. |
|
|
79
|
+
|
|
80
|
+
### Zoom
|
|
81
|
+
|
|
82
|
+
| Tool | Parameters | Description |
|
|
83
|
+
|------|------------|-------------|
|
|
84
|
+
| `obsbot_zoom_absolute` | `ratio` (`1.0`–`2.0`) | Set absolute zoom ratio, clamped to `[1.0, 2.0]`. |
|
|
85
|
+
| `obsbot_zoom_speed` | `ratio` (`1.0`–`2.0`), `speed` (default `0`) | Zoom to a ratio at a chosen speed: `0` = device default, `1`–`10` slow→fast, `255` = maximum. |
|
|
86
|
+
|
|
87
|
+
### AI tracking
|
|
88
|
+
|
|
89
|
+
| Tool | Parameters | Description |
|
|
90
|
+
|------|------------|-------------|
|
|
91
|
+
| `obsbot_ai_tracking` | `enabled` (bool), `mode` (default `"normal"`) | Enable/disable AI subject tracking and choose framing: `normal \| upper-body \| close-up \| headless \| lower-body`. Polls status and returns `{ verified, matched }` (`matched:false` = no subject tracked yet). |
|
|
92
|
+
| `obsbot_ai_track_speed` | `speed`: `"standard" \| "sport"` | Set the tracking-speed preset (Center's Standard/Sport): `standard` (slower follow) or `sport` (snappier). |
|
|
93
|
+
| `obsbot_face_focus` | `enabled` (bool) | Enable or disable face-priority autofocus. |
|
|
94
|
+
|
|
95
|
+
### Image & lens
|
|
96
|
+
|
|
97
|
+
| Tool | Parameters | Description |
|
|
98
|
+
|------|------------|-------------|
|
|
99
|
+
| `obsbot_fov` | `fov`: `"wide" \| "medium" \| "narrow"` | Set the field of view: wide (86°), medium (78°), narrow (65°). |
|
|
100
|
+
| `obsbot_hdr` | `enabled` (bool) | Toggle HDR/WDR imaging on or off. |
|
|
101
|
+
| `obsbot_focus` | `mode`: `"auto" \| "manual"`, `position` (`0`–`100`, default `50`) | `auto` = continuous autofocus; `manual` = set the focus motor to `position` (near→far). |
|
|
102
|
+
| `obsbot_exposure` | `mode`: `"auto" \| "manual"`, `level` (`0`–`100`, default `50`) | `auto` = auto-exposure; `manual` = set `level` (0 darkest → 100 brightest). |
|
|
103
|
+
| `obsbot_white_balance` | `mode`: `"auto" \| "manual"`, `temperature` (Kelvin, default `5000`) | `auto` = auto white balance; `manual` = set a colour temperature (clamped to device range). |
|
|
104
|
+
| `obsbot_image_control` | `control`, `level` (`0`–`100`) | Adjust `brightness \| contrast \| hue \| saturation \| sharpness \| gain \| backlight-compensation`; `level` maps onto the device range. |
|
|
105
|
+
|
|
106
|
+
### Capture
|
|
107
|
+
|
|
108
|
+
| Tool | Parameters | Description |
|
|
109
|
+
|------|------------|-------------|
|
|
110
|
+
| `obsbot_snapshot` | `maxDim` (`256`–`1920`, default `1024`), `quality` (`1`–`100`, default `80`), `settleMs` (default `600`), `source` (default `"device"`) | Grab one still frame and return it as an image (for framing/lighting/exposure checks). `source`: `device \| virtual \| ndi`. |
|
|
111
|
+
| `obsbot_record_start` | `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 under `Videos/OBSBOT`. Returns a `sessionId`. **Needs ffmpeg.**¹ |
|
|
112
|
+
| `obsbot_preview_start` | `source` (default `"device"`) | Open a live preview window. Returns a `sessionId`. **Needs ffplay.**¹ |
|
|
113
|
+
| `obsbot_capture_stop` | `sessionId` | Stop a recording or preview session (recordings are finalized gracefully). |
|
|
114
|
+
| `obsbot_capture_list` | — | List active recording/preview sessions. |
|
|
115
|
+
|
|
116
|
+
### Diagnostics (`--debug` only)
|
|
117
|
+
|
|
118
|
+
| Tool | Parameters | Description |
|
|
119
|
+
|------|------------|-------------|
|
|
120
|
+
| `obsbot_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`. |
|
|
121
|
+
|
|
122
|
+
¹ `record`/`preview` shell out to **ffmpeg**/**ffplay** (install: `winget install Gyan.FFmpeg`
|
|
123
|
+
on Windows, `brew install ffmpeg` on macOS, `apt install ffmpeg` on Linux). `snapshot` does **not**
|
|
124
|
+
need ffmpeg — it grabs the frame through the native helper.
|
|
125
|
+
|
|
126
|
+
## Supported platforms
|
|
127
|
+
|
|
128
|
+
- **Windows x64** — supported today. The native helper is built from source in `native/windows/`
|
|
129
|
+
(CMake + MSVC); the published npm package ships a prebuilt binary so end users need no toolchain.
|
|
130
|
+
- **Linux / macOS** — not yet implemented. The design is platform-agnostic (see [`PROTOCOL.md`](./PROTOCOL.md));
|
|
131
|
+
adding support means writing an equivalent native helper for each OS's UVC control APIs
|
|
132
|
+
(`V4L2` on Linux, `AVFoundation`/`IOKit` on macOS) behind the same JSON-RPC-over-stdio contract used by
|
|
133
|
+
the Windows helper. Contributions welcome.
|
|
134
|
+
|
|
135
|
+
## No proprietary SDK
|
|
136
|
+
|
|
137
|
+
This project speaks the camera's USB protocol directly through the OS's standard UVC driver stack and
|
|
138
|
+
does **not** use, link, bundle, or ship any vendor SDK. See [`PROTOCOL.md`](./PROTOCOL.md) for the
|
|
139
|
+
protocol reference (frame format, checksum, command table).
|
|
140
|
+
|
|
141
|
+
## How it works
|
|
142
|
+
|
|
143
|
+
The camera exposes two independent control surfaces, both reachable through the OS's standard UVC
|
|
144
|
+
(USB Video Class) driver stack — this project never talks to the USB device directly, so the OS keeps
|
|
145
|
+
mediating access and the camera remains usable as a normal webcam at the same time commands are sent:
|
|
146
|
+
|
|
147
|
+
- **Standard UVC controls** — zoom (`CT_ZOOM_ABSOLUTE`), focus and exposure (`IAMCameraControl`),
|
|
148
|
+
gimbal position readback (UVC Pan/Tilt), and the image controls plus white balance
|
|
149
|
+
(`IAMVideoProcAmp`) — are the camera's built-in UVC properties, driven via DirectShow on Windows.
|
|
150
|
+
- **Vendor commands** — gimbal moves, recenter, wake/sleep, AI tracking, HDR, and field of view —
|
|
151
|
+
are sent through the camera's UVC Extension Unit, driven via `IKsControl::KsProperty` against the
|
|
152
|
+
XU's topology node on Windows.
|
|
153
|
+
|
|
154
|
+
Both are issued through a small native helper process (`obsbot-helper.exe` on Windows) that the Node
|
|
155
|
+
server spawns and talks to over a line-delimited JSON-RPC protocol on stdin/stdout. The helper is the
|
|
156
|
+
only platform-specific piece; the codec (frame encoding, CRC-16/USB checksum, command table), transport
|
|
157
|
+
abstraction, device manager, and MCP tool definitions are all pure TypeScript/JavaScript and shared across
|
|
158
|
+
platforms.
|
|
159
|
+
|
|
160
|
+
## Verifying against real hardware
|
|
161
|
+
|
|
162
|
+
`scripts/e2e.mjs` drives the built stack (`dist/`) against a physically connected camera: it wakes the
|
|
163
|
+
device, zooms in, pans the gimbal, recenters, zooms back out, and puts the camera to sleep, with a short
|
|
164
|
+
pause and console log before each step so a human can watch it happen. **This moves the physical gimbal —
|
|
165
|
+
only run it under supervision:**
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
npm run build
|
|
169
|
+
node scripts/e2e.mjs
|
|
170
|
+
```
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,33 +1,53 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "obsbot-mcp",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Cross-platform MCP server for OBSBOT Tiny 2 (UVC) camera control",
|
|
5
|
-
"license": "MIT",
|
|
6
|
-
"author": "Michael Jordan",
|
|
7
|
-
"repository": {
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
"
|
|
12
|
-
"
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
"
|
|
16
|
-
"
|
|
17
|
-
"
|
|
18
|
-
"
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
"
|
|
22
|
-
"
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
"
|
|
26
|
-
"
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "obsbot-mcp",
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Cross-platform MCP server for OBSBOT Tiny 2 (UVC) camera control",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Michael Jordan",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/lxman/obsbot-mcp.git"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/lxman/obsbot-mcp#readme",
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/lxman/obsbot-mcp/issues"
|
|
14
|
+
},
|
|
15
|
+
"keywords": [
|
|
16
|
+
"mcp",
|
|
17
|
+
"model-context-protocol",
|
|
18
|
+
"obsbot",
|
|
19
|
+
"webcam",
|
|
20
|
+
"uvc",
|
|
21
|
+
"ptz",
|
|
22
|
+
"camera"
|
|
23
|
+
],
|
|
24
|
+
"type": "module",
|
|
25
|
+
"bin": {
|
|
26
|
+
"obsbot-mcp": "dist/index.js"
|
|
27
|
+
},
|
|
28
|
+
"files": [
|
|
29
|
+
"dist/",
|
|
30
|
+
"native/prebuilt/"
|
|
31
|
+
],
|
|
32
|
+
"engines": {
|
|
33
|
+
"node": ">=18"
|
|
34
|
+
},
|
|
35
|
+
"scripts": {
|
|
36
|
+
"build": "tsc -p tsconfig.json",
|
|
37
|
+
"test": "vitest run",
|
|
38
|
+
"test:watch": "vitest"
|
|
39
|
+
},
|
|
40
|
+
"dependencies": {
|
|
41
|
+
"@modelcontextprotocol/sdk": "^1.0.0",
|
|
42
|
+
"zod": "^3.23.0",
|
|
43
|
+
"zod-to-json-schema": "^3.23.0"
|
|
44
|
+
},
|
|
45
|
+
"devDependencies": {
|
|
46
|
+
"typescript": "^5.5.0",
|
|
47
|
+
"vitest": "^2.0.0",
|
|
48
|
+
"@types/node": "^20.0.0"
|
|
49
|
+
},
|
|
50
|
+
"allowScripts": {
|
|
51
|
+
"esbuild@0.21.5": true
|
|
52
|
+
}
|
|
53
|
+
}
|