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

Ouverte
#631 2 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
25/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Active
Stack technique
json, php
Domaine
api, backend

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
PHP
Étoiles
1.7k
Forks
206
Merge moyen
1 j 17 h
PR mergées (30 j)
102

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de modelcontextprotocol/php-sdk

Toutes les issues de modelcontextprotocol/php-sdk

Issues similaires

Plus d'issues PHP

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.