Enable servers to send sampling messages to clients

chr-hertel · chr-hertel · commit bff54d96bbda · 2025-10-30T16:14:40.000+01:00
diff --git a/composer.json b/composer.json
@@ -57,6 +57,7 @@
       "Mcp\\Example\\HttpDiscoveryUserProfile\\": "examples/http-discovery-userprofile/",
       "Mcp\\Example\\HttpSchemaShowcase\\": "examples/http-schema-showcase/",
       "Mcp\\Example\\StdioCachedDiscovery\\": "examples/stdio-cached-discovery/",
+      "Mcp\\Example\\StdioClientCommunication\\": "examples/stdio-client-communication/",
       "Mcp\\Example\\StdioCustomDependencies\\": "examples/stdio-custom-dependencies/",
       "Mcp\\Example\\StdioDiscoveryCalculator\\": "examples/stdio-discovery-calculator/",
       "Mcp\\Example\\StdioEnvVariables\\": "examples/stdio-env-variables/",
diff --git a/examples/http-client-communication/server.php b/examples/http-client-communication/server.php
@@ -16,7 +16,6 @@
 use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Enum\LoggingLevel;
-use Mcp\Schema\JsonRpc\Error as JsonRpcError;
 use Mcp\Schema\ServerCapabilities;
 use Mcp\Server;
 use Mcp\Server\ClientGateway;
@@ -56,18 +55,13 @@ function (string $projectName, array $milestones, ClientGateway $client): array
                 implode(', ', $milestones)
             );
 
-            $response = $client->sample(
+            $result = $client->sample(
                 prompt: $prompt,
                 maxTokens: 400,
                 timeout: 90,
                 options: ['temperature' => 0.4]
             );
 
-            if ($response instanceof JsonRpcError) {
-                throw new RuntimeException(sprintf('Sampling request failed (%d): %s', $response->code, $response->message));
-            }
-
-            $result = $response->result;
             $content = $result->content instanceof TextContent ? trim((string) $result->content->text) : '';
 
             $client->log(LoggingLevel::Info, 'Briefing ready, returning to caller.');
diff --git a/examples/stdio-client-communication/ClientAwareService.php b/examples/stdio-client-communication/ClientAwareService.php
@@ -0,0 +1,78 @@
+<?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\Example\StdioClientCommunication;
+
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Enum\LoggingLevel;
+use Mcp\Server\ClientAwareInterface;
+use Mcp\Server\ClientAwareTrait;
+use Psr\Log\LoggerInterface;
+
+final class ClientAwareService implements ClientAwareInterface
+{
+    use ClientAwareTrait;
+
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+        $this->logger->info('SamplingTool instantiated for sampling example.');
+    }
+
+    /**
+     * @return array{incident: string, recommended_actions: string, model: string}
+     */
+    #[McpTool('coordinate_incident_response', 'Coordinate an incident response with logging, progress, and sampling.')]
+    public function coordinateIncident(string $incidentTitle): array
+    {
+        $this->getClientGateway()->log(
+            LoggingLevel::Warning, \sprintf('Incident triage started: %s', $incidentTitle),
+        );
+
+        $steps = [
+            'Collecting telemetry',
+            'Assessing scope',
+            'Coordinating responders',
+        ];
+
+        foreach ($steps as $index => $step) {
+            $progress = ($index + 1) / \count($steps);
+
+            $this->getClientGateway()->progress(progress: $progress, total: 1, message: $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)
+        );
+
+        $result = $this->getClientGateway()->sample(
+            prompt: $prompt,
+            maxTokens: 350,
+            timeout: 90,
+            options: ['temperature' => 0.5]
+        );
+
+        $recommendation = $result->content instanceof TextContent ? trim((string) $result->content->text) : '';
+
+        $this->getClientGateway()->log(LoggingLevel::Info, \sprintf('Incident triage completed for %s', $incidentTitle));
+
+        return [
+            'incident' => $incidentTitle,
+            'recommended_actions' => $recommendation,
+            'model' => $result->model,
+        ];
+    }
+}
diff --git a/examples/stdio-client-communication/server.php b/examples/stdio-client-communication/server.php
@@ -13,70 +13,18 @@
 require_once dirname(__DIR__).'/bootstrap.php';
 chdir(__DIR__);
 
