hand-mcp 0.1.1 → 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,89 +1,86 @@
1
1
  <h1 align="center">hand-mcp</h1>
2
- <p align="center"><strong>hand is one MCP server for headless browser testing and Windows desktop computer use.</strong></p>
2
+ <p align="center"><strong>The MCP server that can see and touch both the browser and Windows.</strong></p>
3
3
 
4
- ## Install
4
+ <p align="center">
5
+ <a href="https://www.npmjs.com/package/hand-mcp"><img src="https://img.shields.io/npm/v/hand-mcp" alt="npm version"></a>
6
+ <img src="https://img.shields.io/badge/platform-windows%20x64-blue" alt="platform">
7
+ <img src="https://img.shields.io/badge/tools-40-brightgreen" alt="40 tools">
8
+ <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT">
9
+ </p>
5
10
 
6
- Run it without installing:
11
+ ## Install
7
12
 
8
13
  ```powershell
9
14
  npx hand-mcp
10
15
  ```
11
16
 
12
- Or install it into a project:
13
-
14
- ```powershell
15
- npm i hand-mcp
16
- ```
17
-
18
- The binary ships inside the package: about 5 MB packed, 14 MB unpacked. No install script downloads anything and no compiler is needed. Pin an exact version with `npx hand-mcp@0.1.1`.
17
+ The binary ships inside the package: about 6.4 MB packed, 19.4 MB unpacked. No install script downloads anything and no compiler is needed. Pin an exact version (`npx hand-mcp@<version>`) when you need reproducibility.
19
18
 
20
- A global install is not supported: the server belongs in the client's own process tree, not on `PATH`. The package's `preinstall` guard exits 1 with `hand-mcp: global install refused — use npx hand-mcp@0.1.1`. npm 12 blocks install scripts by default, so that guard only runs where scripts are allowed; `npx hand-mcp` needs no global install in any case.
19
+ A global install is not supported on purpose: the server belongs in the client's own process tree, not on `PATH`. `npx hand-mcp` needs none.
21
20
 
22
21
  ### Or let your AI install it
23
22
 
24
23
  ```text
25
24
  Install nathwn12/hand (hand-mcp) with `npx hand-mcp`, then prove it works.
26
- 1. Run: `npx hand-mcp`
27
- 2. First run: starts an MCP server on stdio and waits for a client on stdin; nothing else must exist.
28
- 3. Done when: `npx hand-mcp --version` exits 0 and prints `hand 0.1.1 (<commit>; release)`.
25
+ 1. Run: `npx hand-mcp --version`
26
+ 2. Done when: exit 0 and a line `hand <version> (<commit>; release)`.
27
+ 3. Wire it: add the server below to the client config and restart.
29
28
  If it fails, stop and paste the full output; do not improvise a fix.
30
29
  ```
31
30
 
32
31
  ### Wire it yourself
33
32
 
34
- Point your MCP client at the launcher. The client spawns it and speaks newline-delimited JSON-RPC 2.0 on stdio:
35
-
36
33
  ```jsonc
37
34
  {
38
35
  "mcp": {
39
36
  "servers": {
40
- "hand-mcp": {
37
+ "hand": {
41
38
  "type": "local",
42
- "command": ["npx", "hand-mcp"]
39
+ "command": ["cmd", "/c", "npx", "-y", "hand-mcp"]
43
40
  }
44
41
  }
45
42
  }
46
43
  }
47
44
  ```
48
45
 
49
- ## Use it
50
-
51
- `hand-mcp` with no argument starts the MCP session. The launcher forwards argv, stdio and the exit code to the bundled `hand.exe`, so `hand-mcp --version` prints the version, the commit and the build profile (`hand 0.1.1 (<commit>; release)`) and exits without starting a session.
52
-
53
- The binary's own subcommands are `mcp` (the default), `doctor` and `--version`.
46
+ The client spawns npx, which runs the bundled binary and speaks newline-delimited JSON-RPC 2.0 on stdio. stdout carries protocol frames only.
54
47
 
55
- One connection carries 33 tools:
48
+ ## What it does
56
49
 
57
- - Browser, 25: `browser_navigate`, `browser_snapshot`, then a tool that acts on an `@eN` ref, plus evaluate, console, network, fetch text, layout assertions, screenshots, storage and raw CDP (`browser_cdp`).
58
- - Desktop, 7: `desktop_screenshot` through `desktop_elements`, over Win32 and UI Automation, reading or acting only on an explicitly selected window.
59
- - `browser_context`: named contexts, so cookies and storage stay apart.
50
+ One connection, two domains, 40 tools:
60
51
 
