hand-mcp 0.0.0-stage → 0.1.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 +21 -0
- package/README.md +88 -2
- package/bin/hand-mcp.js +44 -0
- package/hand.exe +0 -0
- package/package.json +32 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 nathan <137482711+nathwn12@users.noreply.github.com>
|
|
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
|
-
|
|
1
|
+
<h1 align="center">hand-mcp</h1>
|
|
2
|
+
<p align="center"><strong>One MCP server for the headless browser and the Windows desktop: the Gladius and Puppet engines under one stdio connection.</strong></p>
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
## Install
|
|
5
|
+
|
|
6
|
+
Run it without installing:
|
|
7
|
+
|
|
8
|
+
```powershell
|
|
9
|
+
npx hand-mcp
|
|
10
|
+
```
|
|
11
|
+
|
|
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.0`.
|
|
19
|
+
|
|
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.0`. 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.
|
|
21
|
+
|
|
22
|
+
### Or let your AI install it
|
|
23
|
+
|
|
24
|
+
```text
|
|
25
|
+
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.0 (<commit>; release)`.
|
|
29
|
+
If it fails, stop and paste the full output; do not improvise a fix.
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Wire it yourself
|
|
33
|
+
|
|
34
|
+
Point your MCP client at the launcher. The client spawns it and speaks newline-delimited JSON-RPC 2.0 on stdio:
|
|
35
|
+
|
|
36
|
+
```jsonc
|
|
37
|
+
{
|
|
38
|
+
"mcp": {
|
|
39
|
+
"servers": {
|
|
40
|
+
"hand-mcp": {
|
|
41
|
+
"type": "local",
|
|
42
|
+
"command": ["npx", "hand-mcp"]
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
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.0 (<commit>; release)`) and exits without starting a session.
|
|
52
|
+
|
|
53
|
+
The binary's own subcommands are `mcp` (the default), `doctor` and `--version`.
|
|
54
|
+
|
|
55
|
+
One connection carries 33 tools:
|
|
56
|
+
|
|
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.
|
|
60
|
+
|
|
61
|
+
The 32 tools the two engines already served keep their `inputSchema`, `outputSchema`, `description` and `annotations`; only the name gained a prefix.
|
|
62
|
+
|
|
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.
|
|
64
|
+
|
|
65
|
+
## Configure it
|
|
66
|
+
|
|
67
|
+
No flag serves MCP: `hand-mcp` with no argument is the session. One environment variable is the only switch.
|
|
68
|
+
|
|
69
|
+
| Variable | Default | Effect |
|
|
70
|
+
|---|---|---|
|
|
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. |
|
|
72
|
+
|
|
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.
|
|
74
|
+
|
|
75
|
+
## Requirements
|
|
76
|
+
|
|
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.
|
|
79
|
+
- An MCP client that speaks stdio.
|
|
80
|
+
|
|
81
|
+
## Status
|
|
82
|
+
|
|
83
|
+
**Experimental** — pre-release; interfaces may change.
|
|
84
|
+
|
|
85
|
+
## Links
|
|
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)
|
package/bin/hand-mcp.js
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
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
|
+
import { spawn } from 'node:child_process';
|
|
13
|
+
import { existsSync } from 'node:fs';
|
|
14
|
+
import { dirname, join } from 'node:path';
|
|
15
|
+
import { fileURLToPath } from 'node:url';
|
|
16
|
+
|
|
17
|
+
const here = dirname(fileURLToPath(import.meta.url));
|
|
18
|
+
const exe = join(here, '..', 'hand.exe');
|
|
19
|
+
|
|
20
|
+
if (!existsSync(exe)) {
|
|
21
|
+
console.error(`hand-mcp: bundled binary missing at ${exe} — reinstall the package`);
|
|
22
|
+
process.exit(1);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const args = process.argv.slice(2);
|
|
26
|
+
const child = spawn(exe, args.length ? args : ['mcp'], { stdio: 'inherit' });
|
|
27
|
+
|
|
28
|
+
child.on('error', (error) => {
|
|
29
|
+
console.error(`hand-mcp: could not start the bundled binary: ${error.message}`);
|
|
30
|
+
process.exit(1);
|
|
31
|
+
});
|
|
32
|
+
child.on('exit', (code, signal) => {
|
|
33
|
+
if (signal) {
|
|
34
|
+
console.error(`hand-mcp: terminated by ${signal}`);
|
|
35
|
+
process.exit(1);
|
|
36
|
+
}
|
|
37
|
+
process.exit(code ?? 1);
|
|
38
|
+
});
|
|
39
|
+
|
|
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
|
+
for (const signal of ['SIGINT', 'SIGTERM']) {
|
|
43
|
+
process.on(signal, () => child.kill(signal));
|
|
44
|
+
}
|
package/hand.exe
ADDED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,34 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hand-mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "One MCP server for the headless browser and the Windows desktop: the Gladius and Puppet engines under one stdio connection",
|
|
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.1.0');process.exit(1)}\""
|
|
27
|
+
},
|
|
28
|
+
"files": [
|
|
29
|
+
"bin/",
|
|
30
|
+
"hand.exe",
|
|
31
|
+
"LICENSE",
|
|
32
|
+
"README.md"
|
|
33
|
+
]
|
|
34
|
+
}
|