modelcontextprotocol/php-sdk
Watch
1
0
Fork
You've already forked php-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[Client] Speak the 2026-07-28 lifecycle (#456)

Browse source 
* [Client] Speak the 2026-07-28 lifecycle

On that revision the client opens with server/discover instead of
initialize, stamps each request's _meta with the protocol version, its own
capabilities and client info, and sends the standard Mcp-Method / Mcp-Name /
Mcp-Param-* headers an intermediary routes on. ToolCatalog is what knows,
from the tool list, which arguments a call has to mirror.

An input_required result is answered rather than surfaced: InputRequestResolver
asks the host's elicitation, sampling and roots handlers and retries the same
request carrying inputResponses and the requestState the server sent.

McpHeader holds the header names and the =?base64?…?= sentinel, so the two
sides no longer keep their own copies of the same rules.

* Fix CI baseline drift and address Copilot review findings

Drop stale expected-failure entries the new client fixture now passes.

Copilot review: fix McpHeader round-trip for a wrapper-shaped literal,
encode empty/numeric-keyed inputResponses as a JSON object, stop the
incident example repeating side effects on MRTR retry, and reset
ToolCatalog on reconnect instead of carrying the previous server's
verdicts.

* Skip DualEraExampleTestCase on PHP 8.1

PHP_CLI_SERVER_WORKERS does not reliably fork multiple php -S
workers there (php/php-src#9400), reproducing the single-worker
deadlock the extra workers exist to avoid.
This commit is contained in:
Christopher Hertel 2026-08-19 02:41:02 +02:00 • committed by GitHub
commit 8c06dcecc6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 2443 additions and 248 deletions
Download patch file Download diff file Expand all files Collapse all files

71
examples/server/client-communication/ClientAwareService.php
View file

@ -12,8 +12,13 @@
namespace Mcp\Example\Server\ClientCommunication;
use Mcp\Capability\Attribute\McpTool;
use Mcp\Schema\Content\SamplingMessage;
use Mcp\Schema\Content\TextContent;
use Mcp\Schema\Enum\LoggingLevel;
use Mcp\Schema\Enum\Role;
use Mcp\Schema\Request\CreateSamplingMessageRequest;
use Mcp\Schema\Request\ListRootsRequest;
use Mcp\Schema\Result\InputRequiredResult;
use Mcp\Server\RequestContext;
use Psr\Log\LoggerInterface;
@ -31,10 +36,14 @@ final class ClientAwareService
* Demonstrates the server side of the "roots" client capability: the tool
* issues a roots/list request that the client answers from its own handler.
*
* @return array{status: string, message: string, roots?: list<array{uri: string, name: string|null}>}
* Written the 2026-07-28 way: the ask is returned and the answer read off
* the retry. A handshake-era client reaches the same tool — the SDK sends
* the `roots/list` request over that connection and re-enters this method.
*
* @return array{status: string, message: string, roots?: list<array{uri: string, name: string|null}>}|InputRequiredResult
*/
#[McpTool(name: 'inspect_workspace_roots', description: 'Ask the client for its workspace roots via a roots/list request.')]
public function inspectWorkspaceRoots(RequestContext $context): array
public function inspectWorkspaceRoots(RequestContext $context): array|InputRequiredResult
{
$clientGateway = $context->getClientGateway();
@ -45,7 +54,11 @@ final class ClientAwareService
];
}
$result = $clientGateway->listRoots();
$result = $context->getInputContext()?->rootsResult('roots');
if (null === $result) {
return new InputRequiredResult(['roots' => new ListRootsRequest()]);
}
$roots = [];
foreach ($result->roots as $root) {
@ -62,36 +75,48 @@ final class ClientAwareService
}
/**
* @return array{incident: string, recommended_actions: string, model: string}
* @return array{incident: string, recommended_actions: string, model: string}|InputRequiredResult
*/
#[McpTool(name: 'coordinate_incident_response', description: 'Coordinate an incident response with logging, progress, and sampling.')]
public function coordinateIncident(RequestContext $context, string $incidentTitle): array
public function coordinateIncident(RequestContext $context, string $incidentTitle): array|InputRequiredResult
{
$clientGateway = $context->getClientGateway();
$clientGateway->log(LoggingLevel::Warning, \sprintf('Incident triage started: %s', $incidentTitle));
$steps = [
'Collecting telemetry',
'Assessing scope',
'Coordinating responders',
];
// A retry re-enters this method from the top, so the triage work below
// must run only once: check for the answer first, before repeating logs,
// progress notifications and simulated work the client already saw.
$result = $context->getInputContext()?->samplingResult('recommendation');
foreach ($steps as $index => $step) {
$progress = ($index + 1) / \count($steps);
if (null === $result) {
$clientGateway->log(LoggingLevel::Warning, \sprintf('Incident triage started: %s', $incidentTitle));
$clientGateway->progress($progress, 1, $step);
$steps = [
'Collecting telemetry',
'Assessing scope',
'Coordinating responders',
];
usleep(180_000); // Simulate work being done
foreach ($steps as $index => $step) {
$progress = ($index + 1) / \count($steps);
$clientGateway->progress($progress, 1, $step);
usleep(180_000); // Simulate work being done
}
$prompt = \sprintf(
'Provide a concise response strategy for incident "%s" based on the steps completed: %s.',
$incidentTitle,
implode(', ', $steps)
);
return new InputRequiredResult(['recommendation' => new CreateSamplingMessageRequest(
messages: [new SamplingMessage(Role::User, new TextContent($prompt))],
maxTokens: 350,
temperature: 0.5,
)]);
}
$prompt = \sprintf(
'Provide a concise response strategy for incident "%s" based on the steps completed: %s.',
$incidentTitle,
implode(', ', $steps)
);
$result = $clientGateway->sample($prompt, 350, 90, ['temperature' => 0.5]);
$recommendation = $result->content instanceof TextContent ? trim((string) $result->content->text) : '';
$clientGateway->log(LoggingLevel::Info, \sprintf('Incident triage completed for %s', $incidentTitle));

82
examples/server/elicitation/ElicitationHandlers.php
View file

@ -17,6 +17,9 @@ use Mcp\Schema\Elicitation\ElicitationSchema;
use Mcp\Schema\Elicitation\EnumSchemaDefinition;
use Mcp\Schema\Elicitation\NumberSchemaDefinition;
use Mcp\Schema\Elicitation\StringSchemaDefinition;
use Mcp\Schema\Request\ElicitRequest;
use Mcp\Schema\Result\ElicitResult;
use Mcp\Schema\Result\InputRequiredResult;
use Mcp\Server\RequestContext;
use Psr\Log\LoggerInterface;
@ -43,10 +46,10 @@ final class ElicitationHandlers
* - String field with date format for reservation date
* - Enum field for dietary restrictions with human-readable labels
*
* @return array{status: string, message: string, booking?: array{party_size: int, date: string, dietary: string}}
* @return array{status: string, message: string, booking?: array{party_size: int, date: string, dietary: string}}|InputRequiredResult
*/
#[McpTool(name: 'book_restaurant', description: 'Book a restaurant reservation, collecting details via elicitation.')]
public function bookRestaurant(RequestContext $context, string $restaurantName): array
public function bookRestaurant(RequestContext $context, string $restaurantName): array|InputRequiredResult
{
if (!$context->getClientGateway()->supportsElicitation()) {
return [
@ -55,8 +58,6 @@ final class ElicitationHandlers
];
}
$client = $context->getClientGateway();
$this->logger->info(\sprintf('Starting reservation process for restaurant: %s', $restaurantName));
$schema = new ElicitationSchema(
@ -85,12 +86,19 @@ final class ElicitationHandlers
required: ['party_size', 'date'],
);
$result = $client->elicit(
message: \sprintf('Please provide your reservation details for %s:', $restaurantName),
requestedSchema: $schema,
timeout: 120,
$result = $this->ask(
$context,
'details',
\sprintf('Please provide your reservation details for %s:', $restaurantName),
$schema,
);
// Modern era, first round: the ask travels back as the result and the
// client retries this whole call carrying the answer.
if ($result instanceof InputRequiredResult) {
return $result;
}
if ($result->isDeclined()) {
$this->logger->info('User declined to provide reservation details.');
@ -154,10 +162,10 @@ final class ElicitationHandlers
*
* Demonstrates the simplest elicitation pattern - a yes/no confirmation.
*
* @return array{status: string, message: string}
* @return array{status: string, message: string}|InputRequiredResult
*/
#[McpTool(name: 'confirm_action', description: 'Request user confirmation before proceeding with an action.')]
public function confirmAction(RequestContext $context, string $actionDescription): array
public function confirmAction(RequestContext $context, string $actionDescription): array|InputRequiredResult
{
if (!$context->getClientGateway()->supportsElicitation()) {
return [
@ -166,8 +174,6 @@ final class ElicitationHandlers
];
}
$client = $context->getClientGateway();
$schema = new ElicitationSchema(
properties: [
'confirm' => new BooleanSchemaDefinition(
@ -179,11 +185,17 @@ final class ElicitationHandlers
required: ['confirm'],
);
$result = $client->elicit(
message: \sprintf('Are you sure you want to: %s?', $actionDescription),
requestedSchema: $schema,
$result = $this->ask(
$context,
'confirmation',
\sprintf('Are you sure you want to: %s?', $actionDescription),
$schema,
);
if ($result instanceof InputRequiredResult) {
return $result;
}
if (!$result->isAccepted()) {
return [
'status' => 'not_confirmed',
@ -222,10 +234,10 @@ final class ElicitationHandlers
*
* Demonstrates elicitation with optional fields and enum with labels.
*
* @return array{status: string, message: string, feedback?: array{rating: string, comments: string}}
* @return array{status: string, message: string, feedback?: array{rating: string, comments: string}}|InputRequiredResult
*/
#[McpTool(name: 'collect_feedback', description: 'Collect user feedback via elicitation form.')]
public function collectFeedback(RequestContext $context, string $topic): array
public function collectFeedback(RequestContext $context, string $topic): array|InputRequiredResult
{
if (!$context->getClientGateway()->supportsElicitation()) {
return [
@ -234,8 +246,6 @@ final class ElicitationHandlers
];
}
$client = $context->getClientGateway();
$schema = new ElicitationSchema(
properties: [
'rating' => new EnumSchemaDefinition(
@ -253,11 +263,17 @@ final class ElicitationHandlers
required: ['rating'],
);
$result = $client->elicit(
message: \sprintf('Please provide your feedback about: %s', $topic),
requestedSchema: $schema,
$result = $this->ask(
$context,
'feedback',
\sprintf('Please provide your feedback about: %s', $topic),
$schema,
);
if ($result instanceof InputRequiredResult) {
return $result;
}
if (!$result->isAccepted()) {
return [
'status' => 'skipped',
@ -288,4 +304,26 @@ final class ElicitationHandlers
],
];
}
/**
* Ask the user one question.
*
* Written the way revision 2026-07-28 asks: the question is *returned*, the
* client answers it and retries the whole call, and the answer comes back
* through the input context under the same key. Nothing here names an era —
* on a handshake-era connection the SDK fulfils the same ask over that
* connection's own channel and re-enters the tool with the answer.
*
* The caller gets an {@see ElicitResult} once there is one, or an
* {@see InputRequiredResult} to hand straight back to its own caller.
*/
private function ask(
RequestContext $context,
string $key,
string $message,
ElicitationSchema $schema,
): ElicitResult|InputRequiredResult {
return $context->getInputContext()?->elicitResult($key)
?? new InputRequiredResult([$key => new ElicitRequest($message, $schema)]);
}
}