@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 +20 -33
- package/dist/cli.js +1682 -4540
- package/dist/cli.js.map +4 -4
- package/dist/index.js +1268 -4099
- package/dist/index.js.map +4 -4
- package/package.json +5 -3
- package/server.json +28 -0
package/README.md
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
# @luaward/mcp
|
|
2
2
|
|
|
3
|
-
Official **Luaward
|
|
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
|
|
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`),
|
|
8
|
-
2. **
|
|
9
|
-
|
|
10
|
-
|
|
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
|
|
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
|
|
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
|
-
##
|
|
46
|
+
## Local Tools & Features
|
|
47
47
|
|
|
48
|
-
###
|
|
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
|
|
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,
|
|
57
|
-
- **`
|
|
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`
|
|
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
|
-
|
|
|
83
|
-
|
|
|
84
|
-
| `--
|
|
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
|
---
|