[Capability] Describe nullable parameters with `anyOf` instead of a `type` array?

Offen
#631 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
25/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Aktiv
Tech-Stack
json, php
Bereich
api, backend

Rechercherichtung

Start in SchemaGenerator, where a nullable parameter currently produces a type array such as ["null", "string"]; find the branch that builds that array and the tests covering nullable scalars, enums, arrays and objects. The open question is a design one, so the first deliverable is a maintainer answer on whether anyOf should be default or opt-in before any patch. Done means every nullable parameter shape is covered and existing schema tests are updated alongside the new behaviour.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

For a nullable parameter, SchemaGenerator emits a type array. With mcp/sdk 0.9.0, the ?string $company = null parameter of a tool gets:

{"type": ["null", "string"], "description": "The company of the speaker", "default": null}

MCP Inspector 2 then reports "Schema portability: 0 errors, 1 warning" and suggests {"anyOf": [{"type": "null"}, {"type": "string"}]}. That rule is a warning on purpose (schemaLint.ts, modelcontextprotocol/inspector#2286). The array form is what OpenAI recommends. It only costs portability to clients that map tool schemas onto a dialect with a single type.

What the providers document:

  • OpenAI: "it is possible to emulate an optional parameter by using a union type with null", with "type": ["string", "null"] in the examples. anyOf works too, except at the root.
  • Anthropic: strict tool use supports anyOf, and counts anyOf and type arrays the same in its limit on union types.
  • Gemini: the parameters of a function declaration use "a select subset of an OpenAPI 3.0 schema object". Its type is a single value, with anyOf, nullable and a NULL type. So only the anyOf form maps onto it. parametersJsonSchema takes JSON Schema instead.

Switching to anyOf would change the schema of every nullable parameter, including enums, arrays and objects, and clients that read type wouldn't find it anymore. So I'd rather ask first. Would you take a PR that emits anyOf for nullable parameters, maybe as an option of SchemaGenerator?

Found with the submit_proposal tool of the MCP server of the Symfony showcase app.

Vorherrschende Sprache
PHP
Sterne
1.7k
Forks
206
Ø Merge
1 T. 17 Std.
Gemergte PRs (30 T.)
102

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus modelcontextprotocol/php-sdk

Alle Issues in modelcontextprotocol/php-sdk

Ähnliche Issues

Weitere Issues zu PHP

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.