@luaward/mcp 0.1.0 → 0.2.0

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,24 +1,20 @@
1
1
  # @luaward/mcp
2
2
 
3
- Official **Luaward Model Context Protocol (MCP)** stdio bridge for Claude Desktop, Cursor, Windsurf, and local AI coding assistants.
3
+ Official **Luaward Hybrid Model Context Protocol (MCP)** stdio bridge for Claude Desktop, Cursor, Windsurf, Claude Code, and local AI coding assistants.
4
4
 
5
- Luaward provides a remote Streamable HTTP MCP server at `https://luaward.com/mcp`. For MCP clients that prefer or require a local `stdio` command (`npx -y @luaward/mcp`), this package forwards JSON-RPC 2.0 messages over HTTPS using your Luaward MCP token (`lwm_...`) or existing `@luaward/cli` login session.
5
+ `@luaward/mcp` connects your AI client to three cooperating layers:
6
+
7
+ 1. **Luaward Cloud MCP (`https://luaward.com/mcp`)**: full Luau script protection, licensing, live in-game agent recipes (`gui_snapshot`, `remotes`, `search_scripts`, `scripts_read`, `inspect`, `exec`, `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 `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`), window management (`desktop_window`), Roblox/Potassium process lifecycle & crash recovery (`desktop_launch`), and hybrid in-game `#n` + Win32 clicking (`os_click`).
6
10
 
7
11
  ---
8
12
 
9
13
  ## Quick Start
10
14
 
11
- ### Option 1: Direct Remote HTTP (Claude Code, Claude.ai, ChatGPT, Cursor)
12
-
13
- If your client supports remote HTTP MCP servers, you can connect directly to `https://luaward.com/mcp`:
14
-
15
- ```bash
16
- claude mcp add --transport http luaward https://luaward.com/mcp --header "Authorization: Bearer lwm_YOUR_TOKEN"
17
- ```
18
-
19
- ### Option 2: Local `stdio` Bridge (`npx -y @luaward/mcp`)
15
+ ### Option 1: Hybrid Local `stdio` Bridge (`npx -y @luaward/mcp`) (Recommended for Windows + Potassium)
20
16
 
21
- Add `@luaward/mcp` to your `claude_desktop_config.json` or `.cursor/mcp.json`:
17
+ Add `@luaward/mcp` to your `claude_desktop_config.json`, `.cursor/mcp.json`, or Claude Code MCP config:
22
18
 
23
19
  ```json
24
20
  {
@@ -36,6 +32,35 @@ Add `@luaward/mcp` to your `claude_desktop_config.json` or `.cursor/mcp.json`:
36
32
 
37
33
  If you have already signed in with `npx @luaward/cli login`, `@luaward/mcp` automatically reads your saved token from `~/.config/luaward/credentials.json` when `LUAWARD_MCP_TOKEN` is omitted.
38
34
 
35
+ ### Option 2: Direct Remote HTTP (Cloud-Only)
36
+
37
+ If your client only needs Luaward Cloud tools without local Potassium or Windows desktop tools:
38
+
39
+ ```bash
40
+ claude mcp add --transport http luaward https://luaward.com/mcp --header "Authorization: Bearer lwm_YOUR_TOKEN"
41
+ ```
42
+
43
+ ---
44
+
45
+ ## Hybrid Local Tools Added in v0.2.0
46
+
47
+ ### Potassium Local Bridge & File Integration
48
+ - **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.
49
+ - **`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.
50
+ - **Local `file_path` parameter**: Pass `file_path: "./path/to/script.luau"` to `exec`, `create_script`, or `deploy_script` to read large Luau files directly from disk instead of pasting them inside JSON.
51
+
52
+ ### Windows Computer Use & OS Automation Tools
53
+ - **`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`.
54
+ - **`desktop_window`**: `list`, `focus`, `resize` (e.g. lock Roblox inner client viewport to `1280x720`), `minimize`, `maximize`, `restore`.
55
+ - **`desktop_screenshot`**: Capture live Windows OS PNG screenshots of Roblox client area, Potassium window, or full screen directly (shows `CoreGui`, `gethui()`, and `Drawing` overlays).
56
+ - **`desktop_ui_tree`**: Extract interactive UI Automation controls and screen coordinates from Potassium, Roblox Launcher, or any desktop window.
57
+ - **`desktop_mouse`**: Dual-mode Win32 `SendInput`:
58
+ - `mode="ui"` (Cursor Unlocked): `SetCursorPos` + `MOUSEEVENTF_ABSOLUTE` + 1px relative hover-wake (`dx=1, dy=0`) so Roblox fires `MouseEnter`/`MouseMovement` before clicking.
59
+ - `mode="camera"` / `action="camera_rotate"` (Cursor Locked / First-Person / Shift-Lock): pure relative `MOUSEEVENTF_MOVE` (`dx`, `dy`) for Windows Raw Input (`WM_INPUT`).
60
+ - Also supports `drag_and_drop` and `scroll`.
61
+ - **`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.
62
+ - **`os_click`**: Hybrid tool that resolves `#n` (from `gui_snapshot`) or a `GuiObject` path inside Roblox, combines `AbsolutePosition` + `GuiService:GetGuiInset()` + Win32 `GetClientRect`/`ClientToScreen` scaling, and sends a real OS Win32 click at the exact center.
63
+
39
64
  ---
40
65
 
41
66
  ## CLI Options & Environment Variables
@@ -43,8 +68,14 @@ If you have already signed in with `npx @luaward/cli login`, `@luaward/mcp` auto
43
68
  | Flag / Variable | Description | Default |
44
69
  |---|---|---|
45
70
  | `--token <lwm_...>` / `LUAWARD_MCP_TOKEN` | Personal MCP / IDE token created on `/dashboard/ai` | Falls back to `LUAWARD_TOKEN` or `~/.config/luaward/credentials.json` |
46
- | `--url <https://...>` / `LUAWARD_MCP_URL` | Target Luaward MCP HTTP endpoint | `https://luaward.com/mcp` |
47
- | `--version`, `-v` | Print package version (`@luaward/mcp/0.1.0`) | - |
71
+ | `--url <https://...>` / `LUAWARD_MCP_URL` | Target Luaward Cloud MCP HTTP endpoint | `https://luaward.com/mcp` |
72
+ | `--potassium-url <http://...>` / `POTASSIUM_MCP_URL` | Local Potassium Streamable HTTP MCP endpoint | `http://127.0.0.1:8225/mcp` |
73
+ | `--potassium-token <token>` / `POTASSIUM_MCP_TOKEN` | Bearer token for Potassium local MCP | Auto-discovered from `%APPDATA%/Potassium` when present |
74
+ | `--pair-command <luau>` / `LUAWARD_PAIR_COMMAND` | Override auto-inject one-liner | Auto-fetched from `luaward://pair` resource |
75
+ | `--no-auto-inject` / `LUAWARD_AUTO_INJECT=0` | Disable zero-touch Potassium auto-inject | Enabled (`true`) |
76
+ | `POTASSIUM_AUTOEXEC_DIR` | Custom Potassium `autoexec` / `AUTO EXECUTE` folder for `install_autoexec` | Auto-detected |
77
+ | `ROBLOX_PLAYER_PATH` / `POTASSIUM_PATH` | Optional explicit paths to `RobloxPlayerBeta.exe` or `Potassium.exe` | Auto-detected |
78
+ | `--version`, `-v` | Print package version (`@luaward/mcp/0.2.0`) | - |
48
79
  | `--help`, `-h` | Show usage help | - |
49
80
 
50
81
  ---