61
- The 32 tools the two engines already served keep their `inputSchema`, `outputSchema`, `description` and `annotations`; only the name gained a prefix.
52
+ - **Browser, 33**: `browser_navigate`, `browser_snapshot` (stable `@eN` refs), click with right/middle/double, type, hover, select, key, upload, wheel, drag, ordered form batches, downloads, evaluate, console, network interception (route, mock, abort, offline), fetch text, wait, layout and layout assertions, DOM/text/URL/ax assertions, viewport audits (six sizes, WCAG contrast evidence), visual regression, screenshots (whole page, one element, or a clip; png, jpeg, webp), storage, tabs, viewport, dialog, history, targets, named contexts, opt-in traces (HAR, counted redaction), raw CDP, close.
53
+ - **Desktop, 7**: `desktop_screenshot`, `desktop_diff`, `desktop_list_windows`, `desktop_window`, `desktop_do`, `desktop_cursor`, `desktop_elements`, over Win32 and UI Automation.
62
54
 
63
- Two properties hold across both catalogs. A desktop action is posted to the chosen window: no global mouse, no physical pointer movement, no window activation, no clipboard write. A refusal names its reason, so a cancelled or expired call answers `outcome: unknown` with `retry: unsafe` instead of implying the work stopped.
55
+ A desktop action posts to the chosen window: no global mouse, no physical pointer movement, no window activation, no clipboard write. A refusal names its reason: a cancelled or expired call answers `outcome: unknown` with `retry: unsafe` instead of implying the work stopped. A healthy run writes nothing to the terminal.
64
56
 
65
57
  ## Configure it
66
58
 
67
- No flag serves MCP: `hand-mcp` with no argument is the session. One environment variable is the only switch.
68
-
69
59
  | Variable | Default | Effect |
70
60
  |---|---|---|
71
- | `GLADIUS_CDP_URL` | unset | Attach to a browser you already run instead of launching one. hand does not launch, kill or sweep that engine, and closes only pages it created. |
61
+ | `GLADIUS_CDP_URL` | unset | Attach to a browser you already run instead of launching one. hand does not launch, kill or sweep it, and closes only pages it created. |
62
+ | `HAND_DEBUG` | unset | Print engine diagnostics to stderr. Off by default. |
72
63
 
73
- With no override, the first browser call provisions the pinned `chrome-headless-shell` 155.0.8059.84 into a per-user cache and reuses it after that.
64
+ The first browser call provisions the pinned `chrome-headless-shell` into a per-user cache and reuses it after that.
74
65
 
75
66
  ## Requirements
76
67
 
77
- - Windows 10 or 11, x64. The manifest declares `os: win32` and `cpu: x64`, and the desktop domain is Win32 and UI Automation; there is no other platform.
78
- - Node 22.14.0 or newer, to run the launcher. Nothing else is needed at install time.
68
+ - Windows 10 or 11, x64. The manifest declares `os: win32` and `cpu: x64`.
69
+ - Node 22.14.0 or newer, to run the launcher.
79
70
  - An MCP client that speaks stdio.
80
71
 
81
72
  ## Status
82
73
 
83
- **Experimental** — pre-release; interfaces may change.
74
+ **Experimental**: pre-release; interfaces may change.
84
75
 
85
76
  ## Links
86
77
 
78
+ - [Repository](https://github.com/nathwn12/hand)
87
79
  - [Issues](https://github.com/nathwn12/hand/issues)
88
80
  - [Releases](https://github.com/nathwn12/hand/releases)
89
81
  - [MIT licence](https://opensource.org/license/mit)
82
+
83
+ <p align="center">
84
+ <img src="signature.svg" width="120" alt="nathwn12 signature" />
85
+ <br />Built by nathwn12
86
+ </p>
package/hand.exe CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hand-mcp",
3
- "version": "0.1.1",
3
+ "version": "0.2.0",
4
4
  "description": "hand-mcp: one MCP server for headless browser testing (CDP) and Windows desktop computer use",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -23,12 +23,13 @@
23
23
  },
24
24
  "scripts": {
25
25
  "prepack": "node ./stage.mjs",
26
- "preinstall": "node -e \"if(process.env.npm_config_global==='true'){console.error('hand-mcp: global install refused — use npx hand-mcp@0.1.1');process.exit(1)}\""
26
+ "preinstall": "node -e \"if(process.env.npm_config_global==='true'){console.error('hand-mcp: global install refused — use npx hand-mcp@0.2.0');process.exit(1)}\""
27
27
  },
28
28
  "files": [
29
29
  "bin/",
30
30
  "hand.exe",
31
31
  "LICENSE",
32
- "README.md"
32
+ "README.md",
33
+ "signature.svg"
33
34
  ]
34
35
  }
package/signature.svg ADDED
@@ -0,0 +1,7 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
2
+ <style>html,body{margin:0;padding:0}svg{display:block;width:100vw;height:100vh}</style>
3
+ <!-- Direction A: "cursor-n" — rounded lowercase n + terminal block cursor, near-black ground -->
4
+ <rect x="16" y="16" width="480" height="480" rx="112" fill="#0B0F14"/>
5
+ <path d="M136 384 L136 264 C136 196 180 164 234 164 C288 164 328 198 328 264 L328 384 L264 384 L264 270 C264 242 250 230 234 230 C218 230 200 242 200 270 L200 384 Z" fill="#EEF3F6"/>
6
+ <rect x="352" y="312" width="52" height="72" rx="8" fill="#4DD4E8"/>
7
+ </svg>