[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
10 changed files with 262 additions and 42 deletions
|
|
@ -40,18 +40,18 @@ $server = Server::builder()
|
|||
->setSession(new FileSessionStore(__DIR__.'/sessions'))
|
||||
->setLogger($logger)
|
||||
// Tools
|
||||
->addTool(static fn () => 'This is a simple text response for testing.', 'test_simple_text', 'Tests simple text content response')
|
||||
->addTool(static fn () => new ImageContent(Elements::TEST_IMAGE_BASE64, 'image/png'), 'test_image_content', 'Tests image content response')
|
||||
->addTool(static fn () => new AudioContent(Elements::TEST_AUDIO_BASE64, 'audio/wav'), 'test_audio_content', 'Tests audio content response')
|
||||
->addTool(static fn () => EmbeddedResource::fromText('test://embedded-resource', 'This is an embedded resource content.'), 'test_embedded_resource', 'Tests embedded resource content response')
|
||||
->addTool([Elements::class, 'toolMultipleTypes'], 'test_multiple_content_types', 'Tests response with multiple content types')
|
||||
->addTool([Elements::class, 'toolWithLogging'], 'test_tool_with_logging', 'Tests tool that emits log messages')
|
||||
->addTool([Elements::class, 'toolWithProgress'], 'test_tool_with_progress', 'Tests tool that reports progress notifications')
|
||||
->addTool([Elements::class, 'toolWithSampling'], 'test_sampling', 'Tests server-initiated sampling')
|
||||
->addTool(static fn () => CallToolResult::error([new TextContent('This tool intentionally returns an error for testing')]), 'test_error_handling', 'Tests error response handling')
|
||||
->addTool([Elements::class, 'toolWithElicitation'], 'test_elicitation', 'Tests server-initiated elicitation')
|
||||
->addTool([Elements::class, 'toolWithElicitationDefaults'], 'test_elicitation_sep1034_defaults', 'Tests elicitation with default values')
|
||||
->addTool([Elements::class, 'toolWithElicitationEnums'], 'test_elicitation_sep1330_enums', 'Tests elicitation with enum schemas')
|
||||
->addTool(static fn () => 'This is a simple text response for testing.', name: 'test_simple_text', description: 'Tests simple text content response')
|
||||
->addTool(static fn () => new ImageContent(Elements::TEST_IMAGE_BASE64, 'image/png'), name: 'test_image_content', description: 'Tests image content response')
|
||||
->addTool(static fn () => new AudioContent(Elements::TEST_AUDIO_BASE64, 'audio/wav'), name: 'test_audio_content', description: 'Tests audio content response')
|
||||
->addTool(static fn () => EmbeddedResource::fromText('test://embedded-resource', 'This is an embedded resource content.'), name: 'test_embedded_resource', description: 'Tests embedded resource content response')
|
||||
->addTool([Elements::class, 'toolMultipleTypes'], name: 'test_multiple_content_types', description: 'Tests response with multiple content types')
|
||||
->addTool([Elements::class, 'toolWithLogging'], name: 'test_tool_with_logging', description: 'Tests tool that emits log messages')
|
||||
->addTool([Elements::class, 'toolWithProgress'], name: 'test_tool_with_progress', description: 'Tests tool that reports progress notifications')
|
||||
->addTool([Elements::class, 'toolWithSampling'], name: 'test_sampling', description: 'Tests server-initiated sampling')
|
||||
->addTool(static fn () => CallToolResult::error([new TextContent('This tool intentionally returns an error for testing')]), name: 'test_error_handling', description: 'Tests error response handling')
|
||||
->addTool([Elements::class, 'toolWithElicitation'], name: 'test_elicitation', description: 'Tests server-initiated elicitation')
|
||||
->addTool([Elements::class, 'toolWithElicitationDefaults'], name: 'test_elicitation_sep1034_defaults', description: 'Tests elicitation with default values')
|
||||
->addTool([Elements::class, 'toolWithElicitationEnums'], name: 'test_elicitation_sep1330_enums', description: 'Tests elicitation with enum schemas')
|
||||
// Resources
|
||||
->addResource(static fn () => 'This is the content of the static text resource.', 'test://static-text', 'static-text', 'A static text resource for testing')
|
||||
->addResource(static fn () => fopen('data://image/png;base64,'.Elements::TEST_IMAGE_BASE64, 'r'), 'test://static-binary', 'static-binary', 'A static binary resource (image) for testing')
|
||||
|
|
|
|||
|
|
@ -52,6 +52,21 @@ class McpToolTest extends TestCase
|
|||
$this->assertNull($attribute->outputSchema);
|
||||
}
|
||||
|
||||
public function testInstantiatesWithTitle(): void
|
||||
{
|
||||
$attribute = new McpTool(name: 'n', title: 'T');
|
||||
|
||||
$this->assertSame('n', $attribute->name);
|
||||
$this->assertSame('T', $attribute->title);
|
||||
}
|
||||
|
||||
public function testDefaultTitleIsNull(): void
|
||||
{
|
||||
$attribute = new McpTool();
|
||||
|
||||
$this->assertNull($attribute->title);
|
||||
}
|
||||
|
||||
public function testInstantiatesWithOutputSchema(): void
|
||||
{
|
||||
// Arrange
|
||||
|
|
|
|||
33
tests/Unit/Capability/Discovery/DiscovererToolTitleTest.php
Normal file
33
tests/Unit/Capability/Discovery/DiscovererToolTitleTest.php
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
<?php
|
||||
|
||||
/*
|
||||
* This file is part of the official PHP MCP SDK.
|
||||
*
|
||||
* A collaboration between Symfony and the PHP Foundation.
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
namespace Mcp\Tests\Unit\Capability\Discovery;
|
||||
|
||||
use Mcp\Capability\Discovery\Discoverer;
|
||||
use Mcp\Capability\Registry\ToolReference;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
|
||||
class DiscovererToolTitleTest extends TestCase
|
||||
{
|
||||
public function testDiscoveryPropagatesMcpToolTitleToToolTitle(): void
|
||||
{
|
||||
$discoverer = new Discoverer();
|
||||
|
||||
$discovery = $discoverer->discover(__DIR__, ['Fixtures']);
|
||||
|
||||
$tools = $discovery->getTools();
|
||||
|
||||
$this->assertArrayHasKey('greet_user', $tools);
|
||||
$toolRef = $tools['greet_user'];
|
||||
$this->assertInstanceOf(ToolReference::class, $toolRef);
|
||||
$this->assertSame('Greet User', $toolRef->tool->title);
|
||||
}
|
||||
}
|
||||
|
|
@ -24,7 +24,7 @@ class DiscoverableToolHandler
|
|||
*
|
||||
* @return string the greeting
|
||||
*/
|
||||
#[McpTool(name: 'greet_user', description: 'Greets a user by name.')]
|
||||
#[McpTool(name: 'greet_user', description: 'Greets a user by name.', title: 'Greet User')]
|
||||
public function greet(string $name): string
|
||||
{
|
||||
return "Hello, {$name}!";
|
||||
|
|
|
|||
|
|
@ -0,0 +1,48 @@
|
|||
<?php
|
||||
|
||||
/*
|
||||
* This file is part of the official PHP MCP SDK.
|
||||
*
|
||||
* A collaboration between Symfony and the PHP Foundation.
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
namespace Mcp\Tests\Unit\Capability\Registry\Loader;
|
||||
|
||||
use Mcp\Capability\Registry;
|
||||
use Mcp\Capability\Registry\Loader\ArrayLoader;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
|
||||
class ArrayLoaderToolTitleTest extends TestCase
|
||||
{
|
||||
public function testLoadPropagatesToolTitleToRegisteredTool(): void
|
||||
{
|
||||
$tools = [
|
||||
[
|
||||
'handler' => static fn (): string => 'ok',
|
||||
'name' => 'weather_lookup',
|
||||
'title' => 'Weather Lookup',
|
||||
'description' => null,
|
||||
'annotations' => null,
|
||||
'inputSchema' => [
|
||||
'type' => 'object',
|
||||
'properties' => new \stdClass(),
|
||||
'required' => null,
|
||||
],
|
||||
'icons' => null,
|
||||
'meta' => null,
|
||||
'outputSchema' => null,
|
||||
],
|
||||
];
|
||||
|
||||
$loader = new ArrayLoader($tools);
|
||||
$registry = new Registry();
|
||||
|
||||
$loader->load($registry);
|
||||
|
||||
$toolRef = $registry->getTool('weather_lookup');
|
||||
$this->assertSame('Weather Lookup', $toolRef->tool->title);
|
||||
}
|
||||
}
|
||||
|
|
@ -615,6 +615,7 @@ class RegistryTest extends TestCase
|
|||
{
|
||||
return new Tool(
|
||||
name: $name,
|
||||
title: null,
|
||||
inputSchema: [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
|
|
|
|||
100
tests/Unit/Schema/ToolTest.php
Normal file
100
tests/Unit/Schema/ToolTest.php
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
<?php
|
||||
|
||||
/*
|
||||
* This file is part of the official PHP MCP SDK.
|
||||
*
|
||||
* A collaboration between Symfony and the PHP Foundation.
|
||||
*
|
||||
* For the full copyright and license information, please view the LICENSE
|
||||
* file that was distributed with this source code.
|
||||
*/
|
||||
|
||||
namespace Mcp\Tests\Unit\Schema;
|
||||
|
||||
use Mcp\Schema\Tool;
|
||||
use PHPUnit\Framework\Attributes\DataProvider;
|
||||
use PHPUnit\Framework\TestCase;
|
||||
|
||||
class ToolTest extends TestCase
|
||||
{
|
||||
/**
|
||||
* @return array{type: 'object', properties: array<string, mixed>, required: string[]|null}
|
||||
*/
|
||||
private static function validInputSchema(): array
|
||||
{
|
||||
return [
|
||||
'type' => 'object',
|
||||
'properties' => ['q' => ['type' => 'string']],
|
||||
'required' => null,
|
||||
];
|
||||
}
|
||||
|
||||
private static function makeTool(?string $title, ?string $description = null): Tool
|
||||
{
|
||||
return new Tool(
|
||||
name: 'x',
|
||||
inputSchema: self::validInputSchema(),
|
||||
description: $description,
|
||||
annotations: null,
|
||||
title: $title,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return iterable<string, array{?string, list<string>}>
|
||||
*/
|
||||
public static function serializationKeyOrderProvider(): iterable
|
||||
{
|
||||
yield 'with title' => ['Friendly Title', ['name', 'title', 'inputSchema']];
|
||||
yield 'without title' => [null, ['name', 'inputSchema']];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param list<string> $expectedKeys
|
||||
*/
|
||||
#[DataProvider('serializationKeyOrderProvider')]
|
||||
public function testSerializationPlacesTitleBetweenNameAndInputSchema(?string $title, array $expectedKeys): void
|
||||
{
|
||||
$serialized = self::makeTool($title)->jsonSerialize();
|
||||
|
||||
$this->assertSame($expectedKeys, array_keys($serialized));
|
||||
if (null !== $title) {
|
||||
$this->assertSame($title, $serialized['title']);
|
||||
} else {
|
||||
$this->assertArrayNotHasKey('title', $serialized);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @return iterable<string, array{array<string, mixed>, ?string}>
|
||||
*/
|
||||
public static function fromArrayTitleProvider(): iterable
|
||||
{
|
||||
yield 'title present' => [['title' => 'Friendly Title'], 'Friendly Title'];
|
||||
yield 'title missing' => [[], null];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $extra
|
||||
*/
|
||||
#[DataProvider('fromArrayTitleProvider')]
|
||||
public function testFromArrayReadsTitle(array $extra, ?string $expectedTitle): void
|
||||
{
|
||||
$tool = Tool::fromArray(['name' => 'x', 'inputSchema' => self::validInputSchema()] + $extra);
|
||||
|
||||
$this->assertSame($expectedTitle, $tool->title);
|
||||
}
|
||||
|
||||
public function testRoundTripPreservesTitle(): void
|
||||
{
|
||||
$original = self::makeTool('Friendly Title', 'desc');
|
||||
|
||||
/** @var array{name: string, title?: string, inputSchema: array{type: 'object', properties: array<string, mixed>, required: string[]|null}, description?: string|null} $serialized */
|
||||
$serialized = $original->jsonSerialize();
|
||||
$restored = Tool::fromArray($serialized);
|
||||
|
||||
$this->assertSame('Friendly Title', $restored->title);
|
||||
$this->assertSame($original->name, $restored->name);
|
||||
$this->assertSame($original->description, $restored->description);
|
||||
}
|
||||
}
|
||||
|
|
@ -71,7 +71,7 @@ final class BuilderTest extends TestCase
|
|||
$server = Server::builder()
|
||||
->setServerInfo('test', '1.0.0')
|
||||
->setReferenceHandler($referenceHandler)
|
||||
->addTool(static fn (): string => 'original', 'test_tool', 'A test tool')
|
||||
->addTool(static fn (): string => 'original', name: 'test_tool', description: 'A test tool')
|
||||
->build();
|
||||
|
||||
$result = $this->callTool($server, 'test_tool');
|
||||
|
|
|
|||
|
|
@ -483,7 +483,7 @@ class CallToolHandlerTest extends TestCase
|
|||
|
||||
$request = $this->createCallToolRequest('result_tool', ['query' => 'php']);
|
||||
$toolReference = $this->getMockBuilder(ToolReference::class)
|
||||
->setConstructorArgs([new Tool('simple_tool', $schema, null, null), static function () {}])
|
||||
->setConstructorArgs([new Tool('simple_tool', null, $schema, null, null), static function () {}])
|
||||
->getMock();
|
||||
|
||||
$this->registry
|
||||
|
|
@ -535,7 +535,7 @@ class CallToolHandlerTest extends TestCase
|
|||
],
|
||||
'required' => [],
|
||||
];
|
||||
$tool = new Tool($name, $schema, null, null, null, null, $outputSchema);
|
||||
$tool = new Tool($name, null, $schema, null, null, null, null, $outputSchema);
|
||||
|
||||
$builder = $this->getMockBuilder(ToolReference::class)
|
||||
->setConstructorArgs([$tool, $handler]);
|
||||
|
|
|
|||
|
|
@ -289,6 +289,7 @@ class ListToolsHandlerTest extends TestCase
|
|||
for ($i = 0; $i < $count; ++$i) {
|
||||
$tool = new Tool(
|
||||
name: "tool_$i",
|
||||
title: null,
|
||||
inputSchema: [
|
||||
'type' => 'object',
|
||||
'properties' => [],
|
||||
|
|
|
|||
Loading…
Reference in a new issue