@wezzard/mcp-relay 0.18.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 +55 -16
- package/dist/NOTICE.txt +1 -1
- package/dist/build-info.json +32 -16
- package/dist/doctor.mjs +5273 -234
- package/dist/integrity.json +3 -3
- package/dist/receiver.mjs +79 -25
- package/dist/server.mjs +11870 -6140
- 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,10 +306,26 @@ 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,
|
|
307
|
-
a real Mac that machine-service exposes, such as `
|
|
328
|
+
a real Mac that machine-service exposes, such as `Mac-A`. Every other
|
|
308
329
|
tool works on it as on a VM ([docs/durable-machines.md](docs/durable-machines.md)).
|
|
309
330
|
|
|
310
331
|
- The relay finds the instance that owns the machine as `machctl list` does:
|
|
@@ -315,12 +336,20 @@ tool works on it as on a VM ([docs/durable-machines.md](docs/durable-machines.md
|
|
|
315
336
|
instance found is used only once its `/health` confirms its ID.
|
|
316
337
|
- Every call carries the lease's `lease_id`, files go as bytes, and the relay
|
|
317
338
|
stages under the lease's workspace, which machine-service removes at release.
|
|
339
|
+
- When machine-service reports `machine_id`, the relay saves it and can resume
|
|
340
|
+
the same lease after the Mac is renamed or its address changes. Requests keep
|
|
341
|
+
using the name the lease was granted under. Older services keep the existing
|
|
342
|
+
name and origin checks.
|
|
343
|
+
- A durable 404 never proves release. The relay finds the owner again and
|
|
344
|
+
verifies that its machine record no longer names the lease. An unreachable
|
|
345
|
+
owner leaves the lease retained with guest state `unknown`.
|
|
318
346
|
- Runs take snapshots only while the Mac's cua-driver daemon (`CuaDriver.app`,
|
|
319
347
|
`com.trycua.driver`) holds Screen Recording, read with
|
|
320
348
|
`cua-driver permissions status --json` in the lease. machine-service's own
|
|
321
349
|
permissions are not read, and it needs no Screen Recording grant.
|
|
322
|
-
- A durable machine is on the home network and not isolated from it,
|
|
323
|
-
|
|
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.
|
|
324
353
|
|
|
325
354
|
## Selected environments
|
|
326
355
|
|
|
@@ -355,8 +384,8 @@ needed. Diagnostic commands appear in the review data
|
|
|
355
384
|
as command-only steps without screenshots. `finish` verifies the package before
|
|
356
385
|
destroying the VM; a failed delivery removes only the derived files it created
|
|
357
386
|
and retains the VM for a corrected attempt. Cleanup checks the read-only host
|
|
358
|
-
Tart inventory (the selected one, when an environment is selected
|
|
359
|
-
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
|
|
360
389
|
time up to that TTL; the machine-service reaper is the final backstop for process death.
|
|
361
390
|
|
|
362
391
|
Relay evidence has no size limit (owner decision PS-D12): screenshots are
|
|
@@ -372,8 +401,8 @@ keeps the VM for a retry after space is freed.
|
|
|
372
401
|
|
|
373
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.
|
|
374
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.
|
|
375
|
-
- `MCP_RELAY_URL`: the loopback machine-service origin, default `http://localhost:6240`. Non-loopback servers and redirects are refused;
|
|
376
|
-
- `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.
|
|
377
406
|
- `CONSUL_HTTP_ADDR`: the Consul agent that lists machine-service instances, in Consul mode; default `http://127.0.0.1:8500`.
|
|
378
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`.
|
|
379
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.
|
|
@@ -396,13 +425,20 @@ npm run setup:dev -- /absolute/path/to/built/relay-driver
|
|
|
396
425
|
npm run check # build, typecheck, tests
|
|
397
426
|
```
|
|
398
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
|
+
|
|
399
435
|
Three tests need something outside this repository and skip with a message
|
|
400
436
|
when it is absent: the console fixture regeneration needs a historical
|
|
401
437
|
`../vm-service` checkout with the Python backend (or
|
|
402
|
-
`
|
|
403
|
-
|
|
404
|
-
`../machine-service/rust
|
|
405
|
-
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
|
|
406
442
|
`tests/fixtures/` were encoded once from the test's spatial PNG with a codec
|
|
407
443
|
outside this repository and are committed, because the core carries none.
|
|
408
444
|
|
|
@@ -422,8 +458,11 @@ the stand-in before anything is acquired), an invalid call refused by the
|
|
|
422
458
|
contract, a full acquire, stage, exec, finish lifecycle with a verified package,
|
|
423
459
|
and a lease abandoned when the session ends, which is retained with its renewal
|
|
424
460
|
paused rather than released. What is checked is what happened on disk and at
|
|
425
|
-
the service, not what the model said.
|
|
426
|
-
|
|
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`.
|
|
427
466
|
|
|
428
467
|
The relay-driver links are development-only. The tests run the manager, the
|
|
429
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
|
}
|