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>

core/react/useServerListWritable.ts

@@ -0,0 +1,82 @@
+/**
+ * React hook over the `GET /api/config` endpoint that recovers the session's
+ * `writable` flag. The backend sets `writable: false` when the web UI was
+ * launched against a read-only server list — a `--config` session file or an
+ * ad-hoc `--server-url` / command target — so the UI can hide catalog CRUD
+ * (add / edit / remove / reorder / settings-save) it would only get a 403 for.
+ *
+ * Mirrors {@link useSandboxUrl} (same `/api/config` source, same fetch shape).
+ * Defaults to `true` until the fetch resolves and whenever the field is absent
+ * (a legacy backend that predates the flag), so the default catalog and
+ * `--catalog` keep full CRUD without any UI change.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+
+export interface UseServerListWritableOptions {
+  /** Base URL of the remote server (typically `window.location.origin`). */
+  baseUrl: string;
+  /** Optional auth token for the `x-mcp-remote-auth` header. */
+  authToken?: string;
+  /** Fetch function to use (default: globalThis.fetch). Useful in tests. */
+  fetchFn?: typeof fetch;
+}
+
+export interface UseServerListWritableResult {
+  /** Whether the server list is writable (catalog) or read-only (session). */
+  writable: boolean;
+  /** True while the initial fetch is in flight. */
+  loading: boolean;
+}
+
+/** Minimal shape we read from the `/api/config` payload. */
+interface ConfigPayload {
+  writable?: unknown;
+}
+
+export function useServerListWritable(
+  opts: UseServerListWritableOptions,
+): UseServerListWritableResult {
+  const { baseUrl, authToken, fetchFn } = opts;
+  const doFetch = fetchFn ?? globalThis.fetch;
+  const base = baseUrl.replace(/\/$/, "");
+
+  // Default writable so the common (catalog) case shows CRUD immediately and a
+  // legacy backend that omits the field keeps working.
+  const [writable, setWritable] = useState<boolean>(true);
+  const [loading, setLoading] = useState<boolean>(true);
+
+  const load = useCallback(
+    async (isCancelled: () => boolean): Promise<void> => {
+      const headers: Record<string, string> = {};
+      if (authToken) headers["x-mcp-remote-auth"] = `Bearer ${authToken}`;
+      try {
+        const res = await doFetch(`${base}/api/config`, {
+          method: "GET",
+          headers,
+        });
+        if (isCancelled() || !res.ok) return;
+        const body = (await res.json()) as ConfigPayload;
+        if (isCancelled()) return;
+        // Only an explicit `false` makes the list read-only; a missing field
+        // (legacy backend) stays writable.
+        setWritable(body.writable !== false);
+      } catch {
+        // Network error / aborted fetch: leave writable at its default (true).
+      } finally {
+        if (!isCancelled()) setLoading(false);
+      }
+    },
+    [base, authToken, doFetch],
+  );
+
+  useEffect(() => {
+    let cancelled = false;
+    void load(() => cancelled);
+    return () => {
+      cancelled = true;
+    };
+  }, [load]);
+
+  return { writable, loading };
+}