feat(web): catalog vs read-only session launch model + apply --header (#1481, #1483) (#1496)

* feat(web): catalog vs read-only session launch model + apply --header (#1481, #1483)

Per specification/v2_catalog_launch_config.md, `mcp-inspector --web` now selects
the backend's server-list source and a session-wide writability, instead of
seeding an inert `initialMcpConfig` the UI never read:

- `--catalog <path>` (and `MCP_CATALOG_PATH`) → active WRITABLE catalog
  (seed/CRUD/watch), like the default catalog.
- `--config <path>` → READ-ONLY session file: served in the UI but never
  written, seeded, or plaintext-secret-migrated — safe to point at a foreign
  config (e.g. claude_desktop_config.json).
- ad-hoc `--server-url`/command (+ `--header`) → one server held IN MEMORY
  (no file written); `--header` is lifted onto the entry so the seeded
  connection actually uses it (closes the #1483 warn-only no-op).
- nothing → default catalog (writable), unchanged.

Backend (`createRemoteApp`): new `writable` + `initialServers` options. GET
/api/servers branches three ways (in-memory / read-only file with no
seed+no migrate / writable catalog); the four mutating routes return 403 when
read-only; `/api/config` carries `writable`; the file watcher is skipped for
in-memory sessions. `--catalog`/`--config` are mutually exclusive and neither
combines with an ad-hoc target or `--header`; `--header` requires an ad-hoc
HTTP/SSE server (clear errors otherwise — no silent no-op).

UI: `useServerListWritable` reads `writable` from /api/config; the Servers
screen hides add/edit/clone/remove/reorder/settings and shows a read-only
banner when false. All new props default to writable=true (back-compatible).

Docs: spec gaps G2/G3/G4 updated; launcher README documents the flags.

Verified end-to-end against the built launcher: --config (writable:false,
file byte-stable, mutations 403), ad-hoc --header (in-memory, header lifted),
and --catalog (writable:true, POST persists).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(web): address review — Mantine <Code> in read-only banner, clarify watcher comment

- Replace raw <code> with Mantine <Code> in the read-only-session Alert
  (repo convention: prefer Mantine primitives over raw HTML).
- Add a comment near `watchable` clarifying that a read-only `--config` file
  is still watched on purpose (read-only blocks UI writes, not external
  observation; `writable` does not gate watching).

Deferred (per reviewer): consolidating useSandboxUrl + useServerListWritable
into one useConfig hook to avoid the duplicate /api/config fetch — optional
follow-up. The redundant ad-hoc header type-guard is kept as defensive.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/web/src/components/screens/ServerListScreen/ServerListScreen.test.tsx

@@ -91,4 +91,48 @@ describe("ServerListScreen", () => {
       ).not.toBeInTheDocument();
     });
   });
+
+  describe("read-only session (writable=false)", () => {
+    it("shows the read-only banner", () => {
+      renderWithMantine(<ServerListScreen {...baseProps} writable={false} />);
+      expect(screen.getByText("Read-only session")).toBeInTheDocument();
+    });
+
+    it("hides the Add menu and per-card mutation actions", () => {
+      renderWithMantine(<ServerListScreen {...baseProps} writable={false} />);
+      // Cards still render and connect controls remain.
+      expect(screen.getByText("Alpha")).toBeInTheDocument();
+      expect(
+        screen.queryByRole("button", { name: /add servers/i }),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByRole("button", { name: "Edit" }),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByRole("button", { name: "Remove" }),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByRole("button", { name: "Clone" }),
+      ).not.toBeInTheDocument();
+      expect(
+        screen.queryByRole("button", { name: "Settings" }),
+      ).not.toBeInTheDocument();
+    });
+
+    it("omits drag handles even when onReorder is provided", () => {
+      renderWithMantine(<ServerListScreen {...baseProps} writable={false} />);
+      expect(
+        screen.queryByRole("button", { name: /^Reorder / }),
+      ).not.toBeInTheDocument();
+    });
+
+    it("keeps the Add menu and actions when writable (default)", () => {
+      renderWithMantine(<ServerListScreen {...baseProps} />);
+      expect(
+        screen.getByRole("button", { name: /add servers/i }),
+      ).toBeInTheDocument();
+      expect(screen.getAllByRole("button", { name: "Edit" }).length).toBe(2);
+      expect(screen.queryByText("Read-only session")).not.toBeInTheDocument();
+    });
+  });
 });

clients/web/src/components/screens/ServerListScreen/ServerListScreen.tsx

@@ -1,4 +1,11 @@
-import { ScrollArea, SimpleGrid, Stack, Text } from "@mantine/core";
+import {
+  Alert,
+  Code,
+  ScrollArea,
+  SimpleGrid,
+  Stack,
+  Text,
+} from "@mantine/core";
 import {
   DndContext,
   KeyboardSensor,
@@ -23,6 +30,13 @@ import {
 
 export interface ServerListScreenProps {
   servers: ServerEntry[];
+  /**
+   * Whether the server list is writable (catalog) or read-only (a `--config`
+   * session file / ad-hoc launch). When false, all catalog mutation controls
+   * (add, edit, clone, remove, reorder, settings) are hidden and a read-only
+   * banner is shown. Defaults to true.
+   */
+  writable?: boolean;
   /** Id of the server the wiring layer treats as active (drives card dimming). */
   activeServer?: string;
   onAddManually: () => void;
@@ -57,6 +71,7 @@ const EmptyState = Text.withProps({
 
 export function ServerListScreen({
   servers,
+  writable = true,
   activeServer,
   onAddManually,
   onImportConfig,
@@ -81,11 +96,12 @@ export function ServerListScreen({
 
   const ids = servers.map((s) => s.id);
 
-  // `reorderable` only when a persistence callback is wired. Without it we
-  // render plain `ServerCard`s (no grip, no DndContext) so the screen stays
-  // usable as a pure display — the SortableServerCard's grip would otherwise
-  // be a dead affordance.
-  const reorderable = onReorder !== undefined;
+  // `reorderable` only when a persistence callback is wired AND the list is
+  // writable. Without it we render plain `ServerCard`s (no grip, no DndContext)
+  // so the screen stays usable as a pure display — the SortableServerCard's
+  // grip would otherwise be a dead affordance (and reorder is a catalog write
+  // the backend rejects in a read-only session).
+  const reorderable = onReorder !== undefined && writable;
 
   // Built only when reorderable — the drag-end handler and the fresh
   // announcements object (four closures) are otherwise allocated every render
@@ -99,6 +115,7 @@ export function ServerListScreen({
 
   const cardProps = (server: ServerEntry) => ({
     compact,
+    writable,
     activeServer,
     onToggleConnection,
     onConnectionInfo,
@@ -127,9 +144,17 @@ export function ServerListScreen({
 
   return (
     <PageContainer>
+      {!writable && (
+        <Alert color="gray" variant="light" title="Read-only session">
+          This server list was launched with <Code>--config</Code> or an ad-hoc
+          server and can't be edited here. Changes won't be saved. Use{" "}
+          <Code>--catalog</Code> (or no flag) to manage a writable catalog.
+        </Alert>
+      )}
       <ServerListControls
         serverCount={servers.length}
         compact={compact}
+        writable={writable}
         onToggleList={onToggleCompact}
         onAddManually={onAddManually}
         onImportConfig={onImportConfig}