Watch

Mateu Aguiló Bosch fb2c8c2ee4

[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>

2026-04-26 15:37:40 +02:00

2.7 KiB

Raw Blame History

Client Communication

MCP supports various ways a server can communicate back to a server on top of the main request-response flow.

ClientGateway
Sampling
Logging
Notification
Progress

ClientGateway

Every communication back to client is handled using the Mcp\Server\ClientGateway and its dedicated methods per operation. To use the ClientGateway in your code, you need to use method argument injection for RequestContext.

Every reference of a MCP element, that translates to an actual method call, can just add an type-hinted argument for the RequestContext and the SDK will take care to include the gateway in the arguments of the method call:

use Mcp\Capability\Attribute\McpTool;
use Mcp\Server\RequestContext;

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

Sampling

With sampling servers can request clients to execute "completions" or "generations" with a language model for them:

$result = $clientGateway->sample('Roses are red, violets are', 350, 90, ['temperature' => 0.5]);

The sample method accepts four arguments:

message, which is required and accepts a string, an instance of Content or an array of SampleMessage instances.
maxTokens, which defaults to 1000
timeout in seconds, which defaults to 120
options which might include system_prompt, preferences for model choice, includeContext, temperature, stopSequences and metadata

Find more details to sampling payload in the specification.

Logging

The Logging utility enables servers to send structured log messages as notifcation to clients:

use Mcp\Schema\Enum\LoggingLevel;

$clientGateway->log(LoggingLevel::Warning, 'The end is near.');

Progress

With a Progress notification a server can update a client while an operation is ongoing:

$clientGateway->progress(4.2, 10, 'Downloading needed images.');

Notification

Lastly, the server can push all kind of notifications, that implement the Mcp\Schema\JsonRpc\Notification interface to the client to:

$clientGateway->notify($yourNotification);

2.7 KiB Raw Blame History