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.

feat(mcp): managed-app logs and lifecycle, tiered by blast radius not by layer

Rahmanda25b8a65df4
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 default
An 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` that
diff --git a/docs/MCP.md b/docs/MCP.md
index 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 — a
client 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 di
Settings → 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 the
signal worth watching** — a `read` connector repeatedly reaching for `exec_run` is
what 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 rules
lib/mcp/scope.ts the read/write/exec ladder + the env kill switch
lib/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 catalog
lib/mcp/dispatch.ts JSON-RPC: initialize / ping / tools.list / tools.call
app/mcp/route.ts the endpoint — bearer, rate limits, dispatch
app/oauth/* authorize (consent) · token · register (DCR)
diff --git a/lib/mcp/tool-kit.ts b/lib/mcp/tool-kit.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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";