Skip to content

Commit fb2c8c2

Browse files
e0ipsoDDEV User
e0ipso
and
DDEV User
authored
[Schema][Server] Add top-level title to Tool (#288)
* feat(schema): add top-level title to Tool Mirror PR #278's Prompt change for Tool: - Add optional ?string $title to Mcp\Schema\Tool between $name and $inputSchema. fromArray() now reads $data['title']; jsonSerialize() emits 'title' right after 'name'. The @phpstan-type ToolData gains title?: string. - Add ?string $title to the #[McpTool] attribute between $name and $description. - Note ToolAnnotations::$title as deprecated-for-display in favor of Tool::$title per MCP spec 2025-06-18 (PHPDoc only, field retained for BC). Phase 1 of plan 01--tool-title-spec-compliance. Later phases update Discoverer, Builder::addTool(), ArrayLoader, and the conformance fixture to match the new signature. * feat(server): thread title through discovery - Discoverer::processMethod() now propagates McpTool::$title into every discovered Tool via named arguments. - Builder::addTool() accepts ?string $title between $name and $description. [BC Break] positional callers passing the old $description as 3rd positional argument must switch to named arguments, matching the precedent set for addPrompt() in 0.5.0. - tests/Conformance/server.php migrated to named-argument form for every addTool() call. Phase 2 of plan 01--tool-title-spec-compliance. * feat(loader): forward title in ArrayLoader ArrayLoader now reads 'title' from each tool config entry and passes it into the Tool constructor, completing the wiring from Builder::addTool() through array-driven registration. The $tools @param array-shape typedef gains title: ?string between name and description. Phase 3 of plan 01--tool-title-spec-compliance. * test(schema): cover Tool.title end-to-end - New tests/Unit/Schema/ToolTest.php: constructor round-trip, jsonSerialize key-order when title set vs null, fromArray tolerance. - New tests/Unit/Capability/Discovery/DiscovererToolTitleTest plus a TitleFixture class verifying McpTool(title: ...) propagates through discovery into the registered Tool. - New tests/Unit/Capability/Registry/Loader/ArrayLoader... test verifying array-driven title propagation. - Extend McpToolTest for title named-arg and default-null. - Extend BuilderTest with addTool(title: 't') propagation. - Update tests/Unit/.../RegistryTest, CallToolHandlerTest, ListToolsHandlerTest and examples/.../server.php new Tool(...) call sites to pass title (named args) so they match the new constructor signature. - CHANGELOG 0.6.0 section: feature bullet + [BC Break] note for addTool() signature, mirroring 0.5.0 Prompt entries. - docs/server-builder.md: addTool() row and prose now list title? between name and description. Phase 4 of plan 01--tool-title-spec-compliance. All 730 phpunit tests pass; remaining phpstan warnings are pre-existing and unrelated to Tool.title. * refactor(schema): make Tool.title non-BC-breaking Move `title` to the end of the Tool, Builder::addTool, and McpTool attribute constructors with a default of null. This preserves positional-argument compatibility and removes the need for `title: null` boilerplate at call sites. JSON serialization order (name, title, inputSchema, ...) is unchanged. Also tighten the new tests: parameterize ToolTest with data providers, fold the Discoverer title fixture into the existing DiscoverableToolHandler, and drop the reflection-heavy Builder test that overlapped with ArrayLoaderToolTitleTest. * fix: move title after name --------- Co-authored-by: DDEV User <nobody@example.com>
1 parent 97979ec commit fb2c8c2

22 files changed

Lines changed: 262 additions & 42 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ All notable changes to `mcp/sdk` will be documented in this file.
1414
* Add OAuth 2.0 Dynamic Client Registration middleware (RFC 7591)
1515
* Add optional `title` field to `Prompt` and `McpPrompt` for MCP spec compliance
1616
* [BC Break] `Builder::addPrompt()` signature changed — `$title` parameter added between `$name` and `$description`. Callers using positional arguments for `$description` must switch to named arguments.
17+
* Add optional `title` field to `Tool` and `McpTool` for MCP spec compliance
18+
* [BC Break] `Tool::__construct()` signature changed — `$title` parameter added between `$name` and `$inputSchema`. Callers using positional arguments must switch to named arguments or pass `null` for `$title`.
19+
* [BC Break] `McpTool` attribute signature changed — `$title` parameter added between `$name` and `$description`. Callers using positional arguments for `$description` must switch to named arguments.
20+
* [BC Break] `Builder::addTool()` signature changed — `$title` parameter added between `$name` and `$description`. Callers using positional arguments for `$description` must switch to named arguments.
1721

1822
0.4.0
1923
-----

‎docs/server-builder.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,7 @@ $server = Server::builder()
278278

279279
- `handler` (callable|string): The tool handler
280280
- `name` (string|null): Optional tool name
281+
- `title` (string|null): Optional human-readable title for display in UI
281282
- `description` (string|null): Optional tool description
282283
- `annotations` (ToolAnnotations|null): Optional annotations for the tool
283284
- `inputSchema` (array|null): Optional input schema for the tool
@@ -578,7 +579,7 @@ $server = Server::builder()
578579
| `addRequestHandlers()` | handlers | Prepend multiple custom request handlers |
579580
| `addNotificationHandler()` | handler | Prepend a single custom notification handler |
580581
| `addNotificationHandlers()` | handlers | Prepend multiple custom notification handlers |
581-
| `addTool()` | handler, name?, description?, annotations?, inputSchema? | Register tool |
582+
| `addTool()` | handler, name?, title?, description?, annotations?, inputSchema?, ... | Register tool |
582583
| `addResource()` | handler, uri, name?, description?, mimeType?, size?, annotations? | Register resource |
583584
| `addResourceTemplate()` | handler, uriTemplate, name?, description?, mimeType?, annotations? | Register resource template |
584585
| `addPrompt()` | handler, name?, description? | Register prompt |

‎docs/server-client-communication.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ use Mcp\Server\RequestContext;
2424

2525
class MyService
2626
{
27-
#[McpTool('my_tool', 'My Tool Description')]
27+
#[McpTool(name: 'my_tool', description: 'My Tool Description')]
2828
public function myTool(RequestContext $context): string
2929
{
3030
$context->getClientGateway()->log(...);

‎examples/server/client-communication/ClientAwareService.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ public function __construct(
2828
/**
2929
* @return array{incident: string, recommended_actions: string, model: string}
3030
*/
31-
#[McpTool('coordinate_incident_response', 'Coordinate an incident response with logging, progress, and sampling.')]
31+
#[McpTool(name: 'coordinate_incident_response', description: 'Coordinate an incident response with logging, progress, and sampling.')]
3232
public function coordinateIncident(RequestContext $context, string $incidentTitle): array
3333
{
3434
$clientGateway = $context->getClientGateway();

‎examples/server/custom-method-handlers/server.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
$toolDefinitions = [
2626
'say_hello' => new Tool(
2727
name: 'say_hello',
28+
title: null,
2829
inputSchema: [
2930
'type' => 'object',
3031
'properties' => [
@@ -37,6 +38,7 @@
3738
),
3839
'sum' => new Tool(
3940
name: 'sum',
41+
title: null,
4042
inputSchema: [
4143
'type' => 'object',
4244
'properties' => [

‎examples/server/elicitation/ElicitationHandlers.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ public function __construct(
4545
*
4646
* @return array{status: string, message: string, booking?: array{party_size: int, date: string, dietary: string}}
4747
*/
48-
#[McpTool('book_restaurant', 'Book a restaurant reservation, collecting details via elicitation.')]
48+
#[McpTool(name: 'book_restaurant', description: 'Book a restaurant reservation, collecting details via elicitation.')]
4949
public function bookRestaurant(RequestContext $context, string $restaurantName): array
5050
{
5151
if (!$context->getClientGateway()->supportsElicitation()) {
@@ -156,7 +156,7 @@ enumNames: ['None', 'Vegetarian', 'Vegan', 'Gluten-Free', 'Halal', 'Kosher'],
156156
*
157157
* @return array{status: string, message: string}
158158
*/
159-
#[McpTool('confirm_action', 'Request user confirmation before proceeding with an action.')]
159+
#[McpTool(name: 'confirm_action', description: 'Request user confirmation before proceeding with an action.')]
160160
public function confirmAction(RequestContext $context, string $actionDescription): array
161161
{
162162
if (!$context->getClientGateway()->supportsElicitation()) {
@@ -224,7 +224,7 @@ public function confirmAction(RequestContext $context, string $actionDescription
224224
*
225225
* @return array{status: string, message: string, feedback?: array{rating: string, comments: string}}
226226
*/
227-
#[McpTool('collect_feedback', 'Collect user feedback via elicitation form.')]
227+
#[McpTool(name: 'collect_feedback', description: 'Collect user feedback via elicitation form.')]
228228
public function collectFeedback(RequestContext $context, string $topic): array
229229
{
230230
if (!$context->getClientGateway()->supportsElicitation()) {

‎src/Capability/Attribute/McpTool.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ class McpTool
2222
{
2323
/**
2424
* @param string|null $name The name of the tool (defaults to the method name)
25+
* @param string|null $title Optional human-readable title for display in UI
2526
* @param string|null $description The description of the tool (defaults to the DocBlock/inferred)
2627
* @param ToolAnnotations|null $annotations Optional annotations describing tool behavior
2728
* @param ?Icon[] $icons Optional list of icon URLs representing the tool
@@ -30,6 +31,7 @@ class McpTool
3031
*/
3132
public function __construct(
3233
public ?string $name = null,
34+
public ?string $title = null,
3335
public ?string $description = null,
3436
public ?ToolAnnotations $annotations = null,
3537
public ?array $icons = null,

‎src/Capability/Discovery/Discoverer.php‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -231,13 +231,14 @@ private function processMethod(\ReflectionMethod $method, array &$discoveredCoun
231231
$inputSchema = $this->schemaGenerator->generate($method);
232232
$outputSchema = $this->schemaGenerator->generateOutputSchema($method);
233233
$tool = new Tool(
234-
$name,
235-
$inputSchema,
236-
$description,
237-
$instance->annotations,
238-
$instance->icons,
239-
$instance->meta,
240-
$outputSchema,
234+
name: $name,
235+
title: $instance->title,
236+
inputSchema: $inputSchema,
237+
description: $description,
238+
annotations: $instance->annotations,
239+
icons: $instance->icons,
240+
meta: $instance->meta,
241+
outputSchema: $outputSchema,
241242
);
242243
$tools[$name] = new ToolReference($tool, [$className, $methodName], false);
243244
++$discoveredCount['tools'];

‎src/Capability/Registry/Loader/ArrayLoader.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ final class ArrayLoader implements LoaderInterface
4545
* @param array{
4646
* handler: Handler,
4747
* name: ?string,
48+
* title: ?string,
4849
* description: ?string,
4950
* annotations: ?ToolAnnotations,
5051
* icons: ?Icon[],
@@ -115,6 +116,7 @@ public function load(RegistryInterface $registry): void
115116

116117
$tool = new Tool(
117118
name: $name,
119+
title: $data['title'] ?? null,
118120
inputSchema: $inputSchema,
119121
description: $description,
120122
annotations: $data['annotations'] ?? null,

‎src/Schema/Tool.php‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
* }
3434
* @phpstan-type ToolData array{
3535
* name: string,
36+
* title?: string,
3637
* inputSchema: ToolInputSchema,
3738
* description?: string|null,
3839
* annotations?: ToolAnnotationsData,
@@ -47,17 +48,19 @@ class Tool implements \JsonSerializable
4748
{
4849
/**
4950
* @param string $name the name of the tool
51+
* @param ?string $title Optional human-readable title for display in UI
52+
* @param ToolInputSchema $inputSchema a JSON Schema object (as a PHP array) defining the expected 'arguments' for the tool
5053
* @param ?string $description A human-readable description of the tool.
5154
* This can be used by clients to improve the LLM's understanding of
5255
* available tools. It can be thought of like a "hint" to the model.
53-
* @param ToolInputSchema $inputSchema a JSON Schema object (as a PHP array) defining the expected 'arguments' for the tool
5456
* @param ?ToolAnnotations $annotations optional additional tool information
5557
* @param ?Icon[] $icons optional icons representing the tool
5658
* @param ?array<string, mixed> $meta Optional metadata
5759
* @param ToolOutputSchema|null $outputSchema optional JSON Schema object (as a PHP array) defining the expected output structure
5860
*/
5961
public function __construct(
6062
public readonly string $name,
63+
public readonly ?string $title,
6164
public readonly array $inputSchema,
6265
public readonly ?string $description,
6366
public readonly ?ToolAnnotations $annotations,
@@ -95,19 +98,21 @@ public static function fromArray(array $data): self
9598
}
9699

97100
return new self(
98-
$data['name'],
99-
$inputSchema,
100-
isset($data['description']) && \is_string($data['description']) ? $data['description'] : null,
101-
isset($data['annotations']) && \is_array($data['annotations']) ? ToolAnnotations::fromArray($data['annotations']) : null,
102-
isset($data['icons']) && \is_array($data['icons']) ? array_map(Icon::fromArray(...), $data['icons']) : null,
103-
isset($data['_meta']) && \is_array($data['_meta']) ? $data['_meta'] : null,
104-
$outputSchema,
101+
name: $data['name'],
102+
title: isset($data['title']) && \is_string($data['title']) ? $data['title'] : null,
103+
inputSchema: $inputSchema,
104+
description: isset($data['description']) && \is_string($data['description']) ? $data['description'] : null,
105+
annotations: isset($data['annotations']) && \is_array($data['annotations']) ? ToolAnnotations::fromArray($data['annotations']) : null,
106+
icons: isset($data['icons']) && \is_array($data['icons']) ? array_map(Icon::fromArray(...), $data['icons']) : null,
107+
meta: isset($data['_meta']) && \is_array($data['_meta']) ? $data['_meta'] : null,
108+
outputSchema: $outputSchema,
105109
);
106110
}
107111

108112
/**
109113
* @return array{
110114
* name: string,
115+
* title?: string,
111116
* inputSchema: ToolInputSchema,
112117
* description?: string,
113118
* annotations?: ToolAnnotations,
@@ -118,10 +123,11 @@ public static function fromArray(array $data): self
118123
*/
119124
public function jsonSerialize(): array
120125
{
121-
$data = [
122-
'name' => $this->name,
123-
'inputSchema' => $this->inputSchema,
124-
];
126+
$data = ['name' => $this->name];
127+
if (null !== $this->title) {
128+
$data['title'] = $this->title;
129+
}
130+
$data['inputSchema'] = $this->inputSchema;
125131
if (null !== $this->description) {
126132
$data['description'] = $this->description;
127133
}

0 commit comments

Comments
 (0)