@wezzard/mcp-relay 0.19.0 → 0.20.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/.claude-plugin/plugin.json +1 -1
- package/README.md +47 -15
- package/dist/NOTICE.txt +1 -1
- package/dist/build-info.json +32 -16
- package/dist/doctor.mjs +5270 -232
- package/dist/integrity.json +3 -3
- package/dist/receiver.mjs +79 -25
- package/dist/server.mjs +11639 -6096
- package/package.json +9 -5
- package/pi-mcp.json +1 -1
package/README.md
CHANGED
|
@@ -112,9 +112,14 @@ without a Claude Code plugin or pi package wrapper.
|
|
|
112
112
|
|
|
113
113
|
### Prerequisites
|
|
114
114
|
|
|
115
|
-
Node 22+, Python 3 with `fcntl` for the registry lock, and
|
|
116
|
-
|
|
117
|
-
|
|
115
|
+
Node 22+, Python 3 with `fcntl` for the registry lock, and a running
|
|
116
|
+
[machine-service](https://github.com/WeZZard/vm-service) (formerly vm-service) with prepared guest images.
|
|
117
|
+
The relay runs on macOS and on Ubuntu. Only a local Tart/machine-service
|
|
118
|
+
backend needs an Apple-silicon Mac with Tart; on any other host, such as
|
|
119
|
+
Ubuntu, the relay is a client of an instance on another host, and verifies a
|
|
120
|
+
VM's destruction in that instance's `/machines` inventory instead of a local
|
|
121
|
+
Tart inventory. Bonjour discovery uses `dns-sd` on macOS and Avahi's
|
|
122
|
+
`avahi-browse` on Linux, or the relay's own multicast query when Avahi is absent.
|
|
118
123
|
Check readiness with `node dist/doctor.mjs`. It does not acquire a VM or
|
|
119
124
|
establish guest UI readiness. Staging and runs assume no software in the guest
|
|
120
125
|
but Node.js, which runs the relay's own guest code; `relay_stage` refuses an
|
|
@@ -301,6 +306,22 @@ Failed or uncertain launches retain ownership; resolve or cancel the attempt
|
|
|
301
306
|
rather than replaying it. Console tests use mocked backends; no live viewer,
|
|
302
307
|
installation or platform acceptance is claimed here.
|
|
303
308
|
|
|
309
|
+
## Every instance
|
|
310
|
+
|
|
311
|
+
The relay asks every machine-service instance on the network, found as
|
|
312
|
+
`machctl list` finds them, so a Mac whose own instance offers nothing still
|
|
313
|
+
sees the Macs that host the VMs ([docs/instances.md](docs/instances.md)).
|
|
314
|
+
|
|
315
|
+
- `relay_search` names, for each installation, the instances that offer it,
|
|
316
|
+
each with its `machine_id` and its catalog generation, and lists every
|
|
317
|
+
instance asked; an instance that did not answer is listed as unreachable.
|
|
318
|
+
- `relay_probe` and `relay_acquisition_capabilities` answer per instance.
|
|
319
|
+
- `relay_acquire` with `image` chooses an instance that offers the image and
|
|
320
|
+
has capacity, says which and why in `chosen`, and passes a capacity refusal
|
|
321
|
+
to the next instance. Every later call on the guest goes to that instance.
|
|
322
|
+
- `instance` narrows any of these to one instance, by its name, a former name,
|
|
323
|
+
its `machine_id` or its origin. A selected environment asks only its own.
|
|
324
|
+
|
|
304
325
|
## Durable machines
|
|
305
326
|
|
|
306
327
|
`relay_acquire` takes `machine` in place of `image` to lease a durable machine,
|
|
@@ -326,8 +347,9 @@ tool works on it as on a VM ([docs/durable-machines.md](docs/durable-machines.md
|
|
|
326
347
|
`com.trycua.driver`) holds Screen Recording, read with
|
|
327
348
|
`cua-driver permissions status --json` in the lease. machine-service's own
|
|
328
349
|
permissions are not read, and it needs no Screen Recording grant.
|
|
329
|
-
- A durable machine is on the home network and not isolated from it,
|
|
330
|
-
|
|
350
|
+
- A durable machine is on the home network and not isolated from it, and it has
|
|
351
|
+
no console. A CI job on it holds its lease like any other client, so it never
|
|
352
|
+
shares the desktop with a lease.
|
|
331
353
|
|
|
332
354
|
## Selected environments
|
|
333
355
|
|
|
@@ -362,8 +384,8 @@ needed. Diagnostic commands appear in the review data
|
|
|
362
384
|
as command-only steps without screenshots. `finish` verifies the package before
|
|
363
385
|
destroying the VM; a failed delivery removes only the derived files it created
|
|
364
386
|
and retains the VM for a corrected attempt. Cleanup checks the read-only host
|
|
365
|
-
Tart inventory (the selected one, when an environment is selected
|
|
366
|
-
claiming destruction. Leases default to 4 hours, renewed 15 minutes at a
|
|
387
|
+
Tart inventory (the selected one, when an environment is selected; on a host
|
|
388
|
+
with no local Tart, the instance's `/machines` inventory) before claiming destruction. Leases default to 4 hours, renewed 15 minutes at a
|
|
367
389
|
time up to that TTL; the machine-service reaper is the final backstop for process death.
|
|
368
390
|
|
|
369
391
|
Relay evidence has no size limit (owner decision PS-D12): screenshots are
|
|
@@ -379,8 +401,8 @@ keeps the VM for a retry after space is freed.
|
|
|
379
401
|
|
|
380
402
|
- `MCP_RELAY_PROJECT`: the project directory (the plugin passes Claude Code's). Evidence lands under `relay-evidence/<task>/` there. Every host file the relay reads, `relay_stage`'s `workspace` and `files[].local` and `relay_script`'s `localPath`, lies in this folder: a relative path resolves against it, an absolute path must already lie in it, and a path through a symlink is refused.
|
|
381
403
|
- `MCP_RELAY_SESSION`: an explicit session identity. By default each server process takes a fresh random one; a stable identity lets a restarted server reconcile and reattach the guests of the same identity.
|
|
382
|
-
- `MCP_RELAY_URL`: the loopback machine-service origin, default `http://localhost:6240`. Non-loopback servers and redirects are refused;
|
|
383
|
-
- `MACHINE_SERVICE_DISCOVERY`: how
|
|
404
|
+
- `MCP_RELAY_URL`: the loopback machine-service origin, default `http://localhost:6240`. Non-loopback servers and redirects are refused; an instance on another Mac is reached only when discovery finds it.
|
|
405
|
+
- `MACHINE_SERVICE_DISCOVERY`: how the other instances are found, `bonjour` (the default: `dns-sd -Z` on macOS, `avahi-browse` on Linux, else the relay's own multicast query) or `consul`, as for machine-service and machctl.
|
|
384
406
|
- `CONSUL_HTTP_ADDR`: the Consul agent that lists machine-service instances, in Consul mode; default `http://127.0.0.1:8500`.
|
|
385
407
|
- `MCP_RELAY_GUEST_NETWORK`: the network every guest is acquired on, `nat` (the default) or `internet`. With `internet`, machine-service gives a guest that reaches the internet and reaches neither this host nor any private network; an application that hosts agents sets it. The agent cannot choose it: `relay_acquire` takes no network. Any other value stops the server at startup and refuses every acquisition, and a machine-service that cannot give `internet` refuses the acquisition with its own reason, never falling back to `nat`.
|
|
386
408
|
- `MCP_RELAY_ON_EXIT`: what the end of a session does to its guests, `pause` (the default: renewal pauses and the VMs are kept for an explicit finish or release) or `release` (every guest is released, then the server exits). An application that owns its tasks' machines, such as The Desk, sets `release`. Any other value stops the server at startup.
|
|
@@ -403,13 +425,20 @@ npm run setup:dev -- /absolute/path/to/built/relay-driver
|
|
|
403
425
|
npm run check # build, typecheck, tests
|
|
404
426
|
```
|
|
405
427
|
|
|
428
|
+
The tests start from an empty environment (`scripts/test.mjs`): nothing in
|
|
429
|
+
your shell, such as `VM_ENVIRONMENT_FILE`, `MCP_RELAY_URL`, `MACHCTL`, `TART`
|
|
430
|
+
or `TART_HOME`, reaches them, and a relay a test starts is refused the
|
|
431
|
+
installed instance's origin. Only variables named `MCP_RELAY_TEST_*` pass, as
|
|
432
|
+
the tests' own inputs. Run a single file the same way:
|
|
433
|
+
`node scripts/test.mjs tests/server.test.ts`.
|
|
434
|
+
|
|
406
435
|
Three tests need something outside this repository and skip with a message
|
|
407
436
|
when it is absent: the console fixture regeneration needs a historical
|
|
408
437
|
`../vm-service` checkout with the Python backend (or
|
|
409
|
-
`
|
|
410
|
-
|
|
411
|
-
`../machine-service/rust
|
|
412
|
-
corpus needs `../pilot-images`. The JPEG and WebP presentation fixtures in
|
|
438
|
+
`MCP_RELAY_TEST_PYTHON_BACKEND`); the environment parity test needs a
|
|
439
|
+
`machctl` built from source (`MCP_RELAY_TEST_MACHCTL`, or a release build in
|
|
440
|
+
`../machine-service/rust`; never one on PATH) and `../pilot-images`; and the
|
|
441
|
+
shared catalog text corpus needs `../pilot-images`. The JPEG and WebP presentation fixtures in
|
|
413
442
|
`tests/fixtures/` were encoded once from the test's spatial PNG with a codec
|
|
414
443
|
outside this repository and are committed, because the core carries none.
|
|
415
444
|
|
|
@@ -429,8 +458,11 @@ the stand-in before anything is acquired), an invalid call refused by the
|
|
|
429
458
|
contract, a full acquire, stage, exec, finish lifecycle with a verified package,
|
|
430
459
|
and a lease abandoned when the session ends, which is retained with its renewal
|
|
431
460
|
paused rather than released. What is checked is what happened on disk and at
|
|
432
|
-
the service, not what the model said.
|
|
433
|
-
|
|
461
|
+
the service, not what the model said. Each session has its own HOME and
|
|
462
|
+
`CLAUDE_CONFIG_DIR`, so only the plugin under test loads. The suite needs the
|
|
463
|
+
Claude Code executable named by `MCP_RELAY_TEST_CLAUDE` and a credential in
|
|
464
|
+
`MCP_RELAY_TEST_ANTHROPIC_API_KEY` or `MCP_RELAY_TEST_CLAUDE_CODE_OAUTH_TOKEN`,
|
|
465
|
+
and spends a few model turns per case, so it is not part of `npm test`.
|
|
434
466
|
|
|
435
467
|
The relay-driver links are development-only. The tests run the manager, the
|
|
436
468
|
guest programs and the shipped server against fixture HTTP services, fixture
|
package/dist/NOTICE.txt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
This distribution includes compiled @wezzard/relay-driver-core, @wezzard/relay-driver-host-sdk and @wezzard/relay-driver-remote-runtime code (https://github.com/WeZZard/relay-driver), the Model Context Protocol TypeScript SDK,
|
|
1
|
+
This distribution includes compiled @wezzard/relay-driver-core, @wezzard/relay-driver-host-sdk and @wezzard/relay-driver-remote-runtime code (https://github.com/WeZZard/relay-driver), the Model Context Protocol TypeScript SDK, Ajv with ajv-formats, and the ws WebSocket library (MIT). See build-info.json for source hashes and versions. The relay implementation was inherited from pi-vm-relay (https://github.com/WeZZard/pi-vm-relay) at commit 8990123, synchronized with its implementation through commit 0d69fc7 before that project's retirement, and has been maintained here as mcp-relay's own implementation from then on.
|
package/dist/build-info.json
CHANGED
|
@@ -799,6 +799,20 @@
|
|
|
799
799
|
"node_modules/typebox/build/value/shared/union_priority_sort.mjs": "cd3beabc02d254660e6e9b4647f7b54706955d27ad6df8200de756248599b50e",
|
|
800
800
|
"node_modules/typebox/build/value/shared/union_score_select.mjs": "48ac87f8b950b98655383ad35ef6027f5f13d75523d4c33de3cdfcc3d623af29",
|
|
801
801
|
"node_modules/typebox/build/value/value.mjs": "4e2948390e27c53f0a63bcd4813cd7517daf1a9cb5719ec86751f81cacc0ac52",
|
|
802
|
+
"node_modules/ws/lib/buffer-util.js": "4e996b0c29f30bb094d836a2a563aceebaf3e8692a1e3d5bb4a01a233029732f",
|
|
803
|
+
"node_modules/ws/lib/constants.js": "391e823142b8b370e55a2fd32b022deaf03b8415c56000009674ebc86a0b4f86",
|
|
804
|
+
"node_modules/ws/lib/event-target.js": "c45d3c6e12d170c860c0c3f1a050aa0f864d9806632b609a1e607d675aba128c",
|
|
805
|
+
"node_modules/ws/lib/extension.js": "852564f0f6b460287043803eae732666fb5610f676874354fc89f06aa4e986ed",
|
|
806
|
+
"node_modules/ws/lib/limiter.js": "e0469d4b83f6ba764b15f80e1766b75c136fbff68f048f4c050f0b1c7f065f69",
|
|
807
|
+
"node_modules/ws/lib/permessage-deflate.js": "16a91536988a53c23047ee5882392068728a839a244178c3b09b8c54982f58b0",
|
|
808
|
+
"node_modules/ws/lib/receiver.js": "a6ada33c9a2d54eaf595824b821ea89ca2c6395f89aa06755c52142148274884",
|
|
809
|
+
"node_modules/ws/lib/sender.js": "b343e24310aeb924e713767fb7cd445bccf4f3cc3504ceb2c56ce76b89c1cf45",
|
|
810
|
+
"node_modules/ws/lib/stream.js": "a56fcb6e2b152097ee820b6f5410b1f71e59819b45d08d9f8bda588fe39070ec",
|
|
811
|
+
"node_modules/ws/lib/subprotocol.js": "be3f6323d6f549568577dcba9004c1479d95c65a7abb0fe0c582875b9fac0b7c",
|
|
812
|
+
"node_modules/ws/lib/validation.js": "41ce8e83d0d434132e1704895fedb91f6703a701b42d91c80954ab29b2845593",
|
|
813
|
+
"node_modules/ws/lib/websocket-server.js": "6d8dd89a841748c80445fd5fcdb5ba8005369b53cc3525135e11304c8b9c55e5",
|
|
814
|
+
"node_modules/ws/lib/websocket.js": "9b7bd84b9a95e5bfa66de2dd0ba21aa69ac21013d04c39db066acca66504618b",
|
|
815
|
+
"node_modules/ws/wrapper.mjs": "fe154662301fd558f935f9c217fccbe7a7dac02ff39e648a000589403ff27c7f",
|
|
802
816
|
"node_modules/zod-to-json-schema/dist/esm/Options.js": "11bfc58fbf69f3044798d1871b10d1c11951bb51c1a35636ebfcad9c04c0a950",
|
|
803
817
|
"node_modules/zod-to-json-schema/dist/esm/Refs.js": "cefaaa074df0750b62ae164cfe77818eb86ff54d220d9ae39da323af6bd8c845",
|
|
804
818
|
"node_modules/zod-to-json-schema/dist/esm/errorMessages.js": "7ea991477cf69f1f096db2ebf1148cb1dfa3e2e25253cf6f15da3ab5cdbfa40c",
|
|
@@ -953,35 +967,37 @@
|
|
|
953
967
|
"node_modules/zod/v4/mini/iso.js": "24acf58a401645baaab9846987e5387cdf7c9e659e2e0aa3b3b6b8ac5555a5ed",
|
|
954
968
|
"node_modules/zod/v4/mini/parse.js": "b87374f4e821d583f699d83e4b74ac59e4a5a782c510959187a0ba209145d76b",
|
|
955
969
|
"node_modules/zod/v4/mini/schemas.js": "5614339bbec6b9be13ed1809e1215fe44d78e99f5f0eee848c0bb3b25dc1c9b6",
|
|
956
|
-
"src/archive.ts": "
|
|
970
|
+
"src/archive.ts": "1368e3fea858572f3b68932a2fe1a62186f82fce52f0f4c171f74e6dbb52c152",
|
|
957
971
|
"src/capture-gate.ts": "6757d7329b62e5b093323eddc779ee13722a0da24ab659649a23a2e70c4fbd56",
|
|
958
|
-
"src/config.ts": "
|
|
972
|
+
"src/config.ts": "74a8545f0bec0b13de6ac9ae9ba8f3a6cf1ebc9810ed03f8983365c1f43ecece",
|
|
959
973
|
"src/console.ts": "d8258173a24449c2a394289b14983b9575c5ce753ab267d4e13213f3abfcb72d",
|
|
960
|
-
"src/core.ts": "
|
|
961
|
-
"src/discovery.ts": "
|
|
962
|
-
"src/doctor.ts": "
|
|
974
|
+
"src/core.ts": "49915615db2971ec7a503ecc956f0d7334fa3b63303ef18aa8f9410307ad195b",
|
|
975
|
+
"src/discovery.ts": "c3c3bdfecf2aa34c44532d504e92fcdb321dd2feca51f3f235d403c04c8dc99f",
|
|
976
|
+
"src/doctor.ts": "3d7ebd3214bceb6121446a5a50b42d96a7635ac8c5ea6240cc9cb33f34ab1912",
|
|
963
977
|
"src/downloads.ts": "4f37b5bb4fac96f9260a3a87c83bacf715b9add5ae9926d3fe0994000c70a8dd",
|
|
964
978
|
"src/environment.ts": "5770e966e49d78ae069614078c667f94e70074b150f83111049529ff613aa215",
|
|
965
979
|
"src/evidence-merge.ts": "2f2759e28e70595ef9284fec85e1d6082bf25e815d04f0a36a253c24bfb75110",
|
|
966
|
-
"src/guest/image-evidence.ts": "
|
|
967
|
-
"src/guest/receiver.ts": "
|
|
980
|
+
"src/guest/image-evidence.ts": "807cc35aa2c4cf06ee7ebfaa336bc5e293ce2660da80b3443f5ed1a1c9af71a5",
|
|
981
|
+
"src/guest/receiver.ts": "b8a5b26a1079dbf34193245215f249dd95c7dbdffe5aacd6aeb603aa77c94afe",
|
|
968
982
|
"src/image-presentation.ts": "64ca29a3444a04606cb783c81ac2d0f3136f9a9ac730ae9074156f0a63256c76",
|
|
969
983
|
"src/images.ts": "415bfb37966a60ef3e407236295b9aeeb314f7fb33de55a6ada512cff6661908",
|
|
970
|
-
"src/machine-service.ts": "
|
|
971
|
-
"src/manager.ts": "
|
|
972
|
-
"src/mdns.ts": "
|
|
984
|
+
"src/machine-service.ts": "65c093a7f78203d89a75939c49f33efba3b742edca6c770f7307b213ae59c625",
|
|
985
|
+
"src/manager.ts": "637c4b1505e920fe323cf18dc2ceb5a70a637d148a500d0a6bea51a37e45e2ba",
|
|
986
|
+
"src/mdns.ts": "d81886a6004b01490bb5b40ad81b9a8944bcee80945b5b1c346307c188515d44",
|
|
973
987
|
"src/owner-lock.ts": "a99cbaba67b4aff0e646dc5d5967db4497ba6dbda83fb1838c55f0bf0f6e0367",
|
|
974
988
|
"src/package.ts": "a52ed791813922e3ace9144706ddde8313a67d8580a3acd54a0799de3ebe44d2",
|
|
975
989
|
"src/probe.ts": "40a123f725aad7c22fe63707dd2de99646cb1f307d7d660927e8ca2b973e9ce0",
|
|
976
990
|
"src/registry.ts": "87478f1ceef0f06df9b28c064a817383ff153bdadd70e6d58b4a7ed464f66146",
|
|
991
|
+
"src/relay-client.ts": "7e66223599c3fb7bf1061176f68c8755035048821fc4ce0a04dc31083882ef38",
|
|
992
|
+
"src/relay-session.ts": "b88942c95738f896e1fb7be6213fb6a849baa23c4dcb8bef39474b5a11a0a604",
|
|
977
993
|
"src/review-data.ts": "2e873eb23612fd4502d84e65322006345f4e97bb679109b23dc4d26683200c19",
|
|
978
|
-
"src/schema.ts": "
|
|
994
|
+
"src/schema.ts": "00cf26a824569f4ccaa1756f838db13f7859b13eb15ce8140832299352d093ef",
|
|
979
995
|
"src/search-diagnostics.ts": "cea037618c56f075d51155101ad1cc0314bfa67b174bdb070191e0ea5ea04679",
|
|
980
|
-
"src/search.ts": "
|
|
981
|
-
"src/server.ts": "
|
|
982
|
-
"src/surface.ts": "
|
|
983
|
-
"src/transfer.ts": "
|
|
984
|
-
"src/transport.ts": "
|
|
996
|
+
"src/search.ts": "d131e439525d283e0585904622c8d2ecb00708f9775f419256ffd28f7b2d32a2",
|
|
997
|
+
"src/server.ts": "d279f5dfb27074609b108cbf605e4ed45c1b21c3a86868ff68b9dd9b7beb269a",
|
|
998
|
+
"src/surface.ts": "41c7f7e7d422611fec56b56f82145ec584885c023108e69c3075e58f73b6230f",
|
|
999
|
+
"src/transfer.ts": "f7a7aba3dca7821e4777e8560b1710ff13875fbf455e24da24f9c18eeb447a52",
|
|
1000
|
+
"src/transport.ts": "4a197433f229bf5c9fb324243694aba6bbd3cd79b41922d887cff7e651a0276b",
|
|
985
1001
|
"src/typebox.ts": "7f071fbc67548c7d3701272dabe88a217812e12e41dfad76974ff08169fa1a7e",
|
|
986
1002
|
"src/util.ts": "88993ec29376fbaf5c19fd23153b19c35fef99be1a906c59428cf48554c3b8da"
|
|
987
1003
|
}
|