fix: render tool schemas with root-level anyOf/oneOf composition

AGENTS.md

@@ -186,6 +186,40 @@ v2/main/
 │   │                                   #   and TUI schemaToForm — since each dispatches on
 │   │                                   #   a single `type` string and would otherwise miss
 │   │                                   #   a nullable field entirely — #1928/#2015;
+│   │                                   #   rootUnion.ts: flattens the COMPOSITION keywords a
+│   │                                   #   tool's inputSchema may carry at its ROOT — `allOf`
+│   │                                   #   merged unconditionally (conjunctive, so there is
+│   │                                   #   no choice to present), a root `oneOf`/`anyOf`
+│   │                                   #   returned as the BRANCHES a picker chooses between.
+│   │                                   #   Legal since 2026-07-28 and rendered as an EMPTY
+│   │                                   #   FORM before — no picker, no fields, not even the
+│   │                                   #   raw-JSON fallback a union-typed *property* gets,
+│   │                                   #   so the tool could only be called with empty
+│   │                                   #   arguments. Read by all three clients: web
+│   │                                   #   SchemaForm (the Variant picker + the branch-change
+│   │                                   #   value pruning), TUI schemaToForm (a section per
+│   │                                   #   branch, its fields forced OPTIONAL since only one
+│   │                                   #   alternative applies — and rendered under PREFIXED
+│   │                                   #   names behind a variant select, because ink-form
+│   │                                   #   keys values by field name across the WHOLE form,
+│   │                                   #   so two branches' `kind` would otherwise be one
+│   │                                   #   field; schemaToForm.decodeFormValues translates
+│   │                                   #   back on submit), and convertToolParameters (which
+│   │                                   #   branch's schema types a CLI --tool-arg).
+│   │                                   #   DECLINES rather than half-reads, since keywords at
+│   │                                   #   one level are CONJUNCTIVE and it computes no
+│   │                                   #   intersections: a union whose members are not ALL
+│   │                                   #   field-carrying objects (or whose member `type`
+│   │                                   #   rules objects out), a branch restating a
+│   │                                   #   constraint the root states differently, an allOf
+│   │                                   #   carrying a member it cannot fold in (`false`, a
+│   │                                   #   $ref) — dropping the keyword there would turn an
+│   │                                   #   UNSATISFIABLE schema into a fillable form — and a
+│   │                                   #   schema carrying BOTH oneOf and anyOf. Does not
+│   │                                   #   interpret `not` at all. Declining changes what
+│   │                                   #   RENDERS, never whether the tool takes arguments:
+│   │                                   #   declaresAnyFields counts the raw members, so an
+│   │                                   #   App tool is never auto-invoked with `{}` — #2123;
 │   │                                   #   schemaLint.ts: tool-schema PORTABILITY lint —
 │   │                                   #   constructs that are legal JSON Schema and are
 │   │                                   #   refused or mishandled by real MCP clients (a bare

README.md

@@ -35,8 +35,9 @@ inspector/
 │   │                 #   implementations, the selection policy, and the descriptor the banner and UI report
 │   ├── client/       # Install-level client config (`client.json`): browser-safe parse/validate + Node load/save, remote backend, secrets
 │   ├── json/         # JSON + parameter/argument conversion utilities, the nullable-union
-│   │                 #   schema collapse shared by the web and TUI form builders, and the
-│   │                 #   tool-schema portability lint all three clients report from
+│   │                 #   schema collapse and root-composition flattening shared by the web
+│   │                 #   and TUI form builders, and the tool-schema portability lint all
+│   │                 #   three clients report from
 │   ├── logging/      # Silent pino logger singleton
 │   ├── mcp/          # InspectorClient runtime, state stores, transports, config import,
 │   │                 #   and the RFC 6570 URI-template helpers the web form and TUI expand through
