Tools: x-mcp-header annotation tooling + -32602 unknown-tool rendering (#1632) (#1735)

* Tools: x-mcp-header annotation tooling + -32602 unknown-tool rendering (#1632)

Card 9/10 of the SDK-v2 + New Spec stack. Adds SEP-2243 `x-mcp-header`
tooling to the Tools tab and adjusts result rendering for SDK v2's
unknown-tool behavior, and bumps the SDK to 2.0.0-beta.5.

- **`core/json/xMcpHeader.ts`**: a faithful port of the SDK's (non-public)
  `scanXMcpHeaderDeclarations` — validates every SEP-2243 constraint
  (primitive types incl. `number`, RFC 9110 token, case-insensitive
  uniqueness, statically-reachable `properties`-only chain) and derives the
  mirrored `Mcp-Param-{Name}` params for a kept tool.

- **Excluded tools**: the SDK silently drops tools with invalid annotations
  from `tools/list`. InspectorClient now re-lists the RAW (unfiltered) list
  and scans it to recompute the excluded set with reasons — gated to the
  modern non-stdio era (matching the SDK's gate), recomputed on every
  aggregate refresh, surfaced via a new `excludedToolsChange` event +
  `getExcludedTools()` and `useInspectorClient().excludedTools`. The Tools
  sidebar lists them struck-through under an "Excluded (SEP-2243)" divider
  with the reason on hover.

- **Mirrored args**: ToolDetailPanel shows a "Mirrored request headers"
  section listing each arg → `Mcp-Param-{Name}` (with the browser-omits note).

- **-32602 rendering**: SDK v2 rejects an unknown-tool call with `-32602`
  instead of an `isError` result, which previously rendered nothing. New
  ToolCallErrorPanel renders a thrown tool-call error, with a targeted
  "Unknown Tool" hint for `-32602`.

Adds unit + Storybook + integration coverage (a real modern server with an
invalid-header tool fixture) for every path. `npm run ci`-equivalent checks
green.

Closes #1632

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

* test-servers: x-mcp-header modern showcase config + preset (#1632)

Register the `invalid_header_tool` fixture as a preset and add
`xmcpheader-modern-http.json` — a modern HTTP showcase serving echo, a
valid-header `get_weather`, and the invalid-header tool — so the Tools-tab
x-mcp-header tooling (mirrored headers, excluded-tools surface, -32602
rendering) can be exercised manually. Documented in the README alongside the
other per-SEP showcase configs. Smoke-tested end to end in the web client.

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

* docs: add #1632 proof screenshots to pr-screenshots

End-to-end web-client verification of the x-mcp-header Tools tooling against
the modern showcase server: excluded-tools surface + reason, mirrored-headers
section, and the -32602 unknown-tool error panel.

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

* Respond to review: disambiguate -32602, doc/search nits (#1632)

Addresses the review on PR #1735:

1. -32602 "Unknown Tool" mislabel: `-32602` is generic Invalid params, so a
   known tool called with bad arguments hit the same code and rendered under
   the definitive "Unknown Tool" heading. Replace `isUnknownToolError` with
   `classifyToolCallError(code, message)` → "unknown-tool" only when the
   message names it (not found / unknown tool / …), else "invalid-params"
   (new "Invalid Parameters" heading + schema hint), else "generic".

2. Double pagination walk: expand the `listAllTools` comment to document that
   the excluded-tools recompute is a deliberately un-cached second raw walk
   (doubles list round-trips on modern non-stdio, runs even on a cache-served
   aggregate) — accepted for a debugging tool, no-op on legacy/stdio.

3. Doc nit: `scanXMcpHeaderDeclarations` no longer claims to visit "$ref
   targets" — reworded to note `$ref` is never followed (refs resolve into the
   unreachable `$defs` body).

4. Search nit: the excluded-list filter now matches name AND title, matching
   the main tools filter.

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

* Tighten unknown-tool matcher to be tool-scoped (#1632 re-review nit)

The re-review noted the -32602 disambiguation was symmetric: broad markers
("does not exist", "unrecognized") could inversely mislabel a genuine
invalid-params message (e.g. "property 'region' does not exist") as "Unknown
Tool". Scope the not-found/does-not-exist family to require the word "tool" in
the same clause (matching the SDK's "Tool <name> not found"); keep "unknown
tool" / "no such tool" as standalone unambiguous markers. Adds a
tool-less-"does not exist" test asserting it classifies as invalid-params.

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

* Add trigger_invalid_params showcase tool + Invalid Parameters screenshot (#1632)

Adds a `trigger_invalid_params` spec-error trigger to the modern showcase
server: the injector answers its `tools/call` with a real `-32602 Invalid
params` JSON-RPC error whose message does NOT name an unknown tool. This lets
the "Invalid Parameters" branch of the tool-call error panel (added in the
review response) be exercised live, distinct from the unknown-tool `-32602`.

- `SPEC_ERROR_TRIGGERS` gains the `trigger_invalid_params` entry (HTTP 200,
  in-band -32602) + preset registration.
- Enable `injectSpecErrors` on `xmcpheader-modern-http.json` and add the tool.
- README + pr-screenshots README document it; adds the live "Invalid
  Parameters" proof screenshot.

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

@@ -16,7 +16,9 @@ import type {
   InspectorClientOptions,
   PendingRequestOrigin,
   ResourceSubscriptionStreamState,
+  ExcludedTool,
 } from "./types.js";
+import { scanXMcpHeaderDeclarations } from "../json/xMcpHeader.js";
 // Re-export so v1.5 tests that do `import { InspectorClientOptions } from
 // "@inspector/core/mcp/inspectorClient.js"` keep resolving.
 export type {
@@ -342,6 +344,10 @@ export class InspectorClient extends InspectorClientEventTarget {
   // probed/pinned connection (undefined on a plain legacy connect).
   private protocolEra?: ProtocolEra;
   private discoverResult?: DiscoverResult;
+  // Tools the SDK excludes from `tools/list` for invalid `x-mcp-header`
+  // annotations (SEP-2243), recomputed on every aggregate tools refresh and
+  // surfaced so the Tools tab can show why a tool vanished (#1632).
+  private excludedTools: ExcludedTool[] = [];
   // The capabilities this Inspector client advertises to the server during the
   // initialize handshake. Built once in setupClient() and snapshotted here so
   // UI surfaces (Server Info modal) can display them without poking at the
@@ -1661,6 +1667,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     this.protocolVersion = undefined;
     this.protocolEra = undefined;
     this.discoverResult = undefined;
+    this.excludedTools = [];
     // Drop the modern per-request log-level opt-in so it doesn't leak into the
     // next connection's `_meta` (#1629).
     this.modernLogLevel = undefined;
@@ -1675,6 +1682,7 @@ export class InspectorClient extends InspectorClientEventTarget {
     this.dispatchTypedEvent("protocolVersionChange", this.protocolVersion);
     this.dispatchTypedEvent("protocolEraChange", this.protocolEra);
     this.dispatchTypedEvent("discoverResultChange", this.discoverResult);
+    this.dispatchTypedEvent("excludedToolsChange", this.excludedTools);
   }
 
   /**
@@ -2564,9 +2572,73 @@ export class InspectorClient extends InspectorClientEventTarget {
         this.getCacheableRequestOptions(options?.cacheMode),
       ),
     );
+    // Recompute the SEP-2243 excluded-tools set alongside the aggregate. The
+    // SDK already filtered `response.tools`, so it can't tell us what it
+    // dropped — {@link refreshExcludedTools} re-lists the RAW `tools/list` to
+    // find out. This is a SECOND, deliberately un-cached walk: on a modern
+    // non-stdio connection it roughly doubles the list round-trips per refresh
+    // (and runs even when the aggregate above was served from cache), because
+    // the raw per-page path has no response cache and the excluded set must
+    // reflect the current wire truth. Accepted for a debugging tool where the
+    // list is small and correctness of "why did this tool vanish" matters more
+    // than the extra request; it's a no-op (no round trip) on legacy/stdio.
+    // Kept best-effort: an error here must never fail the tools list itself.
+    await this.refreshExcludedTools(options?.metadata).catch(() => {});
     return { tools: [...response.tools] };
   }
 
+  /**
+   * Whether this connection excludes tools with invalid `x-mcp-header`
+   * annotations from `tools/list`, matching the SDK's gate: only the modern
+   * (2026-07-28) era on a non-stdio (Streamable HTTP / SSE) transport. Legacy
+   * and stdio keep such tools in the list, so there is nothing to surface.
+   */
+  private excludesInvalidXMcpHeaderTools(): boolean {
+    return this.isModernEra() && this.getServerType() !== "stdio";
+  }
+
+  /** The current SEP-2243 excluded-tools set (empty on legacy/stdio). */
+  getExcludedTools(): ExcludedTool[] {
+    return this.excludedTools;
+  }
+
+  /**
+   * Recompute the tools the SDK excludes from `tools/list` for invalid
+   * `x-mcp-header` annotations (SEP-2243), and emit `excludedToolsChange`.
+   * Returns `[]` without any round trip on connections that don't exclude
+   * (legacy/stdio). Otherwise walks every page of the RAW `tools/list` (which,
+   * unlike the SDK's high-level `listTools()`, is NOT filtered) and keeps the
+   * tools whose annotation scan fails, each with its reason. A repeating cursor
+   * stops the walk (non-converging-server guard, mirroring the SDK).
+   */
+  async refreshExcludedTools(
+    metadata?: Record<string, string>,
+  ): Promise<ExcludedTool[]> {
+    const excluded: ExcludedTool[] = [];
+    // Gated to connections that actually exclude; otherwise this is a pure
+    // no-op (no round trip). The raw `listTools` below guards the connection.
+    if (this.excludesInvalidXMcpHeaderTools()) {
+      const seenCursors = new Set<string>();
+      let cursor: string | undefined;
+      do {
+        const page = await this.listTools(cursor, metadata);
+        for (const tool of page.tools) {
+          const scan = scanXMcpHeaderDeclarations(tool.inputSchema);
+          if (!scan.valid) excluded.push({ tool, reason: scan.reason });
+        }
+        cursor = page.nextCursor;
+        if (cursor !== undefined) {
+          /* v8 ignore next -- defensive: a spec-compliant server never repeats a cursor; this guards a non-converging server from an infinite walk (mirrors the SDK's drainList guard) */
+          if (seenCursors.has(cursor)) break;
+          seenCursors.add(cursor);
+        }
+      } while (cursor !== undefined);
+    }
+    this.excludedTools = excluded;
+    this.dispatchTypedEvent("excludedToolsChange", excluded);
+    return excluded;
+  }
+
   /**
    * Call a tool. Caller must provide the Tool (e.g. from a state manager).
    * @param tool The tool to call (use tool.name for the request)