Era-aware connection model & capability gating (#1626) (#1697)

* Era-aware connection model & capability gating (#1626)

Make protocol era (SEP §7.8) a first-class, per-server connection dimension,
orthogonal to the transport type, and drive the SDK Client's versionNegotiation
from it.

Config
- Add `ServerProtocolEra` ("legacy" | "auto" | "modern"), `DEFAULT_PROTOCOL_ERA`
  (legacy, per the SDK's don't-auto-probe guidance), `MODERN_PROTOCOL_VERSION`,
  and `eraToVersionNegotiation()` in core/mcp/types.ts.
- Persist `protocolEra` on `StoredMCPServer` / `InspectorServerSettings`,
  round-tripping through serverList.ts (omitting the default on disk) and the
  `/api/servers` read + write validators.

InspectorClient / state
- Thread `versionNegotiation` through `InspectorClientOptions` (default legacy),
  replacing the hardcoded pin. After connect, read `getProtocolEra()` /
  `getDiscoverResult()` / `getNegotiatedProtocolVersion()`, expose them via
  getters, dispatch `protocolEraChange` / `discoverResultChange`, and clear on
  disconnect. `useInspectorClient` surfaces `protocolEra` / `discoverResult`.

Web UI
- ServerSettingsForm: a Protocol Era selector bound to the per-server setting.
- ConnectionInfoContent: era-aware — Era badge, Session ("Sessionless" on
  modern), and a Discovery section (supported versions + extensions) from the
  `server/discover` result.

CLI/TUI also map the mcp.json `protocolEra` into versionNegotiation so the field
applies uniformly. Version negotiation stays fully client-side; modern connect
works over the existing remote tunnel and disconnect is sessionless (the SDK
skips DELETE when there is no session id). Mcp-* header fidelity is left to the
History/Network card.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Address @claude review: era docstrings, era validation, stdio session label, AGENTS.md rule

- Fix stale docstrings/comments in inspectorClient.ts, useInspectorClient.ts,
  inspectorClientEventTarget.ts, and ConnectionInfoContent.tsx: getProtocolEra()
  returns "legacy" (not undefined) on a plain legacy connect; it is undefined
  only when not connected.
- Validate protocolEra at the storedFieldsToInspectorSettings read boundary
  (new shared isProtocolEra guard) so a hand-edited mcp.json read directly by
  the CLI/TUI drops an unknown era instead of passing it to
  eraToVersionNegotiation. Keeps the exhaustive switch intact.
- ConnectionInfoContent: the Session row is HTTP-only — show "N/A (stdio)" for
  stdio instead of the misleading "Session-based".
- AGENTS.md: add a rule against unjustified `as unknown as` double casts, and
  drop the one such cast introduced in the serverList test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Address re-review: dedupe isProtocolEra guard in remote server

Replace the local isProtocolEra in remote/node/server.ts with the shared guard
now exported from serverList.ts (already imported here), so the era literal set
lives in one place and can't drift.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

---------

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

core/mcp/serverList.ts

@@ -5,13 +5,18 @@
  * remote-server route handlers.
  */
 
-import { DEFAULT_MAX_FETCH_REQUESTS, DEFAULT_TASK_TTL_MS } from "./types.js";
+import {
+  DEFAULT_MAX_FETCH_REQUESTS,
+  DEFAULT_PROTOCOL_ERA,
+  DEFAULT_TASK_TTL_MS,
+} from "./types.js";
 import type { Root } from "@modelcontextprotocol/client";
 import type {
   InspectorServerSettings,
   MCPConfig,
   MCPServerConfig,
   ServerEntry,
+  ServerProtocolEra,
   ServerType,
   StdioServerConfig,
   StoredMCPServer,
@@ -29,6 +34,27 @@ const VALID_SERVER_TYPES: ReadonlySet<ServerType> = new Set([
   "streamable-http",
 ]);
 
+const VALID_PROTOCOL_ERAS: ReadonlySet<ServerProtocolEra> = new Set([
+  "legacy",
+  "auto",
+  "modern",
+]);
+
+/**
+ * Runtime guard for the `protocolEra` literal. `StoredMCPServer` types the
+ * field as `ServerProtocolEra`, but a hand-edited `mcp.json` read directly by
+ * the CLI/TUI (which don't pass through the `/api/servers` route validators)
+ * can carry any string. Dropping unknowns here keeps a garbage value from
+ * reaching `eraToVersionNegotiation` — matching the read-side check the
+ * `/api/servers` route already applies.
+ */
+export function isProtocolEra(value: unknown): value is ServerProtocolEra {
+  return (
+    typeof value === "string" &&
+    VALID_PROTOCOL_ERAS.has(value as ServerProtocolEra)
+  );
+}
+
 /**
  * Normalizes server type:
  * - missing / unknown / non-string → "stdio" (matches Claude Desktop's default)
@@ -89,6 +115,7 @@ type StoredInspectorFields = Pick<
   StoredMCPServer,
   | "headers"
   | "metadata"
+  | "protocolEra"
   | "connectionTimeout"
   | "requestTimeout"
   | "taskTtl"
@@ -162,6 +189,7 @@ export function storedFieldsToInspectorSettings(
     stored.maxFetchRequests !== undefined ||
     stored.oauth !== undefined ||
     stored.roots !== undefined ||
+    stored.protocolEra !== undefined ||
     stored.env !== undefined ||
     stored.cwd !== undefined;
   if (!hasAny) return undefined;
@@ -189,6 +217,13 @@ export function storedFieldsToInspectorSettings(
     // `[]`, which `inspectorSettingsToStoredFields` then omits on write.
     roots: stored.roots ?? [],
   };
+  // Absent on disk reads back as the default era; the write side then omits the
+  // default so a byte-stable round-trip never injects `protocolEra` into files
+  // that never set it. An unknown literal from a hand-edited file is dropped
+  // (→ default legacy) rather than passed through to `eraToVersionNegotiation`.
+  if (isProtocolEra(stored.protocolEra)) {
+    settings.protocolEra = stored.protocolEra;
+  }
   // Truthiness drops empty-string OAuth fields — mirrors the write-side
   // coercion in `validateSettings` (server.ts) so a round-trip can't
   // accidentally surface `oauthClientId: ""` to the form, where the
@@ -258,6 +293,16 @@ export function inspectorSettingsToStoredFields(
     out.autoRefreshOnListChanged = true;
   }
 
+  // Persist only when it differs from the default era. Absent reads back as
+  // DEFAULT_PROTOCOL_ERA, so writing the default would inject the field into
+  // hand-edited files that never had it and break byte-stable round-trips.
+  if (
+    settings.protocolEra !== undefined &&
+    settings.protocolEra !== DEFAULT_PROTOCOL_ERA
+  ) {
+    out.protocolEra = settings.protocolEra;
+  }
+
   // Persist only when it differs from the default. Unlike the timeouts, 0 is a
   // meaningful value here (unlimited), so the omit-sentinel is the default
   // itself rather than 0 — writing the default would inject the field into
@@ -309,6 +354,7 @@ export function inspectorSettingsToStoredFields(
 const INSPECTOR_FIELD_KEY_MAP = {
   headers: true,
   metadata: true,
+  protocolEra: true,
   connectionTimeout: true,
   requestTimeout: true,
   taskTtl: true,