hand-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 +86 -89
- package/bin/hand-mcp.js +0 -12
- package/hand.exe +0 -0
- package/package.json +35 -34
- package/signature.svg +7 -0
package/README.md
CHANGED
|
@@ -1,89 +1,86 @@
|
|
|
1
|
-
<h1 align="center">hand-mcp</h1>
|
|
2
|
-
<p align="center"><strong>
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
{
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
-
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
- [Issues](https://github.com/nathwn12/hand/issues)
|
|
88
|
-
- [Releases](https://github.com/nathwn12/hand/releases)
|
|
89
|
-
- [MIT licence](https://opensource.org/license/mit)
|
|
1
|
+
<h1 align="center">hand-mcp</h1>
|
|
2
|
+
<p align="center"><strong>The MCP server that can see and touch both the browser and Windows.</strong></p>
|
|
3
|
+
|
|
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>
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```powershell
|
|
14
|
+
npx hand-mcp
|
|
15
|
+
```
|
|
16
|
+
|
|
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.
|
|
18
|
+
|
|
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.
|
|
20
|
+
|
|
21
|
+
### Or let your AI install it
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
Install nathwn12/hand (hand-mcp) with `npx hand-mcp`, then prove it works.
|
|
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.
|
|
28
|
+
If it fails, stop and paste the full output; do not improvise a fix.
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Wire it yourself
|
|
32
|
+
|
|
33
|
+
```jsonc
|
|
34
|
+
{
|
|
35
|
+
"mcp": {
|
|
36
|
+
"servers": {
|
|
37
|
+
"hand": {
|
|
38
|
+
"type": "local",
|
|
39
|
+
"command": ["cmd", "/c", "npx", "-y", "hand-mcp"]
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
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.
|
|
47
|
+
|
|
48
|
+
## What it does
|
|
49
|
+
|
|
50
|
+
One connection, two domains, 40 tools:
|
|
51
|
+
|
|
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.
|
|
54
|
+
|
|
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.
|
|
56
|
+
|
|
57
|
+
## Configure it
|
|
58
|
+
|
|
59
|
+
| Variable | Default | Effect |
|
|
60
|
+
|---|---|---|
|
|
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. |
|
|
63
|
+
|
|
64
|
+
The first browser call provisions the pinned `chrome-headless-shell` into a per-user cache and reuses it after that.
|
|
65
|
+
|
|
66
|
+
## Requirements
|
|
67
|
+
|
|
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.
|
|
70
|
+
- An MCP client that speaks stdio.
|
|
71
|
+
|
|
72
|
+
## Status
|
|
73
|
+
|
|
74
|
+
**Experimental**: pre-release; interfaces may change.
|
|
75
|
+
|
|
76
|
+
## Links
|
|
77
|
+
|
|
78
|
+
- [Repository](https://github.com/nathwn12/hand)
|
|
79
|
+
- [Issues](https://github.com/nathwn12/hand/issues)
|
|
80
|
+
- [Releases](https://github.com/nathwn12/hand/releases)
|
|
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/bin/hand-mcp.js
CHANGED
|
@@ -1,14 +1,4 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* hand-mcp — the npm launcher for the bundled Windows binary.
|
|
4
|
-
*
|
|
5
|
-
* Why a launcher and not a postinstall download: the executable ships inside the
|
|
6
|
-
* tarball, so `npx hand-mcp` works with no network, no release asset to resolve,
|
|
7
|
-
* and nothing to verify at run time. 14 MB is the honest cost of that.
|
|
8
|
-
*
|
|
9
|
-
* It forwards argv, stdio and the exit code, so `hand-mcp doctor`, `--version`
|
|
10
|
-
* and a plain MCP session behave exactly like running hand.exe directly.
|
|
11
|
-
*/
|
|
12
2
|
import { spawn } from 'node:child_process';
|
|
13
3
|
import { existsSync } from 'node:fs';
|
|
14
4
|
import { dirname, join } from 'node:path';
|
|
@@ -37,8 +27,6 @@ child.on('exit', (code, signal) => {
|
|
|
37
27
|
process.exit(code ?? 1);
|
|
38
28
|
});
|
|
39
29
|
|
|
40
|
-
// A client that closes the pipe should stop the server too, the same way hand
|
|
41
|
-
// stops on stdin close when it is spawned directly.
|
|
42
30
|
for (const signal of ['SIGINT', 'SIGTERM']) {
|
|
43
31
|
process.on(signal, () => child.kill(signal));
|
|
44
32
|
}
|
package/hand.exe
CHANGED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,34 +1,35 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "hand-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
5
|
-
"type": "module",
|
|
6
|
-
"license": "MIT",
|
|
7
|
-
"repository": {
|
|
8
|
-
"type": "git",
|
|
9
|
-
"url": "https://github.com/nathwn12/hand"
|
|
10
|
-
},
|
|
11
|
-
"homepage": "https://github.com/nathwn12/hand",
|
|
12
|
-
"engines": {
|
|
13
|
-
"node": ">=22.14.0"
|
|
14
|
-
},
|
|
15
|
-
"os": [
|
|
16
|
-
"win32"
|
|
17
|
-
],
|
|
18
|
-
"cpu": [
|
|
19
|
-
"x64"
|
|
20
|
-
],
|
|
21
|
-
"bin": {
|
|
22
|
-
"hand-mcp": "./bin/hand-mcp.js"
|
|
23
|
-
},
|
|
24
|
-
"scripts": {
|
|
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.
|
|
27
|
-
},
|
|
28
|
-
"files": [
|
|
29
|
-
"bin/",
|
|
30
|
-
"hand.exe",
|
|
31
|
-
"LICENSE",
|
|
32
|
-
"README.md"
|
|
33
|
-
|
|
34
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "hand-mcp",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "hand-mcp: one MCP server for headless browser testing (CDP) and Windows desktop computer use",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "https://github.com/nathwn12/hand"
|
|
10
|
+
},
|
|
11
|
+
"homepage": "https://github.com/nathwn12/hand",
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=22.14.0"
|
|
14
|
+
},
|
|
15
|
+
"os": [
|
|
16
|
+
"win32"
|
|
17
|
+
],
|
|
18
|
+
"cpu": [
|
|
19
|
+
"x64"
|
|
20
|
+
],
|
|
21
|
+
"bin": {
|
|
22
|
+
"hand-mcp": "./bin/hand-mcp.js"
|
|
23
|
+
},
|
|
24
|
+
"scripts": {
|
|
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.2.0');process.exit(1)}\""
|
|
27
|
+
},
|
|
28
|
+
"files": [
|
|
29
|
+
"bin/",
|
|
30
|
+
"hand.exe",
|
|
31
|
+
"LICENSE",
|
|
32
|
+
"README.md",
|
|
33
|
+
"signature.svg"
|
|
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>
|