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>

clients/web/src/test/core/mcp/protocolEra.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import {
+  DEFAULT_PROTOCOL_ERA,
+  MODERN_PROTOCOL_VERSION,
+  eraToVersionNegotiation,
+} from "@inspector/core/mcp/types.js";
+
+describe("eraToVersionNegotiation", () => {
+  it("maps legacy to the legacy mode", () => {
+    expect(eraToVersionNegotiation("legacy")).toEqual({ mode: "legacy" });
+  });
+
+  it("maps auto to the probing mode", () => {
+    expect(eraToVersionNegotiation("auto")).toEqual({ mode: "auto" });
+  });
+
+  it("maps modern to a pin at the modern protocol version", () => {
+    expect(eraToVersionNegotiation("modern")).toEqual({
+      mode: { pin: MODERN_PROTOCOL_VERSION },
+    });
+  });
+
+  it("defaults to the legacy era", () => {
+    expect(DEFAULT_PROTOCOL_ERA).toBe("legacy");
+    expect(eraToVersionNegotiation(DEFAULT_PROTOCOL_ERA)).toEqual({
+      mode: "legacy",
+    });
+  });
+});

clients/web/src/test/core/mcp/serverList.test.ts

@@ -303,6 +303,76 @@ describe("serverEntriesToMcpConfig", () => {
     expect(round).toEqual(original);
   });
 
+  it("round-trips protocolEra: lifts a non-default value to settings and back to disk", () => {
+    const original: MCPConfig = {
+      mcpServers: {
+        "era-modern": {
+          type: "streamable-http",
+          url: "https://x.test/mcp",
+          protocolEra: "modern",
+        },
+      },
+    };
+    const [entry] = mcpConfigToServerEntries(original);
+    expect(entry?.settings?.protocolEra).toBe("modern");
+    const round = serverEntriesToMcpConfig(mcpConfigToServerEntries(original));
+    expect(round).toEqual(original);
+  });
+
+  it("round-trips protocolEra: auto is a non-default value", () => {
+    const original: MCPConfig = {
+      mcpServers: {
+        "era-auto": {
+          type: "streamable-http",
+          url: "https://x.test/mcp",
+          protocolEra: "auto",
+        },
+      },
+    };
+    const [entry] = mcpConfigToServerEntries(original);
+    expect(entry?.settings?.protocolEra).toBe("auto");
+    const round = serverEntriesToMcpConfig(mcpConfigToServerEntries(original));
+    expect(round).toEqual(original);
+  });
+
+  it("drops an unknown protocolEra literal on read (hand-edited file)", () => {
+    // The CLI/TUI read mcp.json directly (no /api/servers validators), so a
+    // garbage era must be dropped here rather than reaching versionNegotiation.
+    // Spread the invalid field through an `object`-typed literal so the garbage
+    // value models a hand-edited file without needing an `as unknown as` cast.
+    const badEra: object = { protocolEra: "future" };
+    const original: MCPConfig = {
+      mcpServers: {
+        "era-bad": {
+          type: "streamable-http",
+          url: "https://x.test/mcp",
+          ...badEra,
+        },
+      },
+    };
+    const [entry] = mcpConfigToServerEntries(original);
+    expect(entry?.settings?.protocolEra).toBeUndefined();
+  });
+
+  it("omits protocolEra from disk when it equals the default (legacy)", () => {
+    // A legacy era is the default — writing it back must NOT inject the field.
+    // A benign inspector field keeps `settings` materialized.
+    const original: MCPConfig = {
+      mcpServers: {
+        "era-legacy": {
+          type: "streamable-http",
+          url: "https://x.test/mcp",
+          protocolEra: "legacy",
+          connectionTimeout: 5000,
+        },
+      },
+    };
+    const [entry] = mcpConfigToServerEntries(original);
+    expect(entry?.settings?.protocolEra).toBe("legacy");
+    const round = serverEntriesToMcpConfig(mcpConfigToServerEntries(original));
+    expect("protocolEra" in (round.mcpServers["era-legacy"] ?? {})).toBe(false);
+  });
+
   it("lifts top-level Inspector-extension fields onto ServerEntry.settings (form shape)", () => {
     const cfg: MCPConfig = {
       mcpServers: {

clients/web/src/test/core/react/useInspectorClient.test.tsx

@@ -77,6 +77,59 @@ describe("useInspectorClient", () => {
     expect(result.current.protocolVersion).toBe("2025-06-18");
   });
 
+  it("returns initial protocolEra / discoverResult from the client", () => {
+    const discoverResult = {
+      supportedVersions: ["2026-07-28"],
+      serverInfo: SERVER_INFO,
+      capabilities: {},
+    };
+    const client = new FakeInspectorClient({
+      status: "connected",
+      protocolEra: "modern",
+      discoverResult,
+    });
+    const { result } = renderHook(() => useInspectorClient(client));
+    expect(result.current.protocolEra).toBe("modern");
+    expect(result.current.discoverResult).toEqual(discoverResult);
+  });
+
+  it("subscribes to protocolEraChange and discoverResultChange", () => {
+    const client = new FakeInspectorClient();
+    const { result } = renderHook(() => useInspectorClient(client));
+    expect(result.current.protocolEra).toBeUndefined();
+    expect(result.current.discoverResult).toBeUndefined();
+    const discoverResult = {
+      supportedVersions: ["2026-07-28"],
+      serverInfo: SERVER_INFO,
+      capabilities: {},
+    };
+    act(() => {
+      client.setProtocolEra("modern");
+      client.setDiscoverResult(discoverResult);
+    });
+    expect(result.current.protocolEra).toBe("modern");
+    expect(result.current.discoverResult).toEqual(discoverResult);
+  });
+
+  it("resets protocolEra / discoverResult to defaults when client becomes null", () => {
+    const client = new FakeInspectorClient({
+      status: "connected",
+      protocolEra: "modern",
+      discoverResult: {
+        supportedVersions: ["2026-07-28"],
+        serverInfo: SERVER_INFO,
+        capabilities: {},
+      },
+    });
+    const { result, rerender } = renderHook(({ c }) => useInspectorClient(c), {
+      initialProps: { c: client as FakeInspectorClient | null },
+    });
+    expect(result.current.protocolEra).toBe("modern");
+    rerender({ c: null });
+    expect(result.current.protocolEra).toBeUndefined();
+    expect(result.current.discoverResult).toBeUndefined();
+  });
+
   it("connect() and disconnect() proxy to the client and update status", async () => {
     const client = new FakeInspectorClient();
     const { result } = renderHook(() => useInspectorClient(client));