[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>
This commit is contained in:
Mateu Aguiló Bosch
GitHub
parent
97979ec48d
commit
fb2c8c2ee4
6 changed files with 262 additions and 42 deletions
|
|
@ -22,6 +22,7 @@ class McpTool
|
|||
{
|
||||
/**
|
||||
* @param string|null $name The name of the tool (defaults to the method name)
|
||||
* @param string|null $title Optional human-readable title for display in UI
|
||||
* @param string|null $description The description of the tool (defaults to the DocBlock/inferred)
|
||||
* @param ToolAnnotations|null $annotations Optional annotations describing tool behavior
|
||||
* @param ?Icon[] $icons Optional list of icon URLs representing the tool
|
||||
|
|
@ -30,6 +31,7 @@ class McpTool
|
|||
*/
|
||||
public function __construct(
|
||||
public ?string $name = null,
|
||||
public ?string $title = null,
|
||||
public ?string $description = null,
|
||||
public ?ToolAnnotations $annotations = null,
|
||||
public ?array $icons = null,
|
||||
|
|
|
|||
|
|
@ -231,13 +231,14 @@ final class Discoverer implements DiscovererInterface
|
|||
$inputSchema = $this->schemaGenerator->generate($method);
|
||||
$outputSchema = $this->schemaGenerator->generateOutputSchema($method);
|
||||
$tool = new Tool(
|
||||
$name,
|
||||
$inputSchema,
|
||||
$description,
|
||||
$instance->annotations,
|
||||
$instance->icons,
|
||||
$instance->meta,
|
||||
$outputSchema,
|
||||
name: $name,
|
||||
title: $instance->title,
|
||||
inputSchema: $inputSchema,
|
||||
description: $description,
|
||||
annotations: $instance->annotations,
|
||||
icons: $instance->icons,
|
||||
meta: $instance->meta,
|
||||
outputSchema: $outputSchema,
|
||||
);
|
||||
$tools[$name] = new ToolReference($tool, [$className, $methodName], false);
|
||||
++$discoveredCount['tools'];
|
||||
|
|
|
|||
|
|
@ -45,6 +45,7 @@ final class ArrayLoader implements LoaderInterface
|
|||
* @param array{
|
||||
* handler: Handler,
|
||||
* name: ?string,
|
||||
* title: ?string,
|
||||
* description: ?string,
|
||||
* annotations: ?ToolAnnotations,
|
||||
* icons: ?Icon[],
|
||||
|
|
@ -115,6 +116,7 @@ final class ArrayLoader implements LoaderInterface
|
|||
|
||||
$tool = new Tool(
|
||||
name: $name,
|
||||
title: $data['title'] ?? null,
|
||||
inputSchema: $inputSchema,
|
||||
description: $description,
|
||||
annotations: $data['annotations'] ?? null,
|
||||
|
|
|
|||
|
|
@ -33,6 +33,7 @@ use Mcp\Exception\InvalidArgumentException;
|
|||
* }
|
||||
* @phpstan-type ToolData array{
|
||||
* name: string,
|
||||
* title?: string,
|
||||
* inputSchema: ToolInputSchema,
|
||||
* description?: string|null,
|
||||
* annotations?: ToolAnnotationsData,
|
||||
|
|
@ -47,10 +48,11 @@ class Tool implements \JsonSerializable
|
|||
{
|
||||
/**
|
||||
* @param string $name the name of the tool
|
||||
* @param ?string $title Optional human-readable title for display in UI
|
||||
* @param ToolInputSchema $inputSchema a JSON Schema object (as a PHP array) defining the expected 'arguments' for the tool
|
||||
* @param ?string $description A human-readable description of the tool.
|
||||
* This can be used by clients to improve the LLM's understanding of
|
||||
* available tools. It can be thought of like a "hint" to the model.
|
||||
* @param ToolInputSchema $inputSchema a JSON Schema object (as a PHP array) defining the expected 'arguments' for the tool
|
||||
* @param ?ToolAnnotations $annotations optional additional tool information
|
||||
* @param ?Icon[] $icons optional icons representing the tool
|
||||
* @param ?array<string, mixed> $meta Optional metadata
|
||||
|
|
@ -58,6 +60,7 @@ class Tool implements \JsonSerializable
|
|||
*/
|
||||
public function __construct(
|
||||
public readonly string $name,
|
||||
public readonly ?string $title,
|
||||
public readonly array $inputSchema,
|
||||
public readonly ?string $description,
|
||||
public readonly ?ToolAnnotations $annotations,
|
||||
|
|
@ -95,19 +98,21 @@ class Tool implements \JsonSerializable
|
|||
}
|
||||
|
||||
return new self(
|
||||
$data['name'],
|
||||
$inputSchema,
|
||||
isset($data['description']) && \is_string($data['description']) ? $data['description'] : null,
|
||||
isset($data['annotations']) && \is_array($data['annotations']) ? ToolAnnotations::fromArray($data['annotations']) : null,
|
||||
isset($data['icons']) && \is_array($data['icons']) ? array_map(Icon::fromArray(...), $data['icons']) : null,
|
||||
isset($data['_meta']) && \is_array($data['_meta']) ? $data['_meta'] : null,
|
||||
$outputSchema,
|
||||
name: $data['name'],
|
||||
title: isset($data['title']) && \is_string($data['title']) ? $data['title'] : null,
|
||||
inputSchema: $inputSchema,
|
||||
description: isset($data['description']) && \is_string($data['description']) ? $data['description'] : null,
|
||||
annotations: isset($data['annotations']) && \is_array($data['annotations']) ? ToolAnnotations::fromArray($data['annotations']) : null,
|
||||
icons: isset($data['icons']) && \is_array($data['icons']) ? array_map(Icon::fromArray(...), $data['icons']) : null,
|
||||
meta: isset($data['_meta']) && \is_array($data['_meta']) ? $data['_meta'] : null,
|
||||
outputSchema: $outputSchema,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array{
|
||||
* name: string,
|
||||
* title?: string,
|
||||
* inputSchema: ToolInputSchema,
|
||||
* description?: string,
|
||||
* annotations?: ToolAnnotations,
|
||||
|
|
@ -118,10 +123,11 @@ class Tool implements \JsonSerializable
|
|||
*/
|
||||
public function jsonSerialize(): array
|
||||
{
|
||||
$data = [
|
||||
'name' => $this->name,
|
||||
'inputSchema' => $this->inputSchema,
|
||||
];
|
||||
$data = ['name' => $this->name];
|
||||
if (null !== $this->title) {
|
||||
$data['title'] = $this->title;
|
||||
}
|
||||
$data['inputSchema'] = $this->inputSchema;
|
||||
if (null !== $this->description) {
|
||||
$data['description'] = $this->description;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ namespace Mcp\Schema;
|
|||
class ToolAnnotations implements \JsonSerializable
|
||||
{
|
||||
/**
|
||||
* @param ?string $title a human-readable title for the tool
|
||||
* @param ?string $title a human-readable title for the tool — deprecated for display in favor of `Mcp\Schema\Tool::$title` per MCP spec revision 2025-06-18; retained for backward compatibility
|
||||
* @param ?bool $readOnlyHint if true, the tool does not modify its environment
|
||||
* @param ?bool $destructiveHint If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates.
|
||||
* @param ?bool $idempotentHint If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment. (This property is meaningful only when `readOnlyHint == false`)
|
||||
|
|
|
|||
|
|
@ -99,6 +99,7 @@ final class Builder
|
|||
* @var array{
|
||||
* handler: Handler,
|
||||
* name: ?string,
|
||||
* title: ?string,
|
||||
* description: ?string,
|
||||
* annotations: ?ToolAnnotations,
|
||||
* icons: ?Icon[],
|
||||
|
|
@ -373,6 +374,7 @@ final class Builder
|
|||
* Manually registers a tool handler.
|
||||
*
|
||||
* @param Handler $handler
|
||||
* @param ?string $title Optional human-readable title for display in UI
|
||||
* @param array<string, mixed>|null $inputSchema
|
||||
* @param ?Icon[] $icons
|
||||
* @param array<string, mixed>|null $meta
|
||||
|
|
@ -381,6 +383,7 @@ final class Builder
|
|||
public function addTool(
|
||||
callable|array|string $handler,
|
||||
?string $name = null,
|
||||
?string $title = null,
|
||||
?string $description = null,
|
||||
?ToolAnnotations $annotations = null,
|
||||
?array $inputSchema = null,
|
||||
|
|
@ -391,6 +394,7 @@ final class Builder
|
|||
$this->tools[] = compact(
|
||||
'handler',
|
||||
'name',
|
||||
'title',
|
||||
'description',
|
||||
'annotations',
|
||||
'inputSchema',
|
||||
|
|
|
|||
Loading…
Reference in a new issue