-use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Enum\LoggingLevel;
-use Mcp\Schema\JsonRpc\Error as JsonRpcError;
 use Mcp\Schema\ServerCapabilities;
 use Mcp\Server;
 use Mcp\Server\ClientGateway;
 use Mcp\Server\Transport\StdioTransport;
 
-$capabilities = new ServerCapabilities(logging: true, tools: true);
-
 $server = Server::builder()
     ->setServerInfo('STDIO Client Communication Demo', '1.0.0')
     ->setLogger(logger())
     ->setContainer(container())
-    ->setCapabilities($capabilities)
-    ->addTool(
-        function (string $incidentTitle, ClientGateway $client): array {
-            $client->log(LoggingLevel::Warning, sprintf('Incident triage started: %s', $incidentTitle));
-
-            $steps = [
-                'Collecting telemetry',
-                'Assessing scope',
-                'Coordinating responders',
-            ];
-
-            foreach ($steps as $index => $step) {
-                $progress = ($index + 1) / count($steps);
-
-                $client->progress(progress: $progress, total: 1, message: $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)
-            );
-
-            $sampling = $client->sample(
-                prompt: $prompt,
-                maxTokens: 350,
-                timeout: 90,
-                options: ['temperature' => 0.5]
-            );
-
-            if ($sampling instanceof JsonRpcError) {
-                throw new RuntimeException(sprintf('Sampling request failed (%d): %s', $sampling->code, $sampling->message));
-            }
-
-            $result = $sampling->result;
-            $recommendation = $result->content instanceof TextContent ? trim((string) $result->content->text) : '';
-
-            $client->log(LoggingLevel::Info, sprintf('Incident triage completed for %s', $incidentTitle));
-
-            return [
-                'incident' => $incidentTitle,
-                'recommended_actions' => $recommendation,
-                'model' => $result->model,
-            ];
-        },
-        name: 'coordinate_incident_response',
-        description: 'Coordinate an incident response with logging, progress, and sampling.'
-    )
+    ->setCapabilities(new ServerCapabilities(logging: true, tools: true))
+    ->setDiscovery(__DIR__)
     ->addTool(
         function (string $dataset, ClientGateway $client): array {
             $client->log(LoggingLevel::Info, sprintf('Running quality checks on dataset "%s"', $dataset));
diff --git a/src/Capability/Registry/ReferenceHandler.php b/src/Capability/Registry/ReferenceHandler.php
@@ -13,7 +13,9 @@
 
 use Mcp\Exception\InvalidArgumentException;
 use Mcp\Exception\RegistryException;
+use Mcp\Server\ClientAwareInterface;
 use Mcp\Server\ClientGateway;
+use Mcp\Server\Session\SessionInterface;
 use Psr\Container\ContainerInterface;
 
 /**
@@ -31,12 +33,18 @@ public function __construct(
      */
     public function handle(ElementReference $reference, array $arguments): mixed
     {
+        $session = $arguments['_session'];
+
         if (\is_string($reference->handler)) {
             if (class_exists($reference->handler) && method_exists($reference->handler, '__invoke')) {
                 $reflection = new \ReflectionMethod($reference->handler, '__invoke');
                 $instance = $this->getClassInstance($reference->handler);
                 $arguments = $this->prepareArguments($reflection, $arguments);
 
+                if ($instance instanceof ClientAwareInterface) {
+                    $instance->setClientGateway(new ClientGateway($session));
+                }
+
                 return \call_user_func($instance, ...$arguments);
             }
 
@@ -49,7 +57,7 @@ public function handle(ElementReference $reference, array $arguments): mixed
         }
 
         if (\is_callable($reference->handler)) {
-            $reflection = $this->getReflectionForCallable($reference->handler);
+            $reflection = $this->getReflectionForCallable($reference->handler, $session);
             $arguments = $this->prepareArguments($reflection, $arguments);
 
             return \call_user_func($reference->handler, ...$arguments);
@@ -59,6 +67,11 @@ public function handle(ElementReference $reference, array $arguments): mixed
             [$className, $methodName] = $reference->handler;
             $reflection = new \ReflectionMethod($className, $methodName);
             $instance = $this->getClassInstance($className);
+
+            if ($instance instanceof ClientAwareInterface) {
+                $instance->setClientGateway(new ClientGateway($session));
+            }
+
             $arguments = $this->prepareArguments($reflection, $arguments);
 
             return \call_user_func([$instance, $methodName], ...$arguments);
@@ -130,7 +143,7 @@ private function prepareArguments(\ReflectionFunctionAbstract $reflection, array
     /**
      * Gets a ReflectionMethod or ReflectionFunction for a callable.
      */
-    private function getReflectionForCallable(callable $handler): \ReflectionMethod|\ReflectionFunction
+    private function getReflectionForCallable(callable $handler, SessionInterface $session): \ReflectionMethod|\ReflectionFunction
     {
         if (\is_string($handler)) {
             return new \ReflectionFunction($handler);
@@ -143,6 +156,10 @@ private function getReflectionForCallable(callable $handler): \ReflectionMethod|
         if (\is_array($handler) && 2 === \count($handler)) {
             [$class, $method] = $handler;
 
+            if ($class instanceof ClientAwareInterface) {
+                $class->setClientGateway(new ClientGateway($session));
+            }
+
             return new \ReflectionMethod($class, $method);
         }
 
diff --git a/src/Exception/ClientException.php b/src/Exception/ClientException.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Exception;
+
+use Mcp\Schema\JsonRpc\Error;
+
+class ClientException extends Exception
+{
+    public function __construct(
+        private readonly Error $error,
+    ) {
+        parent::__construct($error->message);
+    }
+
+    public function getError(): Error
+    {
+        return $this->error;
+    }
+}
diff --git a/src/Exception/ConfigurationException.php b/src/Exception/ConfigurationException.php
@@ -12,8 +12,8 @@
 namespace Mcp\Exception;
 
 /**
- * @author Oskar Stark <oskarstark@googlemail.com>
+ * @author Christopher Hertel <mail@christopher-hertel.de>
  */
-class ConfigurationException extends InvalidArgumentException
+class ConfigurationException extends Exception
 {
 }
diff --git a/src/Schema/Content/SamplingMessage.php b/src/Schema/Content/SamplingMessage.php
@@ -18,7 +18,7 @@
  * Describes a message issued to or received from an LLM API during sampling.
  *
  * @phpstan-type SamplingMessageData = array{
- *     role: string,
+ *     role: 'user'|'assistant',
  *     content: TextContent|ImageContent|AudioContent
  * }
  *
diff --git a/src/Schema/Enum/SamplingContext.php b/src/Schema/Enum/SamplingContext.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * 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\Schema\Enum;
+
+enum SamplingContext: string
+{
+    case NONE = 'none';
+    case THIS_SERVER = 'thisServer';
+    case ALL_SERVERS = 'allServers';
+}
diff --git a/src/Schema/Request/CreateSamplingMessageRequest.php b/src/Schema/Request/CreateSamplingMessageRequest.php
@@ -13,6 +13,7 @@
 
 use Mcp\Exception\InvalidArgumentException;
 use Mcp\Schema\Content\SamplingMessage;
+use Mcp\Schema\Enum\SamplingContext;
 use Mcp\Schema\JsonRpc\Request;
 use Mcp\Schema\ModelPreferences;
 
@@ -29,25 +30,24 @@ final class CreateSamplingMessageRequest extends Request
      * @param SamplingMessage[]     $messages       the messages to send to the model
      * @param int                   $maxTokens      The maximum number of tokens to sample, as requested by the server.
      *                                              The client MAY choose to sample fewer tokens than requested.
-     * @param ModelPreferences|null $preferences    The server's preferences for which model to select. The client MAY
+     * @param ?ModelPreferences     $preferences    The server's preferences for which model to select. The client MAY
      *                                              ignore these preferences.
-     * @param string|null           $systemPrompt   An optional system prompt the server wants to use for sampling. The
+     * @param ?string               $systemPrompt   An optional system prompt the server wants to use for sampling. The
      *                                              client MAY modify or omit this prompt.
-     * @param string|null           $includeContext A request to include context from one or more MCP servers (including
+     * @param ?SamplingContext      $includeContext A request to include context from one or more MCP servers (including
      *                                              the caller), to be attached to the prompt. The client MAY ignore this request.
-     *
-     * Allowed values: "none", "thisServer", "allServers"
-     * @param float|null            $temperature   The temperature to use for sampling. The client MAY ignore this request.
-     * @param string[]|null         $stopSequences A list of sequences to stop sampling at. The client MAY ignore this request.
-     * @param ?array<string, mixed> $metadata      Optional metadata to pass through to the LLM provider. The format of
-     *                                             this metadata is provider-specific.
+     *                                              Allowed values: "none", "thisServer", "allServers"
+     * @param ?float                $temperature    The temperature to use for sampling. The client MAY ignore this request.
+     * @param ?string[]             $stopSequences  A list of sequences to stop sampling at. The client MAY ignore this request.
+     * @param ?array<string, mixed> $metadata       Optional metadata to pass through to the LLM provider. The format of
+     *                                              this metadata is provider-specific.
      */
     public function __construct(
         public readonly array $messages,
         public readonly int $maxTokens,
         public readonly ?ModelPreferences $preferences = null,
         public readonly ?string $systemPrompt = null,
-        public readonly ?string $includeContext = null,
+        public readonly ?SamplingContext $includeContext = null,
         public readonly ?float $temperature = null,
         public readonly ?array $stopSequences = null,
         public readonly ?array $metadata = null,
@@ -114,7 +114,7 @@ protected function getParams(): array
         }
 
         if (null !== $this->includeContext) {
-            $params['includeContext'] = $this->includeContext;
+            $params['includeContext'] = $this->includeContext->value;
         }
 
         if (null !== $this->temperature) {
diff --git a/src/Server/ClientAwareInterface.php b/src/Server/ClientAwareInterface.php
diff --git a/src/Server/ClientAwareTrait.php b/src/Server/ClientAwareTrait.php
diff --git a/src/Server/ClientGateway.php b/src/Server/ClientGateway.php

Original file line number	Diff line number	Diff line change
`@@ -12,8 +12,8 @@`
`12`	`12`	`namespace Mcp\Exception;`
`13`	`13`
`14`	`14`	`/**`
`15`		`- * @author Oskar Stark <oskarstark@googlemail.com>`
	`15`	`+ * @author Christopher Hertel <mail@christopher-hertel.de>`
`16`	`16`	`*/`
`17`		`-class ConfigurationException extends InvalidArgumentException`
	`17`	`+class ConfigurationException extends Exception`
`18`	`18`	`{`
`19`	`19`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,7 +18,7 @@`
`18`	`18`	`* Describes a message issued to or received from an LLM API during sampling.`
`19`	`19`	`*`
`20`	`20`	`* @phpstan-type SamplingMessageData = array{`
`21`		`- * role: string,`
	`21`	`+ * role: 'user'\|'assistant',`
`22`	`22`	`* content: TextContent\|ImageContent\|AudioContent`
`23`	`23`	`* }`
`24`	`24`	`*`