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/server/web-server-config.ts

@@ -4,7 +4,7 @@
 
 import pino from "pino";
 import type { Logger } from "pino";
-import type { MCPServerConfig } from "../../../core/mcp/types.ts";
+import type { MCPConfig, MCPServerConfig } from "../../../core/mcp/types.ts";
 // Import directly from the leaf module — not the `core/mcp/remote/index.ts`
 // barrel — so Vite's config-time module graph doesn't pull in `createRemoteLogger`
 // (which references `pino/browser.js`) or other browser-side re-exports that
@@ -23,6 +23,28 @@ export interface WebServerConfig {
   dangerouslyOmitAuth: boolean;
   /** Single initial MCP server config, or null when no server specified. */
   initialMcpConfig: MCPServerConfig | null;
+  /**
+   * Absolute path to the `mcp.json` file the backend reads (and writes/watches
+   * when {@link writable}). When undefined the backend falls back to the
+   * default catalog (`~/.mcp-inspector/mcp.json`). Set by the launcher for
+   * `--catalog <path>` (writable) or `--config <path>` (read-only session).
+   * Mutually exclusive with {@link initialServers} (#1481).
+   */
+  mcpConfigPath: string | undefined;
+  /**
+   * When false, the server list is read-only for the session: the backend
+   * rejects `/api/servers` mutations and never seeds/migrates the file, and
+   * the web UI hides catalog CRUD. True for the default catalog and
+   * `--catalog`; false for `--config` and ad-hoc launches (#1481).
+   */
+  writable: boolean;
+  /**
+   * In-memory server list served by the backend instead of reading a file —
+   * set by the launcher to seed an ad-hoc `--server-url` / command target
+   * (with `--header`) without writing any file. Implies `writable: false`.
+   * Mutually exclusive with {@link mcpConfigPath} (#1481/#1483).
+   */
+  initialServers: MCPConfig | null;
   storageDir: string | undefined;
   allowedOrigins: string[];
   /** Sandbox port (0 = dynamic). */
@@ -151,6 +173,12 @@ export function printServerBanner(
 
 export interface BuildWebServerConfigOptions {
   initialMcpConfig?: MCPServerConfig | null;
+  /** Catalog/session file the backend should serve; see {@link WebServerConfig.mcpConfigPath}. */
+  mcpConfigPath?: string;
+  /** Read-only when false; see {@link WebServerConfig.writable}. Defaults to true. */
+  writable?: boolean;
+  /** In-memory ad-hoc list; see {@link WebServerConfig.initialServers}. */
+  initialServers?: MCPConfig | null;
 }
 
 /**
@@ -160,7 +188,12 @@ export interface BuildWebServerConfigOptions {
 export function buildWebServerConfig(
   options: BuildWebServerConfigOptions = {},
 ): WebServerConfig {
-  const { initialMcpConfig = null } = options;
+  const {
+    initialMcpConfig = null,
+    mcpConfigPath,
+    writable = true,
+    initialServers = null,
+  } = options;
   const port = parseInt(process.env.CLIENT_PORT ?? "6274", 10);
   const hostname = process.env.HOST ?? "localhost";
   const baseUrl = `http://${hostname}:${port}`;
@@ -191,6 +224,9 @@ export function buildWebServerConfig(
     authToken,
     dangerouslyOmitAuth,
     initialMcpConfig,
+    mcpConfigPath,
+    writable,
+    initialServers,
     storageDir: process.env.MCP_STORAGE_DIR,
     allowedOrigins: process.env.ALLOWED_ORIGINS?.split(",").filter(Boolean) ?? [
       baseUrl,