glovrex-connect

# glovrex-connect Wires MCP servers into six hosts with one command: Claude Code, Claude Desktop, Cursor, Windsurf, Cline, and Continue. MCP is an open standard, so whatever model runs inside the host — Claude, GPT, Gemini, or anything else — talks to the same server the same way. One wiring step covers all of them. Two ways to use it: - `install` wires a single server (e.g. the Glovrex server itself) into one host or all six. - `install-all --registry <file>` wires several servers at once — Glovrex plus any companion server that needs its own credentials (a choki-* admin server, for example) — into one host or all six, in one pass. This tool does not include or run any MCP server. For a single server you pass its script path via `--server` or `GLOVREX_SERVER`; for several, list them in a registry file (see below). See [glovrex-cc-plugin](https://github.com/greymoth-jp/glovrex-cc-plugin) for the Claude Code hook layer that sits alongside this. Every wiring action that actually writes something also appends a locally-signed provenance receipt — see [Governance receipts](#governance-receipts). ## Install ``` npm install -g glovrex-connect ``` ## Usage ``` glovrex-connect install <host>|all [--server <path>] [--apply] [--name <name>] glovrex-connect install-all --registry <path> [<host>|all] [--apply] glovrex-connect status glovrex-connect print <host> glovrex-connect verify-receipts ``` Default is dry-run: `install` and `install-all` print what would change and touch nothing. Pass `--apply` to actually write. ``` glovrex-connect install all --server /path/to/glovrex-server.mjs glovrex-connect install cursor --server /path/to/glovrex-server.mjs --apply glovrex-connect install-all --registry ./servers.json glovrex-connect install-all cursor --registry ./servers.json --apply glovrex-connect status glovrex-connect print continue --server /path/to/glovrex-server.mjs glovrex-connect verify-receipts ``` ## What it does per host | host | target | how | |---|---|---| | claude-code | shells out to `claude mcp add` (scope=user) | never edits `~/.claude.json` directly | | claude-desktop | `claude_desktop_config.json` | JSON merge under `mcpServers` | | cursor | `~/.cursor/mcp.json` | JSON merge under `mcpServers` | | windsurf | `~/.codeium/windsurf/mcp_config.json` | JSON merge under `mcpServers` | | cline | `cline_mcp_settings.json` (native or VS Code globalStorage) | JSON merge, adds `disabled`/`autoApprove` | | continue | `.continue/mcpServers/<name>.yaml` (workspace-local) | writes a new YAML file | For claude-desktop, cursor, windsurf, and cline, a JSON config that already exists is merged, not replaced — other `mcpServers` entries are left alone. Before any file is overwritten, the original is copied to `<file>.bak-<timestamp>`. Running install twice with the same arguments is a no-op the second time. Continue only loads MCP servers in **Agent Mode** — chat mode ignores `mcpServers` entirely. This tool writes the workspace-local `.continue/mcpServers/<name>.yaml` file and leaves the global `config.yaml` untouched. If Cline isn't installed yet, neither of its candidate config paths will exist; install prints instructions instead of guessing where to create one. ## status Reads all six host configs (read-only) and reports, per host, whether the config file exists and whether a `glovrex` entry is already there. ## print Prints the config snippet or shell command for one host, for manual copy-paste — useful when you'd rather not run `--apply` yourself. ## Multi-server registry (`install-all`) A registry file lists several servers in one place: ```json { "servers": [ { "name": "glovrex", "command": "node", "args": ["/path/to/glovrex-server.mjs"] }, { "name": "choki-admin", "command": "node", "args": ["/path/to/choki-server.mjs"], "env": { "CHOKI_ADMIN_BEARER": "${CHOKI_ADMIN_BEARER}" } } ] } ``` `glovrex-connect install-all --registry servers.json` wires every entry into every host in one pass. Target one host instead with `install-all <host> --registry servers.json`. For claude-desktop, cursor, windsurf, and cline this is a single merged file write (one diff, one backup) covering all the servers in the registry, not one write per server. For claude-code and continue — which are inherently one action per server — you get one result row per server. `command` can be `node`, `python`, `npx`, or anything else on `PATH`; `args` is optional. ## Env passthrough A server that needs a credential (a choki-* admin bearer token, for example) declares it under `env`, but the registry file never holds the literal value — only a reference in the form `${VAR_NAME}`. At install time, `${VAR_NAME}` is resolved from your shell's environment. If the variable isn't set, install-all refuses to run rather than write a broken or empty credential. If `env` holds anything other than a `${VAR_NAME}` reference — a real token pasted in directly, say — install-all refuses the whole registry file outright: that shape of value is treated as a plaintext secret accidentally committed to a file, not a config mistake to warn about and continue past. The actual (real) value is what gets written into each host's local config file — that's what the host needs to spawn the server with the credential available. It is never printed to the console: dry-run diffs, the `claude mcp add` command preview, and receipts all show the `${VAR_NAME}` reference instead, with the real value substituted back out of any text before it's displayed. ## Governance receipts Every `install` or `install-all` action that actually writes a file (or successfully runs `claude mcp add`) signs a receipt with a local Ed25519 keypair and appends it to `~/.glovrex-connect/receipts.jsonl` (base directory follows `GLOVREX_CONNECT_HOME` like everything else here). Each line records who ran the install, when, which host, which server names, and where — never env values or full commands, so the ledger itself can't leak a credential even if it's copied elsewhere. The keypair is generated on first use and stored under `~/.glovrex-connect/keys/` (private key, mode 0600). It never leaves the machine and is never bundled into the package. `glovrex-connect verify-receipts` re-checks every entry: the payload hash (catches tampering with the receipt itself) and the Ed25519 signature (catches forgery). Exits non-zero if anything fails to verify. This proves *that a specific local install ran and wrote what it says it wrote* — it is not a trust anchor for the server being wired (no PKI, no third-party attestation) and it does not vouch for what the server does at runtime. ## Provenance events (opt-in) glovrex-connect emits a signed provenance event to your own Glovrex app only when `GLOVREX_URL` is set; default is a complete no-op. With no `GLOVREX_URL` in the environment, nothing here changes: no network call, no extra file, no extra output — every example above behaves exactly as if this feature didn't exist. When `GLOVREX_URL` (and optionally `GLOVREX_TOKEN`) is set, every applied `install`/`install-all` result also posts its already-signed governance receipt (the same one described above) to `POST <GLOVREX_URL>/api/events`. If the app can't be reached, the event is appended to `~/.glovrex-connect/events-queue.jsonl` instead of being lost, and is retried automatically the next time a durable action runs. A Glovrex app that is down or unset never affects this tool's own exit code — wiring a host succeeds or fails on its own terms either way. ## create-app: scaffold an Island-constrained app ``` glovrex-connect create-app <name> [--out <dir>] [--force] glovrex-connect create-app --list-slots ``` `create-app` generates the skeleton of an Island-constrained Glovrex app — one that declares data into a fixed Glovrex Island slot instead of shipping its own UI. Glovrex renders every such app with the same set of components, so there is no layout to design and no custom look to get wrong. This is a structural constraint, not a missing feature: the manifest schema rejects any field that isn't part of the fixed vocabulary below, so there is no field to smuggle custom HTML/CSS/components into. ``` glovrex-connect create-app my-dashboard --out ./my-dashboard ``` writes four files into the target directory (current directory by default): - `manifest.json` — `entry.type: "island"`, `glovrex.api: true`, and an empty `slots` array to fill in. - `index.mjs` — a standalone core that runs with no Glovrex connection, plus a commented one-line template for where to emit a Level 1 provenance event via `@greymoth/glovrex-sdk` once that's a dependency. - `README.md` — explains the Island constraint to whoever opens the repo. - `.github/workflows/glovrex-gate.yml` — a CI gate template that validates `manifest.json` against the Island schema on every push and pull request. It's meant for apps built and published out of the scaffolded repo itself, not for pasting into a pull request against someone else's project. `create-app` refuses to overwrite any of those four files if they already exist; pass `--force` to overwrite. ``` glovrex-connect create-app --list-slots ``` prints the Island slots an app can target and the render vocabulary it can ask for, without scaffolding anything: - Island slots: `node`, `detail`, `connect`. - Render vocabulary: `list`, `card`, `stat`, `badge`, `timeline`, `keyval`. A slot binding in `manifest.json` is exactly `{ "island", "source", "render", "label" }` — `source` is an engine reference string, the other three are picked from the vocabularies above. ## What this doesn't do - Doesn't manage, rotate, or generate secrets — the environment variable has to already be set in your shell before you run `install-all`. - Doesn't verify that a wired server behaves correctly, or at all — a receipt proves the wiring action happened, not that the server is trustworthy. - Doesn't encrypt the receipt ledger or the signing key at rest; both are plain files protected only by filesystem permissions. - Doesn't establish identity across machines — a receipt's public key travels inside the receipt itself, so `verify-receipts` proves internal consistency, not "this came from a specific person." - Doesn't have an officially documented Claude Desktop config path on Linux; the path used there is a best-effort XDG-style guess, not confirmed against Anthropic's own docs (carried over from v1). - `continue` still writes one workspace-local YAML file per server name — a registry with three servers means three files, not one. ## Design notes - Zero runtime dependencies — Node stdlib only (`node:crypto` for signing), `node >=20`. - Nothing here embeds a real filesystem path from any particular machine. The server path always comes from `--server`/`GLOVREX_SERVER`, or from the registry file you point `--registry` at. - `GLOVREX_CONNECT_HOME` overrides every host's base directory — and the receipt ledger/keys/events-queue directory — which is how the test suite exercises all six adapters and the governance layer without touching a real profile. - Provenance events target the same `POST /api/events` contract as [glovrex-sdk](https://github.com/greymoth-jp/glovrex-sdk)'s `reportEvent()`. `@greymoth/glovrex-sdk` isn't on the npm registry yet, so `lib/provenance.mjs` is a small vendored client against that same contract rather than a dependency — no `npm install` required, same request shape and offline-queue behavior either way. ## License GPL-3.0 — see [LICENSE](LICENSE).