@luaward/mcp 0.2.6 → 0.2.8

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 CHANGED
@@ -1,19 +1,19 @@
1
1
  # @luaward/mcp
2
2
 
3
- Official **Luaward Hybrid Model Context Protocol (MCP)** stdio bridge for Claude Desktop, Cursor, Windsurf, Claude Code, and local AI coding assistants.
3
+ Official **Luaward Model Context Protocol (MCP)** stdio bridge for Claude Desktop, Cursor, Windsurf, Claude Code, Antigravity, and local AI coding assistants.
4
4
 
5
- `@luaward/mcp` connects your AI client to four cooperating layers:
5
+ `@luaward/mcp` connects your AI client to two focused layers:
6
6
 
7
- 1. **Luaward Cloud MCP (`https://luaward.com/mcp`)**: full Luau script protection, licensing, live in-game agent recipes (`run_and_collect`, `benchmark_session`, `cleanup_run`, `inspect_session_capabilities`, `ui_controls`, `gui_snapshot`, `remotes`, `search_scripts`, `scripts_read`, `inspect`, `exec`, `get_result`, `spy_start`, `player_state`), and workspace script deployment.
8
- 2. **Potassium Local MCP Bridge (`http://127.0.0.1:8225/mcp`)**: zero-touch auto-inject of the Luaward in-game agent whenever Potassium has an attached Roblox client, local `editor_tabs` sync (with `luaward_scratch.luau` tab reuse to avoid Potassium's unclosable dirty tabs), and local `file_path` loading for `run_and_collect`, `exec`, `create_script`, and `deploy_script`.
9
- 3. **Windows Computer Use & OS Lifecycle Automation**: Win32 `SendInput` (Roblox UI hover-wake `dx=1` and Raw Input `WM_INPUT` 3D camera rotation, ScanCode & Unicode keyboard), Windows UI Automation tree inspection (`desktop_ui_tree`), OS PNG screenshots (`desktop_screenshot` with `WindowFromPoint` occlusion detection + `PrintWindow` fallback), window management (`desktop_window` with `AttachThreadInput` foreground focus recovery), Roblox/Potassium process lifecycle & crash recovery (`desktop_launch`), and foreground-verified hybrid `#n` + Win32 clicking (`os_click`).
10
- 4. **Roblox Studio MCP Bridge (`%LOCALAPPDATA%\Roblox\mcp.bat`) & Visual Comparison**: bidirectional live-game to Roblox Studio workflows (`studio_mirror_remotes`, `studio_mirror_gui`, `studio_diff`, `studio_to_live`, `studio_publish`, `live_scripts_to_studio`) with automatic `studio_id` selection, `execute_luau` `datamodel_type` (`Edit` / `Client` / `Server`), automatic Cloud `exec` + `get_result` 24,000-char pagination reassembly, and desktop side-by-side PNG comparison (`compare_screens`).
7
+ 1. **Luaward Cloud MCP (`https://luaward.com/mcp`) + Local `file_path` loader**: full Luau script protection, licensing, live in-game agent recipes (`run_and_collect`, `benchmark_session`, `cleanup_run`, `inspect_session_capabilities`, `ui_controls`, `gui_snapshot`, `remotes`, `search_scripts`, `scripts_read`, `inspect`, `exec`, `get_result`, `spy_start`, `player_state`), workspace script deployment, and local `file_path` loading for `exec`, `run_and_collect`, `create_script`, and `deploy_script`.
8
+ 2. **Windows Computer Use & OS Automation (`src/windows.ts`)**: Win32 `SendInput` (`desktop_mouse` with Roblox UI hover-wake `dx=1` and Raw Input `WM_INPUT` 3D camera rotation, `desktop_keyboard` with ScanCode & Unicode input), Windows UI Automation tree inspection (`desktop_ui_tree`), OS PNG screenshots (`desktop_screenshot` with `WindowFromPoint` occlusion detection + `PrintWindow` fallback), side-by-side PNG window comparison (`compare_screens`), window management (`desktop_window` with `AttachThreadInput` foreground focus recovery), Roblox Player process lifecycle & rejoin recovery (`desktop_launch`), and point-occlusion-verified hybrid `#n` + Win32 clicking (`os_click`).
9
+
10
+ > Note: Third-party MCP bridges (Potassium Local MCP `http://127.0.0.1:8225/mcp` and Roblox Studio MCP `%LOCALAPPDATA%\Roblox\mcp.bat`) are intentionally excluded from `@luaward/mcp` as of v0.2.8. Connect your AI client directly to those MCP servers when needed.
11
11
 
12
12
  ---
13
13
 
14
14
  ## Quick Start
15
15
 
16
- ### Option 1: Hybrid Local `stdio` Bridge (`npx -y @luaward/mcp`) (Recommended for Windows + Potassium)
16
+ ### Option 1: Hybrid Local `stdio` Bridge (`npx -y @luaward/mcp`) (Recommended on Windows)
17
17
 
18
18
  Add `@luaward/mcp` to your `claude_desktop_config.json`, `.cursor/mcp.json`, or Claude Code MCP config:
19
19
 
@@ -35,7 +35,7 @@ If you have already signed in with `npx @luaward/cli login`, `@luaward/mcp` auto
35
35
 
36
36
  ### Option 2: Direct Remote HTTP (Cloud-Only)
37
37
 
38
- If your client only needs Luaward Cloud tools without local Potassium or Windows desktop tools:
38
+ If your client only needs Luaward Cloud tools without local `file_path` or Windows Computer Use tools:
39
39
 
40
40
  ```bash
41
41
  claude mcp add --transport http luaward https://luaward.com/mcp --header "Authorization: Bearer lwm_YOUR_TOKEN"
@@ -43,33 +43,24 @@ claude mcp add --transport http luaward https://luaward.com/mcp --header "Author
43
43
 
44
44
  ---
45
45
 
46
- ## Hybrid Local Tools Added in v0.2.0
46
+ ## Local Tools & Features
47
47
 
48
- ### Potassium Local Bridge & File Integration
49
- - **Zero-Touch Auto-Inject**: When any Cloud in-game tool returns `"no game is connected"`, `@luaward/mcp` checks `http://127.0.0.1:8225/mcp` (`list_clients`), fetches your workspace's `luaward://pair` bootstrapper, injects it via Potassium `execute_script`, waits for the session to connect, and retries your tool call automatically.
50
- - **`editor_tabs`**: Manage Potassium tabs and bridge them with Luaward Cloud (`list`, `read`, `open`, `write`, `activate`, `close`, `run_tab`, `sync_tab_to_cloud`, `open_cloud_script_in_tab`, `install_autoexec`). Reuses `luaward_scratch.luau` by default so you do not accumulate unclosable `dirty: true` tabs.
48
+ ### Layer 1: Luaward Cloud MCP + Local `file_path` Integration
51
49
  - **Local `file_path` parameter**: Pass `file_path: "./path/to/script.luau"` to `run_and_collect`, `exec`, `create_script`, or `deploy_script` to read large Luau files (up to 4 MB) directly from disk instead of pasting them inside JSON.
50
+ - **Automatic scope check**: On `initialize` and `tools/list`, `@luaward/mcp` inspects the active token's available tools and warns on `stderr` / `instructions` if `spy` or `scripts` scopes are missing.
52
51
 
53
- ### Windows Computer Use & OS Automation Tools
54
- - **`desktop_launch`**: `status`, `launch_potassium`, `launch_roblox` (`roblox://experiences/start?placeId=...&gameInstanceId=...` or direct `RobloxPlayerBeta.exe --app --deeplink`), `rejoin` (crash/hang recovery), and `kill_roblox`.
52
+ ### Layer 2: Windows Computer Use & OS Automation (8 Local Tools)
53
+ - **`desktop_launch`**: `status` (lists visible `RobloxPlayerBeta` and `RobloxStudioBeta` windows), `launch_roblox` (`roblox://experiences/start?placeId=...&gameInstanceId=...` or direct `RobloxPlayerBeta.exe --app --deeplink`), `rejoin` (crash/hang recovery: kills stale `RobloxPlayerBeta.exe`, waits briefly, and rejoins the last or specified `place_id`/`job_id`), and `kill_roblox`.
55
54
  - **`desktop_window`**: `list`, `focus`, `resize` (e.g. lock Roblox inner client viewport to `1280x720`), `minimize`, `maximize`, `restore`.
56
- - **`desktop_screenshot`**: Capture live Windows OS PNG screenshots of Roblox client area, Potassium window, or full screen directly (shows `CoreGui`, `gethui()`, and `Drawing` overlays).
57
- - **`desktop_ui_tree`**: Extract interactive UI Automation controls and screen coordinates from Potassium, Roblox Launcher, or any desktop window.
55
+ - **`desktop_screenshot`**: Capture live Windows OS PNG screenshots of Roblox client area, Studio window, or full screen directly (shows `CoreGui`, `gethui()`, and `Drawing` overlays; `method="auto"` uses `WindowFromPoint` occlusion checks with `PrintWindow` fallback).
56
+ - **`compare_screens`**: Captures screenshots of two windows (`target_a="roblox"` vs `target_b="studio"` by default, or `base64_a`/`base64_b`), computes overall and 4x4 grid pixel similarity metrics, and returns both PNG images side by side by default (`include_images=true`).
57
+ - **`desktop_ui_tree`**: Extract interactive UI Automation controls and screen coordinates from any Windows desktop window (`target`, `max_depth`, `max_elements`, `interactive_only`).
58
58
  - **`desktop_mouse`**: Dual-mode Win32 `SendInput`:
59
59
  - `mode="ui"` (Cursor Unlocked): `SetCursorPos` + `MOUSEEVENTF_ABSOLUTE` + 1px relative hover-wake (`dx=1, dy=0`) so Roblox fires `MouseEnter`/`MouseMovement` before clicking.
60
60
  - `mode="camera"` / `action="camera_rotate"` (Cursor Locked / First-Person / Shift-Lock): pure relative `MOUSEEVENTF_MOVE` (`dx`, `dy`) for Windows Raw Input (`WM_INPUT`).
61
61
  - Also supports `drag_and_drop` and `scroll`.
62
62
  - **`desktop_keyboard`**: Win32 `SendInput` with hardware `KEYEVENTF_SCANCODE` (`press`, `key_down`, `key_up`, `hotkey`) for DirectInput/Roblox keybinds and `KEYEVENTF_UNICODE` (`type`) for arbitrary text.
63
- - **`os_click`**: Hybrid tool that resolves `#n` (from `gui_snapshot`) or a `GuiObject` path inside Roblox, combines `AbsolutePosition` + `GuiService:GetGuiInset()` + Win32 `GetClientRect`/`ClientToScreen` scaling, forces Roblox to foreground with `AttachThreadInput` + occlusion verification (`WindowFromPoint`) before clicking, and verifies `GetMouseLocation()` + `gui_snapshot(diff_from="last")` when `verify=true`.
64
-
65
- ### Roblox Studio Bridge & Visual Comparison (v0.2.6)
66
- - **`studio_mirror_remotes`**: BFS + network-first scan of live `RemoteEvent`, `RemoteFunction`, and `UnreliableRemoteEvent` instances (`kind="network"` by default; explicit `"bindable"` / `"all"` supported; deprioritizes bulky `Model`/`Assets` folders) and reconstructs the folder/remote tree in Roblox Studio (`Edit`, `Client`, or `Server` DataModel). Automatically reassembles multi-page Cloud `exec` + `get_result` outputs.
67
- - **`studio_mirror_gui`**: Captures live `PlayerGui` (or explicit `target` path / `#n` handle, plus optional `CoreGui`) hierarchy with properties (`Position`, `Size`, `AnchorPoint`, `Visible`, `Text`, `UICorner`, colors) across full `get_result` pages and rebuilds the GUI tree inside Studio `StarterGui`.
68
- - **`studio_diff`**: Compares live game instances against Roblox Studio (`scope`: `all`, `scripts`, `remotes`, `gui`) with full Cloud pagination reassembly and strict error reporting.
69
- - **`studio_to_live`**: Reads a `Script`, `LocalScript`, or `ModuleScript` from Roblox Studio (`studio_path` or current `Selection`) and runs it in the live game via `run_and_collect` (mapping `wait_seconds` to `settle_ms` and forwarding `timeout_ms`) or `exec`.
70
- - **`studio_publish`**: Reads a script from Roblox Studio (`studio_path` or `Selection`) and creates (`create_script`) or deploys/protects (`deploy_script`) it on Luaward Cloud.
71
- - **`live_scripts_to_studio`**: Decompiles `LocalScript`/`ModuleScript` sources from the live connected game across paginated Cloud `exec` outputs and imports them (with `.Disabled = true` by default) into Studio `ServerStorage.<name>` or any dotted Studio service path such as `ReplicatedStorage.Debug.LiveScripts`.
72
- - **`compare_screens`**: Captures screenshots of two windows (`target_a="roblox"` vs `target_b="studio"` by default, or `base64_a`/`base64_b`), computes overall and 4x4 grid pixel similarity metrics, and returns both PNG images side by side by default (`include_images=true`).
63
+ - **`os_click`**: Hybrid tool that resolves `#n` (from `gui_snapshot`) or a `GuiObject` path inside Roblox, combines `AbsolutePosition` + `GuiService:GetGuiInset()` + Win32 `GetClientRect`/`ClientToScreen` scaling, forces Roblox to foreground with `AttachThreadInput` and verifies exact `(screenX, screenY)` top-of-z-order visibility (`IsWindowTopAtPoint`) before clicking, and verifies `GetMouseLocation()` + `gui_snapshot(diff_from="last")` when `verify=true`.
73
64
 
74
65
  ---
75
66
 
@@ -79,13 +70,9 @@ claude mcp add --transport http luaward https://luaward.com/mcp --header "Author
79
70
  |---|---|---|
80
71
  | `--token <lwm_...>` / `LUAWARD_MCP_TOKEN` | Personal MCP / IDE token created on `/dashboard/ai` | Falls back to `LUAWARD_TOKEN` or `~/.config/luaward/credentials.json` |
81
72
  | `--url <https://...>` / `LUAWARD_MCP_URL` | Target Luaward Cloud MCP HTTP endpoint | `https://luaward.com/mcp` |
82
- | `--potassium-url <http://...>` / `POTASSIUM_MCP_URL` | Local Potassium Streamable HTTP MCP endpoint | `http://127.0.0.1:8225/mcp` |
83
- | `--potassium-token <token>` / `POTASSIUM_MCP_TOKEN` | Bearer token for Potassium local MCP | Auto-discovered from `%APPDATA%/Potassium` when present |
84
- | `--pair-command <luau>` / `LUAWARD_PAIR_COMMAND` | Override auto-inject one-liner | Auto-fetched from `luaward://pair` resource |
85
- | `--no-auto-inject` / `LUAWARD_AUTO_INJECT=0` | Disable zero-touch Potassium auto-inject | Enabled (`true`) |
86
- | `POTASSIUM_AUTOEXEC_DIR` | Custom Potassium `autoexec` / `AUTO EXECUTE` folder for `install_autoexec` | Auto-detected |
87
- | `ROBLOX_PLAYER_PATH` / `POTASSIUM_PATH` | Optional explicit paths to `RobloxPlayerBeta.exe` or `Potassium.exe` | Auto-detected |
88
- | `--version`, `-v` | Print package version (`@luaward/mcp/0.2.6`) | - |
73
+ | `LUAWARD_API_URL` | Optional base API URL override (derives `<api>/mcp`) | - |
74
+ | `ROBLOX_PLAYER_PATH` | Optional explicit path to `RobloxPlayerBeta.exe` | Auto-detected |
75
+ | `--version`, `-v` | Print package version (`@luaward/mcp/0.2.8`) | - |
89
76
  | `--help`, `-h` | Show usage help | - |
90
77
 
91
78
  ---