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/integration/mcp/inspectorClient.test.ts

@@ -746,12 +746,44 @@ describe("InspectorClient", () => {
 
       expect(client.getProtocolVersion()).toBeUndefined();
       await client.connect();
-      // stdio transports don't store the version themselves; the capture
-      // happens in MessageTrackingTransport, so this also guards that path.
+      // The SDK Client's getNegotiatedProtocolVersion() supplies the version
+      // for both eras.
       expect(client.getProtocolVersion()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      // A legacy connect reports the legacy era; there is no server/discover
+      // result without a probe.
+      expect(client.getProtocolEra()).toBe("legacy");
+      expect(client.getDiscoverResult()).toBeUndefined();
 
       await client.disconnect();
       expect(client.getProtocolVersion()).toBeUndefined();
+      expect(client.getProtocolEra()).toBeUndefined();
+      expect(client.getDiscoverResult()).toBeUndefined();
+    });
+
+    it("negotiates the legacy era under versionNegotiation 'auto' against a legacy server (stdio)", async () => {
+      client = new InspectorClient(
+        {
+          type: "stdio",
+          command: serverCommand.command,
+          args: serverCommand.args,
+        },
+        {
+          environment: { transport: createTransportNode },
+          // Auto probes server/discover, then falls back to the initialize
+          // handshake on this legacy test server — so the negotiated era is
+          // legacy and getProtocolEra() reports it (vs. undefined on a plain
+          // legacy connect).
+          versionNegotiation: { mode: "auto" },
+        },
+      );
+
+      await client.connect();
+      expect(client.getProtocolEra()).toBe("legacy");
+      expect(client.getProtocolVersion()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      // A legacy server has no server/discover result even when probed.
+      expect(client.getDiscoverResult()).toBeUndefined();
+
+      await client.disconnect();
     });
 
     it("should not auto-fetch server contents when disabled", async () => {

clients/web/src/test/integration/mcp/remote/server-extra-coverage.test.ts

@@ -424,6 +424,11 @@ describe("server.ts supplemental coverage", () => {
       expect((await res.json()).error).toMatch(/roots/);
     });
 
+    it("rejects an unknown protocolEra", async () => {
+      const res = await postSettings({ ...base, protocolEra: "future" });
+      expect((await res.json()).error).toMatch(/protocolEra/);
+    });
+
     it("accepts a fully-populated valid settings payload", async () => {
       const res = await postSettings({
         ...base,
@@ -432,6 +437,7 @@ describe("server.ts supplemental coverage", () => {
         taskTtl: 1000,
         autoRefreshOnListChanged: true,
         maxFetchRequests: 5,
+        protocolEra: "modern",
         oauthClientId: "cid",
         oauthScopes: "a b",
         enterpriseManaged: true,
@@ -467,6 +473,8 @@ describe("server.ts supplemental coverage", () => {
               requestTimeout: -1,
               taskTtl: "x",
               maxFetchRequests: -1,
+              // unknown era literal → isProtocolEra branch
+              protocolEra: "future",
               // enterpriseManaged non-boolean → isOauthObject inner branch
               oauth: { enterpriseManaged: "yes" },
               // a non-string `name` → isRootArray inner branch
@@ -494,6 +502,7 @@ describe("server.ts supplemental coverage", () => {
           "requestTimeout",
           "taskTtl",
           "maxFetchRequests",
+          "protocolEra",
           "oauth",
           "roots",
         ]) {

clients/web/src/test/integration/mcp/remote/servers-route.test.ts

@@ -1045,6 +1045,8 @@ describe("/api/servers routes", () => {
               connectionTimeout: "30s",
               // Good: valid number
               requestTimeout: 60000,
+              // Good: valid era literal → round-trips
+              protocolEra: "modern",
               // Bad: array instead of object → drop
               oauth: ["not", "an", "object"],
               // Bad: entry missing a string `uri` → drop the whole roots field
@@ -1063,6 +1065,7 @@ describe("/api/servers routes", () => {
       // Good fields survive.
       expect(fetched.headers).toEqual({ "X-Keep": "yes" });
       expect(fetched.requestTimeout).toBe(60000);
+      expect(fetched.protocolEra).toBe("modern");
       // Bad fields are dropped.
       expect(fetched).not.toHaveProperty("metadata");
       expect(fetched).not.toHaveProperty("connectionTimeout");