Namespaces

Classes

Interfaces

1: <?php
2:
3: declare(strict_types=1);
4:
5: /**
6: * This file is part of the Nexus MCP SDK package.
7: *
8: * (c) 2026 John Paul E. Balandan, CPA <paulbalandan@gmail.com>
9: *
10: * For the full copyright and license information, please view
11: * the LICENSE file that was distributed with this source code.
12: */
13:
14: namespace Nexus\Mcp\Core\Schema\Elicitation;
15:
16: use Nexus\Assert\Assert;
17: use Nexus\Mcp\Core\Schema\Arrayable;
18:
19: /**
20: * Schema for multiple-selection enumeration with display titles for each option.
21: *
22: * @implements Arrayable<array{
23: * type: 'array',
24: * items: array{anyOf: list<template-type<EnumOption, Arrayable, 'T'>>},
25: * title?: non-empty-string,
26: * description?: non-empty-string,
27: * minItems?: int<0, max>,
28: * maxItems?: int<0, max>,
29: * default?: list<string>,
30: * }>
31: *
32: * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#titledmultiselectenumschema
33: */
34: final readonly class TitledMultiSelectEnumSchema implements Arrayable, MultiSelectEnumSchema
35: {
36: public const string TYPE = 'array';
37:
38: /**
39: * @var list<EnumOption>
40: */
41: public array $items;
42:
43: /**
44: * @var null|non-empty-string
45: */
46: public ?string $title;
47:
48: /**
49: * @var null|non-empty-string
50: */
51: public ?string $description;
52:
53: /**
54: * @var null|list<string>
55: */
56: public ?array $default;
57:
58: /**
59: * @param list<EnumOption> $items The inner `anyOf` list of `{const, title}` pairs
60: * @param null|list<string> $default
61: */
62: public function __construct(
63: array $items,
64: ?string $title = null,
65: ?string $description = null,
66: public ?int $minItems = null,
67: public ?int $maxItems = null,
68: ?array $default = null,
69: ) {
70: Assert::that($items)
71: ->isList('titled multi-select enum schema "items" must be a list, non-list array given.')
72: ->values()->isInstanceOf(EnumOption::class, 'each titled multi-select enum schema "items" must be an enum option, {type} given.')
73: ;
74: Assert::that($title)->nullOr()->isNonEmptyString('titled multi-select enum schema "title" must be a non-empty string or null.');
75: Assert::that($description)->nullOr()->isNonEmptyString('titled multi-select enum schema "description" must be a non-empty string or null.');
76: Assert::that($minItems)->nullOr()->isNaturalInt('titled multi-select enum schema "minItems" must be a non-negative integer or null.');
77: Assert::that($maxItems)->nullOr()->isNaturalInt('titled multi-select enum schema "maxItems" must be a non-negative integer or null.');
78:
79: if (null !== $default) {
80: Assert::that($default)
81: ->isList('titled multi-select enum schema "default" must be a list, non-list array given.')
82: ->values()->isString('each titled multi-select enum schema "default" must be a string.')
83: ;
84: }
85:
86: $this->items = $items;
87: $this->title = $title;
88: $this->description = $description;
89: $this->default = $default;
90: }
91:
92: /**
93: * @param array<string, mixed> $data
94: */
95: #[\Override]
96: public static function fromArray(array $data): static
97: {
98: Assert::that($data)->hasOffset('type', 'titled multi-select enum schema missing the required "type" key.');
99: $type = $data['type'];
100: Assert::that($type)->isIdentical(self::TYPE, 'titled multi-select enum schema "type" must be {other}, {value} given.');
101:
102: Assert::that($data)->hasOffset('items', 'titled multi-select enum schema missing the required "items" key.');
103: Assert::that($data['items'])
104: ->isArray('titled multi-select enum schema "items" must be an object, {type} given.')
105: ->isMap('titled multi-select enum schema "items" must be a string-keyed object.')
106: ;
107:
108: $anyOf = $data['items']['anyOf'] ?? null;
109: Assert::that($anyOf)
110: ->isArray('titled multi-select enum schema "items.anyOf" must be a list, {type} given.')
111: ->isList('titled multi-select enum schema "items.anyOf" must be a list, non-list array given.')
112: ->values()
113: ->isArray('each titled multi-select enum schema "items.anyOf" must be an object, {type} given.')
114: ->isMap('each titled multi-select enum schema "items.anyOf" must be a string-keyed object.')
115: ;
116: $items = array_map(EnumOption::fromArray(...), $anyOf);
117:
118: $title = $data['title'] ?? null;
119: Assert::that($title)->nullOr()->isString('titled multi-select enum schema "title" must be a string or null, {type} given.');
120:
121: $description = $data['description'] ?? null;
122: Assert::that($description)->nullOr()->isString('titled multi-select enum schema "description" must be a string or null, {type} given.');
123:
124: $minItems = $data['minItems'] ?? null;
125: Assert::that($minItems)->nullOr()->isInt('titled multi-select enum schema "minItems" must be an int or null, {type} given.');
126:
127: $maxItems = $data['maxItems'] ?? null;
128: Assert::that($maxItems)->nullOr()->isInt('titled multi-select enum schema "maxItems" must be an int or null, {type} given.');
129:
130: $default = null;
131:
132: if (isset($data['default'])) {
133: Assert::that($data['default'])
134: ->isList('titled multi-select enum schema "default" must be a list, non-list array given.')
135: ->values()->isString('each titled multi-select enum schema "default" must be a string, {type} given.')
136: ;
137: $default = $data['default'];
138: }
139:
140: return new self($items, $title, $description, $minItems, $maxItems, $default);
141: }
142:
143: #[\Override]
144: public function toArray(): array
145: {
146: $data = [
147: 'type' => self::TYPE,
148: 'items' => [
149: 'anyOf' => array_map(static fn(EnumOption $o): array => $o->toArray(), $this->items),
150: ],
151: ];
152:
153: if (null !== $this->title) {
154: $data['title'] = $this->title;
155: }
156:
157: if (null !== $this->description) {
158: $data['description'] = $this->description;
159: }
160:
161: if (null !== $this->minItems) {
162: $data['minItems'] = $this->minItems;
163: }
164:
165: if (null !== $this->maxItems) {
166: $data['maxItems'] = $this->maxItems;
167: }
168:
169: if (null !== $this->default) {
170: $data['default'] = $this->default;
171: }
172:
173: return $data;
174: }
175:
176: #[\Override]
177: public function jsonSerialize(): array
178: {
179: return $this->toArray();
180: }
181: }
182:
Nexus MCP SDK API documentation generated by ApiGen dev-master