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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(mcp): managed-app logs and lifecycle, tiered by blast radius not by layer
Rahmanda25b8a65df4
diff --git a/CLAUDE.md b/CLAUDE.mdindex 64a91c4c..3c029533 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -261,7 +261,7 @@ to `resources/` (rr) and drive any project from one manifest:## MCP server (`/mcp`) — optional, OFF by defaultAn MCP endpoint so ChatGPT / Claude.ai / Cursor can drive the host. `lib/mcp/*`-(pkce · scope · store · tools · dispatch) + `app/mcp/route.ts` + `app/oauth/*` ++(pkce · scope · store · tool-kit · tools-read · tools · dispatch) + `app/mcp/route.ts` + `app/oauth/*` +`app/.well-known/oauth-*`. **`OS_MCP_ENABLED=1` or every one of those routes 404s** —that is the kill switch, and demo mode forces it off. Read `docs/MCP.md` first.- **`/mcp` is deliberately NOT under `/api`.** `proxy.ts` blocks mutating `/api` thatdiff --git a/docs/MCP.md b/docs/MCP.mdindex 72bcebff..29ac155b 100644--- a/docs/MCP.md+++ b/docs/MCP.md@@ -59,10 +59,16 @@ Picked per token, on the consent screen, capped by `OS_MCP_MAX_SCOPE`.| Scope | Tools ||---|---|-| `read` | `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `browser_status` |-| `write` | + `fs_write` `fs_mkdir` `fs_move` `fs_copy` `fs_delete` |+| `read` | `fs_list` `fs_read` `fs_search` `fs_usage` `sys_stats` `sys_processes` `apps_list` `apps_logs` `browser_status` |+| `write` | + `fs_write` `fs_mkdir` `fs_move` `fs_copy` `fs_delete` `apps_power` || `exec` | + `exec_run` `browser_power` |+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.+`apps_power` is three verbs against known units, so restarting a daemon does not+require handing one over either.+`tools/list` is filtered by the token's scope, and `tools/call` re-checks it — aclient that calls a tool it was never shown still gets refused.@@ -113,7 +119,7 @@ jq -c 'select(.actor|startswith("mcp:"))' ~/.mso/audit.log # everything MCP diSettings → MCP shows the last 20 MCP lines inline.What is recorded: `fs.write` `fs.mkdir` `fs.move` `fs.copy` `fs.delete`-`exec.run` `camoufox.power`, each with its target and whether it succeeded, plus+`exec.run` `managed-app.action` `camoufox.power`, each with its target and whether it succeeded, plus`mcp.denied` when a token asks for a tool above its scope. **That last one is thesignal worth watching** — a `read` connector repeatedly reaching for `exec_run` iswhat a prompt-injected model looks like from the outside.@@ -161,7 +167,9 @@ failure mode for an endpoint whose top scope is a shell.lib/mcp/pkce.ts S256 verify, base64url, hashing, redirect_uri ruleslib/mcp/scope.ts the read/write/exec ladder + the env kill switchlib/mcp/store.ts ~/.mso/mcp.json — clients, codes, tokens (hashed)-lib/mcp/tools.ts the catalog; every handler is a thin call into lib/host+lib/mcp/tool-kit.ts the McpTool shape + arg helpers shared by both tiers+lib/mcp/tools-read.ts the read tier — observability, no way to change anything+lib/mcp/tools.ts the write + exec tiers, and the assembled cataloglib/mcp/dispatch.ts JSON-RPC: initialize / ping / tools.list / tools.callapp/mcp/route.ts the endpoint — bearer, rate limits, dispatchapp/oauth/* authorize (consent) · token · register (DCR)diff --git a/lib/mcp/tool-kit.ts b/lib/mcp/tool-kit.tsnew file mode 100644index 00000000..8a405f36--- /dev/null+++ b/lib/mcp/tool-kit.ts@@ -0,0 +1,40 @@+import type { AuditAction } from "@/lib/host";+import type { Scope } from "./scope";++// Shared shapes for the MCP tool catalog. EVERY handler goes through lib/host — never node fs or+// child_process directly — so all of it inherits the bounds that already guard+// /api/v1: OS_FS_READ_ROOTS / OS_FS_WRITE_ROOTS, the credential denylist+// (~/.ssh, ~/.mso itself, cloud + AI tokens), realpath escape checks, and the+// catastrophic-command filter in exec.ts. That is the whole reason this file is+// thin: a tool that reimplemented an operation would reimplement its guard too.++export interface McpTool {+ name: string;+ description: string;+ scope: Scope;+ inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };+ annotations?: Record<string, boolean>;+ run: (a: Record<string, unknown>) => Promise<unknown>;+ /** Which audit action this writes, and which argument names the target. Reads+ * are deliberately unaudited (bounded + high-volume, same rule the /api/v1+ * routes follow); a tool without this field writes nothing.+ *+ * This exists because MCP tools call lib/host DIRECTLY. The /api/v1 routes+ * audit at the ROUTE layer, so without this every write, delete and exec that+ * arrived over MCP would be invisible in the only forensic trail there is. */+ audit?: { action: AuditAction; targetArg?: string };+}++export const str = (a: Record<string, unknown>, k: string): string => {+ const v = a[k];+ if (typeof v !== "string" || !v) throw new Error(`${k} must be a non-empty string`);+ return v;+};+export const opt = (a: Record<string, unknown>, k: string): string | undefined =>+ typeof a[k] === "string" && a[k] ? (a[k] as string) : undefined;++export const S = (properties: Record<string, unknown>, required?: string[]) =>+ ({ type: "object" as const, properties, ...(required ? { required } : {}) });++export const PATH_P = { path: { type: "string", description: "Absolute path on the VPS, or ~/… for the owner's home." } };+export const READ_ONLY = { readOnlyHint: true, idempotentHint: true };diff --git a/lib/mcp/tools-read.ts b/lib/mcp/tools-read.tsnew file mode 100644index 00000000..93988a8a--- /dev/null+++ b/lib/mcp/tools-read.ts@@ -0,0 +1,112 @@+import { listDir, readFile, searchFs, usage, stats, processes } from "@/lib/host";+import { camoufoxStatus } from "@/lib/camoufox/service";+import { listManagedApps, getManagedAppLogs } from "@/lib/managed-apps/manager";+import { isManagedAppId } from "@/lib/managed-apps/catalog";+import { type McpTool, str, opt, S, PATH_P, READ_ONLY } from "./tool-kit";++// The read tier: observability with no way to change anything. Everything here is+// answerable without granting a shell, which is the whole point of the tiering —+// "why is hermes down?" should not cost the same trust as `exec_run`.+export const READ_TOOLS: McpTool[] = [+ {+ name: "fs_list",+ description:+ "List a directory on the VPS. Returns entries with name, type, size and mtime. " ++ "USE THIS FIRST to discover paths before reading or writing — guessing a path wastes a call. " ++ "Reads are bounded to OS_FS_READ_ROOTS and credential paths (~/.ssh, ~/.mso, cloud tokens) are refused.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S({ ...PATH_P, includeHidden: { type: "boolean", description: "Include dotfiles. Default true." } }, ["path"]),+ run: (a) => listDir(str(a, "path"), a.includeHidden !== false),+ },+ {+ name: "fs_read",+ description:+ "Read a text file on the VPS and return its contents. For binary files this will be garbage — " ++ "check the extension from fs_list first. NOT for finding a file: use fs_search.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S(PATH_P, ["path"]),+ run: async (a) => ({ path: a.path, content: await readFile(str(a, "path")) }),+ },+ {+ name: "fs_search",+ description:+ "Find DIRECTORIES whose name contains a fragment, recursively, under a root. Use it to locate a " ++ "project folder before fs_list — it is bounded and needs no shell scope, unlike exec_run with find. " ++ "It does NOT match file names or file contents; fs_list the directory it returns.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S({+ query: { type: "string", description: "Substring matched against directory names." },+ root: { type: "string", description: "Where to search from. Defaults to ~/projects." },+ }, ["query"]),+ run: (a) => searchFs(str(a, "query"), { root: opt(a, "root") }),+ },+ {+ name: "fs_usage",+ description: "Disk usage for a path: total, used and free bytes. Use for 'is the VPS full?'.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S(PATH_P, ["path"]),+ run: (a) => usage(str(a, "path")),+ },+ {+ name: "sys_stats",+ description:+ "Live VPS health: CPU load, memory, disk, uptime. USE THIS for 'how is the server doing' — " ++ "it is one cheap call and needs no shell scope.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S({}),+ run: () => stats(),+ },+ {+ name: "sys_processes",+ description: "Top processes by CPU with pid, command, cpu% and memory%. Use to find what is eating the box.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S({}),+ run: () => processes(),+ },+ {+ name: "apps_list",+ description:+ "List the managed applications mso can install and control on this VPS, with install and running state. " ++ "This is NOT the mso app list (Files, Terminal, …) — those are UI surfaces with no server state.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S({}),+ run: () => listManagedApps(),+ },+ {+ name: "apps_logs",+ description:+ "Recent log output for a managed application (hermes, openclaw). USE THIS to answer 'why is X " ++ "down' — it needs only read scope, where the same question via exec_run would need a full shell. " ++ "Call apps_list first for the valid ids and their state.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S({ id: { type: "string", description: "Managed app id from apps_list, e.g. hermes." } }, ["id"]),+ run: (a) => {+ const id = str(a, "id");+ if (!isManagedAppId(id)) throw new Error(`unknown managed application "${id}" — call apps_list for valid ids`);+ return getManagedAppLogs(id);+ },+ },+ {+ name: "browser_status",+ description:+ "State of the Camoufox anti-fingerprinting browser (a real Firefox on a headless display). " ++ "Returns installed/running/autostart only. The viewer URL and its one-time VNC password are DELIBERATELY not " ++ "returned here — that session holds live Google and LinkedIn logins, so its credentials never leave " ++ "the box through a tool result. Open Settings in mso to get them.",+ scope: "read",+ annotations: READ_ONLY,+ inputSchema: S({}),+ run: async () => {+ const s = await camoufoxStatus();+ return { installed: s.installed, running: s.running, autostart: s.enabled };+ },+ },+];diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.tsindex 9d500df3..5f1d4f07 100644--- a/lib/mcp/tools.ts+++ b/lib/mcp/tools.ts@@ -1,138 +1,14 @@-import {- listDir, readFile, writeFile, makeDir, remove, move, copy, searchFs, usage,- runCommand, stats, processes,-} from "@/lib/host";-import type { AuditAction } from "@/lib/host";-import { camoufoxStatus, setCamoufoxEnabled } from "@/lib/camoufox/service";-import { listManagedApps } from "@/lib/managed-apps/manager";-import type { Scope } from "./scope";--// The MCP tool catalog. EVERY handler goes through lib/host — never node fs or-// child_process directly — so all of it inherits the bounds that already guard-// /api/v1: OS_FS_READ_ROOTS / OS_FS_WRITE_ROOTS, the credential denylist-// (~/.ssh, ~/.mso itself, cloud + AI tokens), realpath escape checks, and the-// catastrophic-command filter in exec.ts. That is the whole reason this file is-// thin: a tool that reimplemented an operation would reimplement its guard too.--export interface McpTool {- name: string;- description: string;- scope: Scope;- inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };- annotations?: Record<string, boolean>;- run: (a: Record<string, unknown>) => Promise<unknown>;- /** Which audit action this writes, and which argument names the target. Reads- * are deliberately unaudited (bounded + high-volume, same rule the /api/v1- * routes follow); a tool without this field writes nothing.- *- * This exists because MCP tools call lib/host DIRECTLY. The /api/v1 routes- * audit at the ROUTE layer, so without this every write, delete and exec that- * arrived over MCP would be invisible in the only forensic trail there is. */- audit?: { action: AuditAction; targetArg?: string };-}--const str = (a: Record<string, unknown>, k: string): string => {- const v = a[k];- if (typeof v !== "string" || !v) throw new Error(`${k} must be a non-empty string`);- return v;-};-const opt = (a: Record<string, unknown>, k: string): string | undefined =>- typeof a[k] === "string" && a[k] ? (a[k] as string) : undefined;--const S = (properties: Record<string, unknown>, required?: string[]) =>- ({ type: "object" as const, properties, ...(required ? { required } : {}) });--const PATH_P = { path: { type: "string", description: "Absolute path on the VPS, or ~/… for the owner's home." } };-const READ_ONLY = { readOnlyHint: true, idempotentHint: true };--export const TOOLS: McpTool[] = [- {- name: "fs_list",- description:- "List a directory on the VPS. Returns entries with name, type, size and mtime. " +- "USE THIS FIRST to discover paths before reading or writing — guessing a path wastes a call. " +- "Reads are bounded to OS_FS_READ_ROOTS and credential paths (~/.ssh, ~/.mso, cloud tokens) are refused.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S({ ...PATH_P, includeHidden: { type: "boolean", description: "Include dotfiles. Default true." } }, ["path"]),- run: (a) => listDir(str(a, "path"), a.includeHidden !== false),- },- {- name: "fs_read",- description:- "Read a text file on the VPS and return its contents. For binary files this will be garbage — " +- "check the extension from fs_list first. NOT for finding a file: use fs_search.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S(PATH_P, ["path"]),- run: async (a) => ({ path: a.path, content: await readFile(str(a, "path")) }),- },- {- name: "fs_search",- description:- "Find DIRECTORIES whose name contains a fragment, recursively, under a root. Use it to locate a " +- "project folder before fs_list — it is bounded and needs no shell scope, unlike exec_run with find. " +- "It does NOT match file names or file contents; fs_list the directory it returns.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S({- query: { type: "string", description: "Substring matched against directory names." },- root: { type: "string", description: "Where to search from. Defaults to ~/projects." },- }, ["query"]),- run: (a) => searchFs(str(a, "query"), { root: opt(a, "root") }),- },- {- name: "fs_usage",- description: "Disk usage for a path: total, used and free bytes. Use for 'is the VPS full?'.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S(PATH_P, ["path"]),- run: (a) => usage(str(a, "path")),- },- {- name: "sys_stats",- description:- "Live VPS health: CPU load, memory, disk, uptime. USE THIS for 'how is the server doing' — " +- "it is one cheap call and needs no shell scope.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S({}),- run: () => stats(),- },- {- name: "sys_processes",- description: "Top processes by CPU with pid, command, cpu% and memory%. Use to find what is eating the box.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S({}),- run: () => processes(),- },- {- name: "apps_list",- description:- "List the managed applications mso can install and control on this VPS, with install and running state. " +- "This is NOT the mso app list (Files, Terminal, …) — those are UI surfaces with no server state.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S({}),- run: () => listManagedApps(),- },- {- name: "browser_status",- description:- "State of the Camoufox anti-fingerprinting browser (a real Firefox on a headless display). " +- "Returns installed/running/autostart only. The viewer URL and its one-time VNC password are DELIBERATELY not " +- "returned here — that session holds live Google and LinkedIn logins, so its credentials never leave " +- "the box through a tool result. Open Settings in mso to get them.",- scope: "read",- annotations: READ_ONLY,- inputSchema: S({}),- run: async () => {- const s = await camoufoxStatus();- return { installed: s.installed, running: s.running, autostart: s.enabled };- },- },+import { writeFile, makeDir, remove, move, copy, runCommand } from "@/lib/host";+import { setCamoufoxEnabled } from "@/lib/camoufox/service";+import { performManagedAppAction } from "@/lib/managed-apps/manager";+import { isManagedAppId } from "@/lib/managed-apps/catalog";+import { type McpTool, str, opt, S, PATH_P } from "./tool-kit";+import { READ_TOOLS } from "./tools-read";+// The write and exec tiers. Each carries an `audit` descriptor — the dispatcher,+// not the tool, writes the trail, because these call lib/host directly and so+// never pass the route-layer audit that covers /api/v1.+const MUTATE_TOOLS: McpTool[] = [{name: "fs_write",audit: { action: "fs.write" as const, targetArg: "path" },@@ -184,6 +60,27 @@ export const TOOLS: McpTool[] = [run: async (a) => { await remove(str(a, "path")); return { ok: true, path: a.path }; },},+ {+ name: "apps_power",+ audit: { action: "managed-app.action" as const, targetArg: "id" },+ description:+ "Start, stop or restart a managed application on the VPS. Bounded to the known apps and the " ++ "three verbs — restarting a daemon should not require handing over a shell, so this sits at " ++ "write scope rather than exec. Check apps_list or apps_logs first.",+ scope: "write",+ annotations: { destructiveHint: true },+ inputSchema: S({+ id: { type: "string", description: "Managed app id from apps_list." },+ action: { type: "string", enum: ["start", "stop", "restart"], description: "start | stop | restart" },+ }, ["id", "action"]),+ run: (a) => {+ const id = str(a, "id");+ const action = str(a, "action");+ if (!isManagedAppId(id)) throw new Error(`unknown managed application "${id}" — call apps_list for valid ids`);+ if (!["start", "stop", "restart"].includes(action)) throw new Error("action must be start, stop or restart");+ return performManagedAppAction(id, action as "start" | "stop" | "restart");+ },+ },{name: "exec_run",audit: { action: "exec.run" as const, targetArg: "command" },@@ -216,4 +113,6 @@ export const TOOLS: McpTool[] = [},];+export const TOOLS: McpTool[] = [...READ_TOOLS, ...MUTATE_TOOLS];export const TOOLS_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));+export type { McpTool } from "./tool-kit";