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

Aperta
#631 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
json, php
Ambito
api, backend

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.

Lingua principale
PHP
Stelle
1.7k
Fork
206
Merge medio
1g 17h
PR unite (30g)
102

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di modelcontextprotocol/php-sdk

Tutte le issue di modelcontextprotocol/php-sdk

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.