@rebind.gg/mcp-server 0.2.1 → 0.2.3

package/README.md

@@ -55,7 +55,7 @@ Connects, takes a capture, and reports the display — the fastest way to catch
 | `type` | Type text into the focused element. |
 | `key` | Press a key or combo, e.g. `Enter`, `LCtrl+L`, `LAlt+Tab`. |
 | `scroll` | Scroll at the cursor. Positive scrolls down, negative up. `unit` is `wheel` (default, fine wheel clicks) or `page` (one PageDown or PageUp per unit, capped at 10). |
-| `read_page` | Extract the focused browser's current page as structured text (URL, forms, interactive elements, plain text) via an address-bar bookmarklet; the full dump, including cleaned HTML, lands in the clipboard. The result is read back through AppleScript (`URL of active tab of front window`), so the relay host must be macOS and the front browser must answer that query. Safari is detected but blocks the bookmarklet path. |
+| `read_page` | Extract the focused browser's current page as structured text (URL, forms, interactive elements, plain text) via an address-bar bookmarklet; the full dump, including cleaned HTML, lands in the clipboard. The result is read back through AppleScript (`URL of active tab of front window`), so the tool is registered only when the relay host is macOS, and the front browser must answer that query. Safari is detected but blocks the bookmarklet path. |
 | `meditate` | Research a problem page until a reasoning model has the data to solve it: fetches the URL directly, pulls the script bundles behind a JS shell so its API endpoints are visible, fetches those endpoints and assets, and reads the live page with vision. The browser steps (rendering a JS shell, same-origin fetches through the page, and the vision pass) need a macOS relay; elsewhere it reads pages over HTTP only. Returns a markdown dossier plus JSON `{error, problem, requirements, plan, submittable, form, live_captcha_hint, confidence, sources, assets, pending_fetch, notes, cost_usd}`. `error` is non-null when no problem could be identified or the page could not be read; partial data is still returned. Gated behind `REBIND_ALLOW_DELEGATION=1` (spends OpenRouter credits). See the pipeline below. |
 | `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`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebind.gg/mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MCP server exposing Rebind as computer-use tools: screenshot, verified click, type, key, scroll, and window control over the Remote Control protocol.",
   "type": "module",
   "bin": {

package/src/index.ts

@@ -98,8 +98,6 @@ function versusMessages(
 // asked to re-emit the whole growing dossier blows the model's output cap and
 // truncates the JSON; splitting keeps every response small and bounds cost.
 
-/** stop the loop once the model reports at least this much confidence */
-const MEDITATE_CONFIDENT = 0.8;
 /** max distinct pages read (problem page + follows) before the loop must stop */
 const MEDITATE_MAX_PAGES = 10;
 // Budgets sized for a 1M-token context, not a 4k one. These were tight enough
@@ -980,9 +978,10 @@ return { ok = true, proc = proc }
     },
     async ({ handle }) => {
       // handle-based activation can raise without focusing on macOS; fall back
-      // to app-name activation (App.Activate, macOS-only, no-op elsewhere via
-      // pcall). Decided relay-side: this process may run on a different
-      // machine than the relay, so process.platform is the wrong signal.
+      // to app-name activation (App.Activate, pcall-guarded because it raises
+      // where the relay has no App backend). Decided relay-side: this process
+      // may run on a different machine than the relay, so process.platform is
+      // the wrong signal.
       const r = (await client.luaExec(`
 local h = ${handle}
 Window.Activate(h)
@@ -1289,7 +1288,7 @@ return { ok = Window.IsActive(h), name = name }
       "meditate",
       {
         description:
-          "Research a problem page until enough data is collected to solve it. Fetches `url` directly (relay-side curl) and, when the response is a JS shell, pulls its script bundles so the API endpoints behind the page are visible; falls back to extracting the rendered page in a browser when a fetch cannot see the content. A reasoning model then iterates: identify the problem, fetch the URLs and API endpoints that close information gaps, download required assets, until it reaches confidence >= 0.8, has nothing left to fetch, or hits max_rounds. A final pass renders everything into a solving dossier. " +
+          "Research a problem page until enough data is collected to solve it. Fetches `url` directly (relay-side curl) and, when the response is a JS shell, pulls its script bundles so the API endpoints behind the page are visible; falls back to extracting the rendered page in a browser when a fetch cannot see the content. A reasoning model then iterates: identify the problem, fetch the URLs and API endpoints that close information gaps, download required assets, until it has nothing left to fetch or hits max_rounds. A final pass renders everything into a solving dossier. " +
           "Returns the dossier as markdown plus a JSON plan {error, problem, requirements, plan, confidence, sources, assets, pending_fetch, notes, cost_usd}. `error` is non-null (with the partial data still returned, never thrown) when no clear problem is identifiable or the browser could not be driven. Downloaded `assets` paths are on the RELAY host. " +
           "On a macOS relay it also drives the real browser (takes over keyboard/clipboard for the duration) to render a JS shell, fetch same-origin URLs through the page, and read the live captcha; elsewhere it reads pages over HTTP only. Spends OpenRouter credits. Refuses non-public URLs (loopback/private/link-local). Safari cannot be driven — pass `browser` to name another.",
         inputSchema: {

package/src/rebind.d.luau

@@ -35,6 +35,14 @@ export type ServerHandle = {
   Stop: (self: ServerHandle) -> (),
 }
 
+-- UDP: socket handle returned by Net.UDPListen. SendTo sends from the bound
+-- address and returns false when the send fails or the socket is stopped.
+export type UdpHandle = {
+  port: number,
+  SendTo: (self: UdpHandle, ip: string, port: number, bytes: string) -> boolean,
+  Stop: (self: UdpHandle) -> (),
+}
+
 -- WebSocket: server-side per-connection handle passed to OnConnect/OnMessage/OnClose.
 -- `id` is a monotonic identifier unique to this connection.
 export type WsClient = {
@@ -112,6 +120,19 @@ export type WindowPos = {
   height: number,
 }
 
+-- the input device a key, button, move or scroll came from. hooks get nil
+-- where the source cannot tell devices apart (Windows and macOS software mode)
+export type InputDevice = {
+  id: string,
+  name: string,
+  nickname: string?,
+  kind: "keyboard" | "mouse" | "other",
+  vid: string,
+  pid: string,
+  source: "vm" | "host",
+  exact: boolean,
+}
+
 export type MousePos = {
   x: number,
   y: number,
@@ -224,9 +245,10 @@ export type UiProxy = { [string]: any }
 
 -- bind config for table-style binding
 export type BindConfig = {
-  when: (() -> boolean)?,
-  action: (() -> boolean?)?,
-  release: (() -> ())?,
+  device: string?, -- nickname or id: the bind answers only to that device
+  when: ((device: InputDevice?) -> boolean)?,
+  action: ((device: InputDevice?) -> boolean?)?,
+  release: ((device: InputDevice?) -> ())?,
 }
 
 -- runtime identity table
@@ -300,6 +322,20 @@ declare System: {
 
 -- hid namespace
 
+-- a joypad state; every field is optional and defaults to neutral. buttons
+-- lists pressed buttons 1-32, hat is 0 (up) to 7 clockwise (nil = centered),
+-- x/y/z/rz are -1..1 (0 = center), slider and dial are 0..1.
+export type JoypadState = {
+  buttons: { number }?,
+  hat: number?,
+  x: number?,
+  y: number?,
+  z: number?,
+  rz: number?,
+  slider: number?,
+  dial: number?,
+}
+
 declare HID: {
   Down: (code: string) -> (),
   Up: (code: string) -> (),
@@ -319,6 +355,15 @@ declare HID: {
   Scroll: (amount: number) -> (),
   SetMouseMode: (mode: string) -> (),
   GetMouseMode: () -> string,
+  -- keyboard HID usage for a key name, or nil (media keys return nil). Down,
+  -- Up, Press and Combo also accept "usage:N" (decimal or 0x hex, 0x04-0xE7).
+  Usage: (name: string) -> number?,
+  -- set the whole joypad state (last write wins across scripts). Needs a
+  -- Rebind Link whose USB profile has a joypad; raises otherwise. Keyboard
+  -- and mouse calls raise the same way when the profile leaves them out.
+  Joypad: (state: JoypadState?) -> (),
+  -- back to neutral; the relay also does this when a script stops or errors
+  JoypadReset: () -> (),
 }
 
 -- input namespace
@@ -354,7 +399,7 @@ declare Bind: typeof(setmetatable({} :: {
   Toggle: (key: string, uiId: string) -> BindHandle,
   Remap: (from: string, to: string) -> BindHandle,
 }, {} :: {
-  __call: (self: any, key: string, config: (() -> boolean?) | BindConfig) -> BindHandle,
+  __call: (self: any, key: string, config: ((device: InputDevice?) -> boolean?) | BindConfig) -> BindHandle,
 }))
 
 -- timer namespace
@@ -374,7 +419,8 @@ declare Macro: {
   StopAll: () -> (),
   Record: (options: RecordOpts?) -> (),
   Finish: () -> { MacroAction },
-  -- the saved-macro format: modeline, actions table, top-level Macro.Play.
+  -- the saved-macro format: a `macro=true` modeline, then `return` of the
+  -- actions. require() of a saved macro returns the actions.
   ToScript: (macro: { MacroAction }, name: string) -> string,
   Stream: (macro: { MacroAction }) -> (),
   Abort: () -> (),
@@ -471,6 +517,8 @@ export type ImageMatch = {
   height: number,
 }
 
+-- pixel reads are limited by a screen:target or screen:none permission entry
+
 declare Screen: {
   GetPixelColor: (x: number?, y: number?) -> string,
   -- reads the published frame. regions up to 200k physical pixels answer on the
@@ -519,9 +567,12 @@ declare Window: {
 }
 
 -- app namespace: application-level control (Keyboard Maestro's Application
--- Control). names match case-insensitively by app display name. Front/IsRunning/
--- Activate are permission-free; Hide/Quit/IsHidden drive an AppleEvent and
--- prompt for macOS Automation permission on first use.
+-- Control). macOS: names match case-insensitively by app display name;
+-- Front/IsRunning/Activate are permission-free; Hide/Quit/IsHidden drive an
+-- AppleEvent and prompt for macOS Automation permission on first use.
+-- Windows: names are executable names (case-insensitive, ".exe" optional);
+-- Activate focuses a running app and does not launch one; Quit closes its
+-- windows; Hide/IsHidden raise. Linux: every call raises.
 
 export type AppInfo = {
   name: string,
@@ -538,7 +589,7 @@ declare App: {
   Quit: (name: string) -> (),
 }
 
--- net namespace
+-- net namespace (permission: net, or net:<host> for the client calls and WSConnect)
 
 declare Net: {
   Get: (url: string, headers: { [string]: string }?, options: HttpOptions?) -> HttpResponse,
@@ -551,6 +602,10 @@ declare Net: {
   Listen: (port: number, handler: (request: HttpRequest) -> HttpResponseSpec | string) -> ServerHandle,
   WSListen: (port: number, handlers: WsListenHandlers) -> WsServerHandle,
   WSConnect: (url: string, handlers: WsConnectHandlers) -> WsConnectHandle,
+  -- bind a UDP socket; handler receives each datagram's raw bytes and sender.
+  UDPListen: (bindIp: string, port: number, handler: (data: string, ip: string, port: number) -> ()) -> UdpHandle,
+  -- this computer's IPv4 address on its default route, or nil when there is none.
+  LocalIP: () -> string?,
 }
 
 -- pipe namespace
@@ -637,7 +692,7 @@ declare Dialog: {
   SaveFile: (options: DialogFileOptions?) -> string?,
 }
 
--- clipboard namespace
+-- clipboard namespace (limited by clipboard:read, clipboard:write, clipboard:none)
 
 declare Clipboard: {
   Get: () -> string?,
@@ -752,14 +807,14 @@ declare Registry: {
 -- declare function OnFocus(window: WindowInfo): ()
 -- declare function OnBlur(window: WindowInfo): ()
 -- declare function OnTick(dtMs: number): ()  -- ms elapsed since the previous OnTick (0 on the first)
--- declare function OnDown(key: string): boolean?
--- declare function OnUp(key: string, durationMs: number): boolean?
--- declare function OnMove(dx: number, dy: number): boolean?  -- return value only used with mouse_block=true (hardware mode only)
--- declare function OnScroll(delta: number): boolean?
+-- declare function OnDown(key: string, device: InputDevice?): boolean?
+-- declare function OnUp(key: string, durationMs: number, device: InputDevice?): boolean?
+-- declare function OnMove(dx: number, dy: number, device: InputDevice?): boolean?  -- return value only used with mouse_block=true (hardware mode only)
+-- declare function OnScroll(delta: number, device: InputDevice?): boolean?
 -- declare function OnScrollH(delta: number): boolean?
--- declare function OnInputDown(key: string): ()
--- declare function OnInputUp(key: string, durationMs: number): ()
--- declare function OnInputMove(dx: number, dy: number): ()
--- declare function OnInputScroll(delta: number): ()
+-- declare function OnInputDown(key: string, device: InputDevice?): ()
+-- declare function OnInputUp(key: string, durationMs: number, device: InputDevice?): ()
+-- declare function OnInputMove(dx: number, dy: number, device: InputDevice?): ()
+-- declare function OnInputScroll(delta: number, device: InputDevice?): ()
 -- declare function OnError(message: string): ()
 -- declare function OnReload(): ()