@luaward/mcp 0.0.0-stage → 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Luaward
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,89 @@
1
- # Temporary Holding Version
1
+ # @luaward/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Official **Luaward Hybrid Model Context Protocol (MCP)** stdio bridge for Claude Desktop, Cursor, Windsurf, Claude Code, and local AI coding assistants.
4
+
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`).
10
+
11
+ ---
12
+
13
+ ## Quick Start
14
+
15
+ ### Option 1: Hybrid Local `stdio` Bridge (`npx -y @luaward/mcp`) (Recommended for Windows + Potassium)
16
+
17
+ Add `@luaward/mcp` to your `claude_desktop_config.json`, `.cursor/mcp.json`, or Claude Code MCP config:
18
+
19
+ ```json
20
+ {
21
+ "mcpServers": {
22
+ "luaward": {
23
+ "command": "npx",
24
+ "args": ["-y", "@luaward/mcp"],
25
+ "env": {
26
+ "LUAWARD_MCP_TOKEN": "lwm_YOUR_48_HEX_TOKEN"
27
+ }
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
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.
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
+
64
+ ---
65
+
66
+ ## CLI Options & Environment Variables
67
+
68
+ | Flag / Variable | Description | Default |
69
+ |---|---|---|
70
+ | `--token <lwm_...>` / `LUAWARD_MCP_TOKEN` | Personal MCP / IDE token created on `/dashboard/ai` | Falls back to `LUAWARD_TOKEN` or `~/.config/luaward/credentials.json` |
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`) | - |
79
+ | `--help`, `-h` | Show usage help | - |
80
+
81
+ ---
82
+
83
+ ## Links
84
+
85
+ - **MCP & AI Documentation:** [luaward.com/docs/ai-tools/workspace-mcp](https://luaward.com/docs/ai-tools/workspace-mcp)
86
+ - **CLI (`@luaward/cli`):** [npmjs.com/package/@luaward/cli](https://www.npmjs.com/package/@luaward/cli)
87
+ - **JS/TS SDK (`@luaward/sdk`):** [npmjs.com/package/@luaward/sdk](https://www.npmjs.com/package/@luaward/sdk)
88
+ - **Python SDK (`luaward`):** [pypi.org/project/luaward](https://pypi.org/project/luaward/)
89
+ - **Support:** [luaward.com/support](https://luaward.com/support)