Enable servers to send sampling messages to clients

Author: chr-hertel

composer.json

@@ -60,6 +60,7 @@
       "Mcp\\Example\\StdioDiscoveryCalculator\\": "examples/stdio-discovery-calculator/",
       "Mcp\\Example\\StdioEnvVariables\\": "examples/stdio-env-variables/",
       "Mcp\\Example\\StdioExplicitRegistration\\": "examples/stdio-explicit-registration/",
+      "Mcp\\Example\\StdioToolSampling\\": "examples/stdio-tool-sampling/",
       "Mcp\\Tests\\": "tests/"
     }
   },

examples/stdio-tool-sampling/SamplingTool.php

@@ -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\Example\StdioToolSampling;
+
+use Mcp\Schema\Content\SamplingMessage;
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Enum\Role;
+use Mcp\Schema\Request\CreateSamplingMessageRequest;
+use Mcp\Schema\Result\CreateSamplingMessageResult;
+use Mcp\Server\ClientAwareInterface;
+use Mcp\Server\ClientAwareTrait;
+use Psr\Log\LoggerInterface;
+
+final class SamplingTool implements ClientAwareInterface
+{
+    use ClientAwareTrait;
+
+    public function __construct(
+        private readonly LoggerInterface $logger,
+    ) {
+        $this->logger->info('SamplingTool instantiated for sampling example.');
+    }
+
+    public function trySampling(): string
+    {
+        $this->logger->info('About to send a sampling request to the client.');
+
+        $response = $this->getClientGateway()->request(
+            new CreateSamplingMessageRequest(
+                messages: [new SamplingMessage(Role::User, new TextContent('Hello from server!'))],
+                maxTokens: 100,
+            ),
+        );
+
+        \assert($response instanceof CreateSamplingMessageResult);
+
+        return 'Client Response: '.$response->content->text;
+    }
+}

examples/stdio-tool-sampling/server.php

@@ -0,0 +1,35 @@
+#!/usr/bin/env php
+<?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.
+ */
+
+require_once dirname(__DIR__).'/bootstrap.php';
+chdir(__DIR__);
+
+use Mcp\Example\StdioToolSampling\SamplingTool;
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+logger()->info('Starting MCP Server with Sampling ...');
+
+$server = Server::builder()
+    ->setServerInfo('Sampling Server', '1.0.0')
+    ->setLogger(logger())
+    ->setContainer(container())
+    ->addTool([SamplingTool::class, 'trySampling'], 'try_sampling')
+    ->build();
+
+$transport = new StdioTransport(logger: logger());
+
+$server->connect($transport);
+
+$transport->listen();
+
+logger()->info('Server listener stopped gracefully.');

src/Capability/Registry/ReferenceHandler.php

@@ -13,6 +13,8 @@
 
 use Mcp\Exception\InvalidArgumentException;
 use Mcp\Exception\RegistryException;
+use Mcp\Server\ClientAwareInterface;
+use Mcp\Server\ClientGateway;
 use Psr\Container\ContainerInterface;
 
 /**
@@ -21,6 +23,7 @@
 final class ReferenceHandler implements ReferenceHandlerInterface
 {
     public function __construct(
+        private readonly ClientGateway $clientGateway,
         private readonly ?ContainerInterface $container = null,
     ) {
     }
@@ -36,6 +39,10 @@ public function handle(ElementReference $reference, array $arguments): mixed
                 $instance = $this->getClassInstance($reference->handler);
                 $arguments = $this->prepareArguments($reflection, $arguments);
 
+                if ($instance instanceof ClientAwareInterface) {
+                    $instance->setClientGateway($this->clientGateway);
+                }
+
                 return \call_user_func($instance, ...$arguments);
             }
 
@@ -58,6 +65,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($this->clientGateway);
+            }
+
             $arguments = $this->prepareArguments($reflection, $arguments);
 
             return \call_user_func([$instance, $methodName], ...$arguments);
@@ -131,6 +143,10 @@ private function getReflectionForCallable(callable $handler): \ReflectionMethod|
         if (\is_array($handler) && 2 === \count($handler)) {
             [$class, $method] = $handler;
 
+            if ($class instanceof ClientAwareInterface) {
+                $class->setClientGateway($this->clientGateway);
+            }
+
             return new \ReflectionMethod($class, $method);
         }
 

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
  * }
  *

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';
+}

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;
 
@@ -25,29 +26,30 @@
  */
 final class CreateSamplingMessageRequest extends Request
 {
+    protected string|int $id = 'create_sampling_message';
+
     /**
      * @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 +116,7 @@ protected function getParams(): array
         }
 
         if (null !== $this->includeContext) {
-            $params['includeContext'] = $this->includeContext;
+            $params['includeContext'] = $this->includeContext->value;
         }
 
         if (null !== $this->temperature) {

src/Server.php

@@ -12,6 +12,7 @@
 namespace Mcp;
 
 use Mcp\Server\Builder;
+use Mcp\Server\ClientGateway;
 use Mcp\Server\Handler\JsonRpcHandler;
 use Mcp\Server\Transport\TransportInterface;
 use Psr\Log\LoggerInterface;
@@ -26,6 +27,7 @@ final class Server
 {
     public function __construct(
         private readonly JsonRpcHandler $jsonRpcHandler,
+        private readonly ClientGateway $clientGateway,
         private readonly LoggerInterface $logger = new NullLogger(),
     ) {
     }
@@ -43,6 +45,8 @@ public function connect(TransportInterface $transport): void
             'transport' => $transport::class,
         ]);
 
+        $this->clientGateway->connect($transport);
+
         $transport->onMessage(function (string $message, ?Uuid $sessionId) use ($transport) {
             foreach ($this->jsonRpcHandler->process($message, $sessionId) as [$response, $context]) {
                 if (null === $response) {

src/Server/Builder.php

@@ -360,7 +360,8 @@ public function build(): Server
 
         $capabilities = $this->explicitCapabilities ?? $registry->getCapabilities();
         $configuration = new Configuration($this->serverInfo, $capabilities, $this->paginationLimit, $this->instructions);
-        $referenceHandler = new ReferenceHandler($container);
+        $clientGateway = new ClientGateway($logger);
+        $referenceHandler = new ReferenceHandler($clientGateway, $container);
 
         $methodHandlers = array_merge($this->customMethodHandlers, [
             new Handler\Request\PingHandler(),
@@ -384,7 +385,7 @@ public function build(): Server
             logger: $logger,
         );
 
-        return new Server($jsonRpcHandler, $logger);
+        return new Server($jsonRpcHandler, $clientGateway, $logger);
     }
 
     private function performDiscovery(

src/Server/ClientAwareInterface.php

@@ -0,0 +1,17 @@
+<?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\Server;
+
+interface ClientAwareInterface
+{
+    public function setClientGateway(ClientGateway $clientGateway): void;
+}