mcp-client: normalise union-typed tool parameter schemas to one type before they reach the model

[fbeeg]

Observation

Tool parameter schemas that use a type list (["boolean", "string"]), anyOf or oneOf can silently break some models. Gemini reads a type list as its first type only, so a parameter typed ["boolean","string"] can never be filled with a string. We measured this by reading the last request header of 702 sessions (216 distinct tools): our own tools can be fixed at the source, but MCP servers mounted through dsh-mcp-client are third party, and createMcpToolDefinition passes their inputSchema to the model unchanged (parameters: inputSchema). For example a code-search MCP server declares anyOf [array|string, null] on its main parameters.

Idea

Normalise the MCP inputSchema to one type per node before it reaches the model, and send the arguments to the server unchanged (the narrowed schema accepts a subset of what the server accepts). The rule we run today as an out-of-tree patch:

• type lists lose "null"; if several types remain, pick by preference: string, array, object, number, integer, boolean.
• anyOf / oneOf lose their null branches. If every remaining branch is an object, merge them (union of properties, required is the intersection). Otherwise pick one branch by the same preference. The parent's annotations win.
• enum loses null. allOf and everything else are left alone.
• Recurse into properties, items, additionalProperties and $defs / definitions with a depth bound; a non-object schema is returned as is and the normaliser never throws.

This is a policy decision (it narrows what the model is shown), which is why I am posting it as an idea rather than a bug with a diff. It could also be a per-row option (for example schema: single-type) or apply only for providers known to mishandle unions. If you would like it, I can port it to packages/mcp/mcp-client/src/tools.ts with specs.

[argszero]

This gap is real and the mechanical cause is where the report says it is. I checked it against the current tree:

• packages/mcp/mcp-client/src/tools.ts — createMcpToolDefinition(ctx, { inputSchema: tool.inputSchema, ... }) sets parameters: inputSchema, and syncTools() registers that definition as it is. The server's schema is never compiled.
• packages/core/tools/src/index.ts — schemaOf() destructures parameters off the definition, and that is what the request assembly puts in front of the model. register() does not validate the internal shape of parameters, so a type list, an anyOf or a oneOf reaches the model untouched.

Our own tools can be corrected at the source; an MCP server's inputSchema cannot. So I built the normaliser as an out-of-tree plugin rather than a core patch, since a policy decision about what the model is shown is easier to adopt when a deployment can switch it on and read what it did before it does it:

@argszero/dsh-mcp-schema-normalizer — https://www.npmjs.com/package/@argszero/dsh-mcp-schema-normalizer (source: https://github.com/argszero/dsh-mcp-schema-normalizer)

dsh plugin --profile <name> add @argszero/dsh-mcp-schema-normalizer

- insert:
    - id: mcp-schema-normalizer
      name: '@argszero/dsh-mcp-schema-normalizer'
      config:
        mode: observe      # normalize (default) | observe | off
        servers: [github]  # omitted = every mcp__* tool

How it attaches. It shadows register on the tools service instance — the value behind the traceable view (ctx.get('tools')[Symbol.for('cordis.original')]) — because mcp-client reaches the registry by name lookup at call time and a write to the view would be seen only by the writer. The wrapper captures the register it found at mount and calls that, so it chains with @argszero/dsh-mcp-tool-filter, which uses the same seam (that one decides whether a tool is registered, this one decides what schema).

Because a plugin cannot re-register another plugin's tools, the row has to be listed before the row that connects the servers; when it is mounted afterwards it lists the MCP tools it found already registered and says so, instead of reporting coverage it never had.

Rules implemented (from your patch): a type list loses "null" and reduces by the preference order (string, array, object, number, integer, boolean); anyOf/oneOf lose their null branches; an all-object union merges (union of properties, intersection of required); a union with nothing left is dropped from the node rather than left accepting nothing. Arguments are never touched, and observe mode registers the server's schema unchanged and reports what normalize would have changed.

Two rules of yours I deliberately did not implement, and I would rather say so here than let the README read as complete:

• Picking one branch when a union is not all objects. anyOf: [{"type":"string"},{"type":"number"}] stays a union, and is counted as counters.unionButUnchanged — it is the counter that says the rule set does not cover a deployment's shapes. Picking discards an alternative the server still accepts, so a model that needed the number could no longer send one; I did not want to make that trade on someone else's schemas by default. If you think it should be the default, or should be a pickBranch: true option, I will add it.
• Dropping null from enum. I left enum alone: a type-list or union null is structural, an enum member is a value the server enumerated, and the reported example does not need it.

Evidence. 58 tests against a real cordis context and the real @deepseek-ai/dsh-tools registry (the assertions read what ctx.tools.schemas() projects — the same path the request assembly takes, not an internal representation); 45 defect-injection arms, every one of them caught by the suite (a mutation that survives is a line nothing checks); and the three release lines the peer range claims (0.1.7-rc.2, 0.2.0-rc.2, 0.2.1-alpha.2) each green at 58/58. The tarball a consumer installs was unpacked into a scratch tree and mounted against a real registry as a last check.

If you would rather have this in packages/mcp/mcp-client/src/tools.ts — your offer — the plugin's rule set and its tests are a direct port: the rules are in src/normalize.ts and the registration decision in src/normalizer.ts, and neither depends on anything the plugin owns.