Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

docs: record that connectors-gateway now consumes this MCP surface

Rahmanc80b83a2463a
diff --git a/CLAUDE.md b/CLAUDE.md
index 5b9d696f..7bf7243c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -302,8 +302,15 @@ that is the kill switch, and demo mode forces it off. Read `docs/MCP.md` first.
(including `~/.mso` itself) and `exec.ts`'s destructive filter for free. A tool that
reimplements an operation reimplements its guard too — don't.
- Scope ladder `read < write < exec`, picked per token on the consent page, capped by
- `OS_MCP_MAX_SCOPE` (default `write`). `tools/list` filters by it AND `tools/call`
+ `OS_MCP_MAX_SCOPE` (default `write`; **the running box is set to `exec`** — open
+ decision, see the integration doc below). `tools/list` filters by it AND `tools/call`
re-checks it — a client can call a name it was never shown.
+- **Tool names are a cross-repo contract.** `rahmanef63/connectors-gateway` registered
+ mso as a connector on 2026-08-17 and pins 15 of the 17 names as literal strings
+ (`x-upstream`), omitting `exec_run` and `browser_power` entirely. Renaming or removing
+ a tool here breaks it with **no error in either repo** — `parity.test.ts` guards the
+ Alfa axis, not this one. Read `docs/CONNECTORS-GATEWAY-INTEGRATION.md` before touching
+ a tool name.
- Store is `~/.mso/mcp.json`, **sha256 only**, same atomic-write + fail-loud-on-corrupt
rule as `lib/auth/device-store.ts`. Codes are single-use, 60 s, deleted BEFORE the
token is minted. `browser_status` must never return the VNC password — that profile
diff --git a/docs/CONNECTORS-GATEWAY-INTEGRATION.md b/docs/CONNECTORS-GATEWAY-INTEGRATION.md
new file mode 100644
index 00000000..d2de3e37
--- /dev/null
+++ b/docs/CONNECTORS-GATEWAY-INTEGRATION.md
@@ -0,0 +1,90 @@
+# mso → Connectors Gateway
+
+**Status: mso is a registered connector there as of 2026-08-17** (`connectors-gateway@03e0948`).
+Nothing in THIS repo changed to make that happen — no config, no code, no token. This
+file exists so the next person here knows the dependency is there, because otherwise
+it is invisible from inside mso.
+
+Direction matters: mso is the **provider**. `rahmanef63/connectors-gateway` is a consumer
+of mso's MCP surface, alongside CareerPack and Composio. It reaches mso the same way
+ChatGPT or Claude.ai would — over `https://mso.rahmanef.com/mcp`, through the OAuth in
+[`MCP.md`](./MCP.md). mso grants it nothing special.
+
+## The thing that will break, and how
+
+The gateway keeps its own manifest of mso's tools, and it pins **upstream tool names as
+strings**:
+
+```
+connectors-gateway/adapters/remote-mcp/connectors/mso.connector.json
+ { "id": "mso.fs.delete", …, "x-upstream": "fs_delete" }
+```
+
+There is no shared type, no generated client, and no build step that reads this repo.
+
+**So renaming or removing a tool in `lib/mcp/tools.ts` or `tools-read.ts` breaks the
+gateway silently.** Both repos still typecheck, both test suites still pass, and the
+failure only shows up as one action erroring at call time for whoever is using it. The
+same is true in reverse: a tool ADDED here does not appear in the gateway until someone
+edits that JSON.
+
+`lib/mcp/parity.test.ts` already guards the Alfa ↔ MCP axis. It does not know about this
+one. If you rename a tool, grep the gateway repo for its name.
+
+## What is exposed there, and what is deliberately not
+
+15 of the 17 tools. The whole `read` and `write` tiers, and **neither `exec` tool**:
+
+| Omitted | Why |
+|---|---|
+| `exec_run` | arbitrary shell on the VPS the gateway itself runs on |
+| `browser_power` | drives the Camoufox profile holding live Google / LinkedIn sessions |
+
+They are **omitted from the manifest, not disabled in policy**. That was decided in the
+gateway's `docs/16-connector-strategy.md` before the connector was written: a disabled
+action is one policy edit away from live, while a name absent from the catalog cannot be
+resolved into an action id at all.
+
+`connectors-gateway/adapters/remote-mcp/src/mso.test.ts` pins it, and checks `x-upstream`
+rather than the local id — so renaming an action over there cannot smuggle the same shell
+back in.
+
+Two tools are rated `R3` + destructive there, which routes them through that platform's
+human approval queue before they ever reach mso: **`fs_delete`** and **`apps_power`**. The
+second one because stopping or restarting a daemon cuts off whatever is using it.
+
+## Open decision — yours, not the gateway's
+
+`.env.local` on the running box has:
+
+```
+OS_MCP_MAX_SCOPE=exec
+```
+
+`MCP.md`'s own example in this repo says `write`, and the gateway's `docs/16` says to
+narrow it to `write` before connecting mso. It has **not** been changed — that is a
+production config change to this application, so it is the owner's call rather than a
+side effect of work done in another repo.
+
+Narrowing it costs nothing for this integration: the gateway omits both `exec` tools, so
+it never asks for that scope. What the ceiling protects against is a *different* token —
+minted later, from the consent screen, by anyone who can sign in — being able to reach
+`exec_run` at all.
+
+## What was done in this repo: nothing
+
+The gateway's manifest was written by reading `lib/mcp/tools.ts`, `lib/mcp/tools-read.ts`
+and `lib/mcp/tool-kit.ts` directly, rather than by calling `tools/list` against the live
+server. That was deliberate: it meant **no MCP bearer had to be minted on this deployment**
+to build the integration. `mso mcp list` was empty before and is empty after.
+
+## Checking it from here
+
+```bash
+mso mcp list # tokens the gateway (or anything else) holds. Empty = not connected yet.
+mso audit 50 # every mutating MCP call, actor `mcp:<id>`
+```
+
+The gateway side lives at `connectors-gateway/docs/16-connector-strategy.md` (why mso is
+connected read/write only) and `docs/18-oauth.md` (how a client authorizes to that gateway
+— unrelated to how the gateway authorizes to mso).
diff --git a/docs/MCP.md b/docs/MCP.md
index 3c2413b7..c5a3a6d7 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -69,6 +69,12 @@ written reason. The two catalogs stay separate on purpose (different transport,
different guard) but may not drift by accident, which they did: MCP shipped the
managed-app and browser tools before Alfa had them.
+**These tool names are also a cross-repo contract.** `rahmanef63/connectors-gateway`
+registered mso as a connector on 2026-08-17 and pins 15 of these names as strings; a
+rename here breaks it with no error in either repo, and `parity.test.ts` does not cover
+that axis. See [`CONNECTORS-GATEWAY-INTEGRATION.md`](./CONNECTORS-GATEWAY-INTEGRATION.md)
+before renaming or removing a tool.
+
The tiering is about blast radius, not about which layer the call lands in.
`apps_logs` reads a daemon's journal, so "why is hermes down?" is answerable from
a `read` token — the same question through `exec_run` would need a full shell.