[Schema][Server] Add top-level title to Tool#288
Merged
chr-hertel merged 6 commits intomodelcontextprotocol:mainfrom Apr 26, 2026
Merged
[Schema][Server] Add top-level title to Tool#288chr-hertel merged 6 commits intomodelcontextprotocol:mainfrom
chr-hertel merged 6 commits intomodelcontextprotocol:mainfrom
Conversation
added 5 commits
April 19, 2026 17:44
Mirror PR modelcontextprotocol#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.
- 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.
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.
- 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.
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.
e0ipso
requested review from
CodeWithKyrian,
Nyholm,
chr-hertel and
soyuka
as code owners
Contributor
Author
|
The, unrelated, CI failures are fixed in #289 |
chr-hertel
requested changes
Apr 20, 2026
Member
There was a problem hiding this comment.
Thanks for tackling this @e0ipso - only small consistency issue and please add an entry to the changelog for 0.5 - thanks already! 🙏
Rebase will solve the CS issue - thanks to you :D
chr-hertel
changed the title
chr-hertel
added
Server
chr-hertel
added
the
needs more work
chr-hertel
approved these changes
Apr 26, 2026
chr-hertel
removed
the
needs more work
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
titlefield toTool(mirrors thetitleaddition toPromptin [Schema] Addtitlefield to Prompt for MCP spec compliance #278) for MCP spec compliance.titlethrough theMcpToolattribute,Discoverer,ArrayLoader, andServer\Builder::addTool().titleis serialized as the second key (betweennameandinputSchema) when non-null and omitted otherwise.titleis a trailing optional parameter (defaultnull) onTool::__construct,McpTool, andaddTool(); positional callers are unaffected.titlefield inToolschema #287Test plan
vendor/bin/phpunitpass.ToolTest(construction, serialization key order,fromArray, round-trip) via data providers.DiscovererToolTitleTestexercises#[McpTool(title: ...)]end-to-end against the sharedDiscoverableToolHandlerfixture.ArrayLoaderToolTitleTestverifies the loader forwardstitleinto the registeredTool.McpToolTestcovers the new attribute field and its default.