@rebind.gg/mcp-server 0.1.5 → 0.1.6

package/README.md

@@ -1,19 +1,17 @@
 # @rebind.gg/mcp-server
 
-Stdio MCP server that exposes Rebind as computer-use tools: `screenshot`,
-`screenshot_window`, `zoom`, `click` (verified), `move_mouse`, `type`, `key`,
-`scroll`, `run_lua`, `wait`, window control, and `calibrate`. Wraps
-`@rebind.gg/client-ts`; requires the **Rebind** app
-(https://rebind.gg/download) running its Remote Access relay — `remote.luau`
-(recommended) or `remote_access.lua` (protocol >= 1.1.0). The `click` tool clicks via `hid.press`, which is
-coroutine-only; use `remote.luau` or a current `remote_access.lua` (older copies
-called it outside a coroutine, so clicks silently failed).
+Stdio MCP server that turns [Rebind](https://rebind.gg) into a computer-use toolkit: screenshots, verified clicks, keyboard input, window control, and direct Luau scripting on the connected machine — driven over real HID, not synthetic OS events.
+
+**Requirements**
+
+- [Bun](https://bun.sh) >= 1.1 (the server runs via `bunx`)
+- The [Rebind app](https://rebind.gg/download) running its Remote Access relay: `remote.luau` (recommended) or `remote_access.lua` (protocol >= 1.1.0)
+
+> Older copies of `remote_access.lua` called `hid.press` outside a coroutine, so clicks silently failed. Use `remote.luau` or a current `remote_access.lua`.
 
 ## Install
 
-One command writes the correct config for whichever clients you name — Claude
-Code, Cursor, Codex, OpenCode, VS Code, Windsurf, Zed, and more — each in its
-native format, via [`add-mcp`](https://github.com/neondatabase/add-mcp):
+One command writes the correct config for whichever clients you name — Claude Code, Cursor, Codex, OpenCode, VS Code, Windsurf, Zed, and more — via [`add-mcp`](https://github.com/neondatabase/add-mcp):
 
 ```sh
 npx add-mcp "bunx @rebind.gg/mcp-server" --name rebind \
@@ -21,13 +19,9 @@ npx add-mcp "bunx @rebind.gg/mcp-server" --name rebind \
   -g -a claude-code -a cursor -a codex -a opencode
 ```
 
-Drop `-a <agent>` for the clients you want, or pass `--all`. `-g` installs
-globally; omit it for project-local config. Restart the client afterward.
-
-Requires **Bun** (the server runs via `bunx`) and the **Rebind** app
-(https://rebind.gg/download) running its Remote Access relay.
+Drop `-a <agent>` for the clients you want, or pass `--all`. `-g` installs globally; omit it for project-local config. Restart the client afterward.
 
-## Configure manually
+### Manual configuration
 
 Any MCP client takes the stdio block directly:
 
@@ -43,33 +37,48 @@ Any MCP client takes the stdio block directly:
 }
 ```
 
-`REBIND_TOKEN` is required when the server has an auth token set (the **Auth
-token** panel field on `remote.luau`, or `AUTH_TOKEN` on `remote_access.lua`).
-
-Check the relay is reachable before wiring it up:
+### Verify the relay is reachable
 
 ```sh
 bunx @rebind.gg/mcp-server --selftest
 ```
 
-Set `REBIND_AGENT_LOG=<path>` to append one JSONL line per tool call
-(`{ts, tool, ok, latency_ms, note}`) — no screenshot bytes, no user content.
-Off unless set.
-
-`click` and `move_mouse` reach an absolute screen point by reading the real OS
-cursor and sending relative HID deltas (which map 1:1 to pixels), correcting
-against the true cursor until it lands. This sidesteps the relay's own absolute
-move, whose delta is computed from a cached cursor position that goes stale and
-flings the pointer to a screen edge. A mouse scale probe runs on the first
-click/move_mouse; if pointer ballistics are detected (enhance pointer precision,
-DPI mismatch) the probe reports it, since acceleration would break the 1:1
-assumption.
-
-Tool calls are serialized through a single queue: there is one physical cursor
-and keyboard, so parallel tool calls from the model (e.g. two `move_mouse` in
-one turn) run one after another instead of interleaving HID input. All results
-are reported in the coordinate space of the last screenshot, the same space the
-model emits.
+Connects, takes a capture, and reports the display — the fastest way to catch the #1 first-run failure (relay not loaded).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `screenshot` | Capture a display (cursor marked with a crosshair). All coordinates the model emits are pixels in the most recent screenshot. |
+| `screenshot_window` | Capture one window by title substring (or the active window) — smaller, cheaper, monitor-proof. |
+| `zoom` | Re-capture a region of the last screenshot at native resolution, for small text. Read-only. |
+| `click` | Move to a point and click (`left`/`right`/`middle`, optional double). Landing position is verified and corrected before pressing. |
+| `move_mouse` | Move without clicking, with the same verification. |
+| `type` | Type text into the focused element. |
+| `key` | Press a key or combo, e.g. `Enter`, `LCtrl+L`, `LAlt+Tab`. |
+| `scroll` | Scroll the wheel at the cursor (positive = up). |
+| `run_lua` | Run a Luau script on the connected machine and return its `return` value as JSON — the fast path for any deterministic sequence (launch apps, place windows, shell commands, pixel search). |
+| `lua_docs` | Full Luau SDK type definitions for `run_lua`. |
+| `list_displays` / `list_windows` / `focus_window` / `active_window` | Display and window enumeration and control. |
+| `get_cursor` / `wait` / `calibrate` | Cursor readback, pauses, and the mouse scale probe. |
+
+## Configuration
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `REBIND_URL` | `ws://127.0.0.1:19561` | Relay WebSocket URL. |
+| `REBIND_TOKEN` | — | Required when the relay has an auth token set (the **Auth token** panel field on `remote.luau`, or `AUTH_TOKEN` on `remote_access.lua`). |
+| `REBIND_AGENT_LOG` | off | Path to append one JSONL line per tool call (`{ts, tool, ok, latency_ms, note}`). No screenshot bytes, no user content. |
+
+## How it works
+
+**Verified clicks.** `click` and `move_mouse` reach an absolute screen point by reading the real OS cursor and sending relative HID deltas (which map 1:1 to pixels), correcting against the true cursor until it lands. This sidesteps the relay's own absolute move, whose delta comes from a cached cursor position that goes stale and flings the pointer to a screen edge.
+
+**Calibration.** A mouse scale probe runs on the first `click`/`move_mouse`. If pointer ballistics are detected (enhance pointer precision, DPI mismatch), the probe reports it, since acceleration would break the 1:1 assumption. Re-run it any time with `calibrate`.
+
+**One queue.** There is one physical cursor and keyboard, so tool calls are serialized: parallel calls from the model run one after another instead of interleaving HID input.
+
+**One coordinate space.** All results are reported in the pixel space of the last screenshot — the same space the model emits — so no rescaling math ever falls on the model.
 
 ## Develop
 
@@ -77,3 +86,7 @@ model emits.
 bun test packages/mcp-server/tests/
 bun run --cwd packages/mcp-server typecheck
 ```
+
+## License
+
+MIT © [US Input Company](https://usinput.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebind.gg/mcp-server",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "MCP server exposing Rebind as computer-use tools: screenshot, verified click, type, key, scroll, and window control over the Remote Access protocol.",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@rebind.gg/client-ts": "0.2.0",
+    "@rebind.gg/client-ts": "0.2.1",
     "sharp": "^0.34.2",
     "zod": "^3.25.0"
   },

package/src/index.ts

@@ -53,7 +53,7 @@ async function main() {
 
   const session = new Session(client);
 
-  const server = new McpServer({ name: "rebind", version: "0.1.5" });
+  const server = new McpServer({ name: "rebind", version: "0.1.6" });
 
   // REBIND_AGENT_LOG=<path>: opt-in telemetry — one JSONL line per tool call
   // ({ts, tool, ok, latency_ms, note}). No screenshot bytes, no user content.