@@ -153,6 +154,7 @@ Each config below is a ready-made server for exercising one feature by hand. Loa
 | `structured-output-http.json`             | Tools tab: a result's `structuredContent` section  | [#1908](https://github.com/modelcontextprotocol/inspector/issues/1908) |
 | `duplicate-tool-names-http.json`          | A `tools/list` that repeats a tool name            | [#1957](https://github.com/modelcontextprotocol/inspector/issues/1957) |
 | `nullable-fields-http.json`               | Tools tab: nullable (`anyOf` + `null`) arguments   | [#1928](https://github.com/modelcontextprotocol/inspector/issues/1928) |
+| `root-union-schemas-http.json` **(legacy era)** | Tool schemas whose arguments are a root `anyOf` / `oneOf` | [#2123](https://github.com/modelcontextprotocol/inspector/issues/2123) |
 | `unportable-schemas-http.json` **(legacy era)** | Tool schemas a real client rejects, flagged in all three clients | [#1005](https://github.com/modelcontextprotocol/inspector/issues/1005) |
 | `rfc6570-templates-http.json`             | Resources tab: RFC 6570 resource-template expansion | [#1919](https://github.com/modelcontextprotocol/inspector/issues/1919) |
 | `advertised-extensions-http.json`         | Tool registration gated on advertised extensions    | [#1739](https://github.com/modelcontextprotocol/inspector/issues/1739) |
@@ -288,6 +290,34 @@ Open the Tools tab and select `record_shipment`: `direction` must render as a **
 
 The **TUI** had the same gap and is worth checking against the same server (`--tui`, then test `record_shipment`): `direction` is a select, `quantity` an integer field, `express` a boolean. Both clients now share one collapse step — `normalizeNullableUnion` in [`core/json/nullableUnion.ts`](./core/json/nullableUnion.ts) — precisely so they cannot drift on which schemas they can render.
 
+#### Root-level unions
+
+`root-union-schemas-http.json` serves two tools whose arguments are declared as a **composition at the root** of `inputSchema` rather than as a flat `properties` map — `echo` with an `anyOf` beside its own `message` property, and `get_weather` with an OpenAPI-style `discriminator` over a `oneOf`. Plain streamable-HTTP — connect with the **default (legacy)** protocol era.
+
+The 2026-07-28 revision makes this shape explicitly legal: `type: "object"` is required at the root, and beyond that "any JSON Schema 2020-12 keyword may appear alongside `type`, including composition keywords (`oneOf`, `anyOf`, `allOf`, `not`)".
+
+Open the Tools tab and select `echo`. Above the fields is a **Variant** picker listing the union's alternatives — labelled from each branch's `title`, else its discriminator `const`, else its position — and choosing one swaps in that branch's fields with the discriminator already filled in. On the broken build both tools rendered **nothing but the Execute Tool button**: no picker, no fields, not even the raw-JSON editor a union-typed _property_ falls back to, so neither tool could be called with anything but empty arguments ([#2123](https://github.com/modelcontextprotocol/inspector/issues/2123)).
+
+Switching branches drops the values that belonged to the outgoing one. They are no longer on screen, so the user can neither see nor clear them, and submitting them would describe a shape the call is not making.
+
+The **TUI** has the same gap and is worth checking against the same server (`--tui`, then test `echo`). ink-form is static — there is no picker to hide the alternatives behind — so each branch becomes its own **section**, preceded by a **Variant** select naming which one the call means. The fields in a branch section are rendered optional whatever the branch says: only one alternative applies to a call, so requiring them would build a form that can never be submitted.
+
+The sections are not as independent as they look, which is why the select is not cosmetic: ink-form keeps one value object for the whole form, keyed by field name alone, so two branches both declaring `kind` would be **one** field and the later section's initial value would decide what the earlier one submits. Each branch's fields are therefore rendered under a prefixed name and translated back on submit, where every branch but the chosen one is dropped.
+
+The **CLI** has no form at all, but the same flattening decides how `--tool-arg` values are typed: a branch's `count: { "type": "number" }` is what turns `--tool-arg count=3` into `3` rather than `"3"`. Which branch is *inferred* rather than chosen — a discriminated union pins its discriminator with `const`, so the supplied arguments either identify one branch or they do not. When nothing identifies one, only the names every branch that declares them types the same way are coerced; a name one branch calls a number and another a boolean is passed through as the string it was typed as, rather than run through an arbitrary branch's schema.
+
+All three read one helper, [`core/json/rootUnion.ts`](./core/json/rootUnion.ts), so they cannot drift on which schemas they can render.
+
+What it declines to flatten is as deliberate as what it flattens, and every case falls back to whatever the schema's own `properties` describe rather than claiming something untrue:
+
+- **A union whose members are not all field-carrying object schemas** — including one whose member `type` rules objects out, since tool arguments are a JSON object and such a member can never match. A picker whose options render nothing is no better than no picker.
+- **A branch that restates a constraint the root already states.** The two are conjunctive, so root `minimum: 10` under branch `minimum: 0` is still 10, disjoint `enum`s leave nothing satisfiable, and `type: "string"` under `type: "number"` describes a value that cannot exist — rendering either side would accept what the schema rejects. A property both declare *compatibly* is merged rather than replaced, so a root's `minimum` survives a branch's `maximum`, and a disagreement about `title`/`description` is not a conflict at all.
+- **An `allOf` with a member it cannot fold in** — JSON Schema's boolean form (`allOf: [false, …]` admits nothing) or a `$ref`, whose constraints are unknown rather than absent. Merging the rest and dropping the keyword would turn an unsatisfiable schema into a fillable form.
+- **A schema carrying both `oneOf` and `anyOf`** — independent keywords a value satisfies *together*, not two spellings of one union, so reading one and dropping the other omits real constraints while looking complete. Satisfying both honestly means the cross product of their alternatives, which no real schema has yet asked for.
+- **`not`**, which is not interpreted at all: there is no faithful form for "anything except this".
+
+Declining changes what *renders*, never whether the tool is treated as taking arguments: a declined union still has fields, so an App tool carrying one still asks for them rather than auto-invoking with `{}`.
+
 #### Unportable tool schemas
 
 `unportable-schemas-http.json` serves four tools, three of whose advertised