Merge branch 'main' of github.com:kaipiyann/php-sdk

Author: kaipiyann

README.md

@@ -254,6 +254,7 @@ $server = Server::builder()
 - [Server Builder](docs/server-builder.md) - Complete ServerBuilder reference and configuration
 - [Transports](docs/transports.md) - STDIO and HTTP transport setup and usage
 - [MCP Elements](docs/mcp-elements.md) - Creating tools, resources, and prompts
+- [Client Communiocation](docs/client-communication.md) - Communicating back to the client from server-side
 
 **Learning:**
 - [Examples](docs/examples.md) - Comprehensive example walkthroughs

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/",

docs/client-communication.md

@@ -0,0 +1,101 @@
+# Client Communication
+
+MCP supports various ways a server can communicate back to a server on top of the main request-response flow.
+
+## Table of Contents
+
+- [ClientGateway](#client-gateway)
+- [Sampling](#sampling)
+- [Logging](#logging)
+- [Notification](#notification)
+- [Progress](#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, there are two ways to do so:
+
+### 1. Method Argument Injection
+
+Every refernce of a MCP element, that translates to an actual method call, can just add an type-hinted argument for the
+`ClientGateway` and the SDK will take care to include the gateway in the arguments of the method call:
+
+```php
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Server\ClientGateway;
+
+class MyService
+{
+    #[McpTool('my_tool', 'My Tool Description')]
+    public function myTool(ClientGateway $client): string
+    {
+        $client->log(...);
+```
+
+### 2. Implementing `ClientAwareInterface`
+
+Whenever a service class of an MCP element implements the interface `Mcp\Server\ClientAwareInterface` the `setClient`
+method of that class will get called while handling the reference, and in combination with `Mcp\Server\ClientAwareTrait`
+this ends up with code like this:
+
+```php
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Server\ClientAwareInterface;
+use Mcp\Server\ClientAwareTrait;
+
+class MyService implements ClientAwareInterface
+{
+    use ClientAwareTrait;
+
+    #[McpTool('my_tool', 'My Tool Description')]
+    public function myTool(): string
+    {
+        $this->log(...);
+```
+
+## Sampling
+
+With [sampling](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling) servers can request clients to
+execute "completions" or "generations" with a language model for them:
+
+```php
+$result = $clientGateway->sample('Roses are red, violets are', 350, 90, ['temperature' => 0.5]);
+```
+
+The `sample` method accepts four arguments:
+
+1. `message`, which is **required** and accepts a string, an instance of `Content` or an array of `SampleMessage` instances.
+2. `maxTokens`, which defaults to `1000`
+3. `timeout` in seconds, which defaults to `120`
+4. `options` which might include `system_prompt`, `preferences` for model choice, `includeContext`, `temperature`, `stopSequences` and `metadata`
+
+[Find more details to sampling payload in the specification.](https://modelcontextprotocol.io/specification/2025-06-18/client/sampling#protocol-messages)
+
+## Logging
+
+The [Logging](https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging) utility enables servers
+to send structured log messages as notifcation to clients:
+
+```php
+use Mcp\Schema\Enum\LoggingLevel;
+
+$clientGateway->log(LoggingLevel::Warning, 'The end is near.');
+```
+
+## Progress
+
+With a [Progress](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress#progress)
+notification a server can update a client while an operation is ongoing:
+
+```php
+$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:
+
+```php
+$clientGateway->notify($yourNotification);
+```

docs/examples.md

@@ -163,6 +163,16 @@ $server = Server::builder()
     ->setDiscovery(__DIR__, ['.'], [], $cache)
 ```
 
+### Client Communication
+
+**File**: `examples/stdio-client-communication/`
+
+**What it demostrates:**
+- Server initiated communcation back to the client
+- Logging, sampling, progress and notifications
+- Using `ClientGateway` in service class via `ClientAwareInterface` and corresponding trait
+- Using `ClientGateway` in tool method via method argument injection
+
 ## HTTP Examples
 
 ### Discovery User Profile

docs/mcp-elements.md

@@ -154,31 +154,37 @@ public function getMultipleContent(): array
 
 #### Error Handling
 
-Tools can throw exceptions which are automatically converted to proper JSON-RPC error responses:
+Tool handlers can throw any exception, but the type determines how it's handled:
+
+- **`ToolCallException`**: Converted to JSON-RPC response with `CallToolResult` where `isError: true`, allowing the LLM to see the error message and self-correct
+- **Any other exception**: Converted to JSON-RPC error response, but with a generic error message
 
 ```php
+use Mcp\Exception\ToolCallException;
+
 #[McpTool]
 public function divideNumbers(float $a, float $b): float
 {
     if ($b === 0.0) {
-        throw new \InvalidArgumentException('Division by zero is not allowed');
+        throw new ToolCallException('Division by zero is not allowed');
     }
-    
+
     return $a / $b;
 }
 
 #[McpTool]
 public function processFile(string $filename): string
 {
     if (!file_exists($filename)) {
-        throw new \InvalidArgumentException("File not found: {$filename}");
+        throw new ToolCallException("File not found: {$filename}");
     }
-    
+
     return file_get_contents($filename);
 }
 ```
 
-The SDK will convert these exceptions into appropriate JSON-RPC error responses that MCP clients can understand.
+**Recommendation**: Use `ToolCallException` when you want to communicate specific errors to clients. Any other exception will still be converted to JSON-RPC compliant errors but with generic error messages.
+
 
 ## Resources
 
@@ -298,24 +304,31 @@ public function getMultipleResources(): array
 
 #### Error Handling
 
-Resource handlers can throw exceptions for error cases:
+Resource handlers can throw any exception, but the type determines how it's handled:
+
+- **`ResourceReadException`**: Converted to JSON-RPC error response with the actual exception message
+- **Any other exception**: Converted to JSON-RPC error response, but with a generic error message
 
 ```php
+use Mcp\Exception\ResourceReadException;
+
 #[McpResource(uri: 'file://{path}')]
 public function getFile(string $path): string
 {
     if (!file_exists($path)) {
-        throw new \InvalidArgumentException("File not found: {$path}");
+        throw new ResourceReadException("File not found: {$path}");
     }
-    
+
     if (!is_readable($path)) {
-        throw new \RuntimeException("File not readable: {$path}");
+        throw new ResourceReadException("File not readable: {$path}");
     }
-    
+
     return file_get_contents($path);
 }
 ```
 
+**Recommendation**: Use `ResourceReadException` when you want to communicate specific errors to clients. Any other exception will still be converted to JSON-RPC compliant errors but with generic error messages.
+
 ## Resource Templates
 
 Resource templates are **dynamic resources** that use parameterized URIs with variables. They follow all the same rules
@@ -449,40 +462,44 @@ public function explicitMessages(): array
 }
 ```
 
+The SDK automatically validates that all messages have valid roles and converts the result into the appropriate MCP prompt message format.
+
 #### Valid Message Roles
 
 - **`user`**: User input or questions  
 - **`assistant`**: Assistant responses/system 
 
 #### Error Handling
 
-Prompt handlers can throw exceptions for invalid inputs:
+Prompt handlers can throw any exception, but the type determines how it's handled:
+- **`PromptGetException`**: Converted to JSON-RPC error response with the actual exception message
+- **Any other exception**: Converted to JSON-RPC error response, but with a generic error message
 
 ```php
+use Mcp\Exception\PromptGetException;
+
 #[McpPrompt]
 public function generatePrompt(string $topic, string $style): array
 {
     $validStyles = ['casual', 'formal', 'technical'];
-    
+
     if (!in_array($style, $validStyles)) {
-        throw new \InvalidArgumentException(
+        throw new PromptGetException(
             "Invalid style '{$style}'. Must be one of: " . implode(', ', $validStyles)
         );
     }
-    
+
     return [
         ['role' => 'user', 'content' => "Write about {$topic} in a {$style} style"]
     ];
 }
 ```
 
-The SDK automatically validates that all messages have valid roles and converts the result into the appropriate MCP prompt message format.
+**Recommendation**: Use `PromptGetException` when you want to communicate specific errors to clients. Any other exception will still be converted to JSON-RPC compliant errors but with generic error messages.
 
 ## Completion Providers
 
-Completion providers help MCP clients offer auto-completion suggestions for Resource Templates and Prompts. Unlike Tools
-and static Resources (which can be listed via `tools/list` and `resources/list`), Resource Templates and Prompts have
-dynamic parameters that benefit from completion hints.
+Completion providers help MCP clients offer auto-completion suggestions for Resource Templates and Prompts. Unlike Tools and static Resources (which can be listed via `tools/list` and `resources/list`), Resource Templates and Prompts have dynamic parameters that benefit from completion hints.
 
 ### Completion Provider Types
 

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(
-                prompt: $prompt,
+            $result = $client->sample(
+                message: $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.');

examples/http-discovery-userprofile/McpElements.php

@@ -16,7 +16,8 @@
 use Mcp\Capability\Attribute\McpResource;
 use Mcp\Capability\Attribute\McpResourceTemplate;
 use Mcp\Capability\Attribute\McpTool;
-use Mcp\Exception\InvalidArgumentException;
+use Mcp\Exception\PromptGetException;
+use Mcp\Exception\ResourceReadException;
 use Psr\Log\LoggerInterface;
 
 /**
@@ -48,7 +49,7 @@ public function __construct(
      *
      * @return User user profile data
      *
-     * @throws InvalidArgumentException if the user is not found
+     * @throws ResourceReadException if the user is not found
      */
     #[McpResourceTemplate(
         uriTemplate: 'user://{userId}/profile',
@@ -62,7 +63,7 @@ public function getUserProfile(
     ): array {
         $this->logger->info('Reading resource: user profile', ['userId' => $userId]);
         if (!isset($this->users[$userId])) {
-            throw new InvalidArgumentException("User profile not found for ID: {$userId}");
+            throw new ResourceReadException("User not found for ID: {$userId}");
         }
 
         return $this->users[$userId];
@@ -130,7 +131,7 @@ public function testToolWithoutParams(): array
      *
      * @return array<string, string>[] prompt messages
      *
-     * @throws InvalidArgumentException if user not found
+     * @throws PromptGetException if user not found
      */
     #[McpPrompt(name: 'generate_bio_prompt')]
     public function generateBio(
@@ -140,7 +141,7 @@ public function generateBio(
     ): array {
         $this->logger->info('Executing prompt: generate_bio', ['userId' => $userId, 'tone' => $tone]);
         if (!isset($this->users[$userId])) {
-            throw new InvalidArgumentException("User not found for bio prompt: {$userId}");
+            throw new PromptGetException("User not found for bio prompt: {$userId}");
         }
         $user = $this->users[$userId];
 

examples/stdio-cached-discovery/CachedCalculatorElements.php

@@ -14,6 +14,7 @@
 namespace Mcp\Example\StdioCachedDiscovery;
 
 use Mcp\Capability\Attribute\McpTool;
+use Mcp\Exception\ToolCallException;
 
 /**
  * Example MCP elements for demonstrating cached discovery.
@@ -39,7 +40,7 @@ public function multiply(int $a, int $b): int
     public function divide(int $a, int $b): float
     {
         if (0 === $b) {
-            throw new \InvalidArgumentException('Division by zero is not allowed');
+            throw new ToolCallException('Division by zero is not allowed');
         }
 
         return $a / $b;