refactor: use specific exceptions in examples for better error handling

Author: CodeWithKyrian

examples/http-client-communication/server.php

@@ -14,6 +14,7 @@
 
 use Http\Discovery\Psr17Factory;
 use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
+use Mcp\Exception\ToolCallException;
 use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\Enum\LoggingLevel;
 use Mcp\Schema\JsonRpc\Error as JsonRpcError;
@@ -64,7 +65,7 @@ function (string $projectName, array $milestones, ClientGateway $client): array
             );
 
             if ($response instanceof JsonRpcError) {
-                throw new RuntimeException(sprintf('Sampling request failed (%d): %s', $response->code, $response->message));
+                throw new ToolCallException(sprintf('Sampling request failed (%d): %s', $response->code, $response->message));
             }
 
             $result = $response->result;

examples/http-discovery-userprofile/McpElements.php

@@ -16,6 +16,8 @@
 use Mcp\Capability\Attribute\McpResource;
 use Mcp\Capability\Attribute\McpResourceTemplate;
 use Mcp\Capability\Attribute\McpTool;
+use Mcp\Exception\PromptGetException;
+use Mcp\Exception\ResourceReadException;
 use Psr\Log\LoggerInterface;
 
 /**
@@ -47,7 +49,7 @@ public function __construct(
      *
      * @return User user profile data
      *
-     * @throws McpServerException if the user is not found
+     * @throws ResourceReadException if the user is not found
      */
     #[McpResourceTemplate(
         uriTemplate: 'user://{userId}/profile',
@@ -61,8 +63,7 @@ public function getUserProfile(
     ): array {
         $this->logger->info('Reading resource: user profile', ['userId' => $userId]);
         if (!isset($this->users[$userId])) {
-            // Throwing an exception that Processor can turn into an error response
-            throw McpServerException::invalidParams("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 McpServerException 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 McpServerException::invalidParams("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;

examples/stdio-discovery-calculator/McpElements.php

@@ -13,6 +13,7 @@
 
 use Mcp\Capability\Attribute\McpResource;
 use Mcp\Capability\Attribute\McpTool;
+use Mcp\Exception\ToolCallException;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 
@@ -44,10 +45,10 @@ public function __construct(
      * @param float  $b         the second operand
      * @param string $operation the operation ('add', 'subtract', 'multiply', 'divide')
      *
-     * @return float|string the result of the calculation, or an error message string
+     * @return float the result of the calculation
      */
     #[McpTool(name: 'calculate')]
-    public function calculate(float $a, float $b, string $operation): float|string
+    public function calculate(float $a, float $b, string $operation): float
     {
         $this->logger->info(\sprintf('Calculating: %f %s %f', $a, $operation, $b));
 
@@ -65,16 +66,16 @@ public function calculate(float $a, float $b, string $operation): float|string
                 break;
             case 'divide':
                 if (0 == $b) {
-                    return 'Error: Division by zero.';
+                    throw new ToolCallException('Division by zero is not allowed.');
                 }
                 $result = $a / $b;
                 break;
             default:
-                return "Error: Unknown operation '{$operation}'. Supported: add, subtract, multiply, divide.";
+                throw new ToolCallException("Unknown operation '{$operation}'. Supported: add, subtract, multiply, divide.");
         }
 
         if (!$this->config['allow_negative'] && $result < 0) {
-            return 'Error: Negative results are disabled.';
+            throw new ToolCallException('Negative results are disabled.');
         }
 
         return round($result, $this->config['precision']);

phpstan-baseline.neon

@@ -1,17 +1,5 @@
 parameters:
 	ignoreErrors:
-		-
-			message: '#^Call to static method invalidParams\(\) on an unknown class Mcp\\Example\\HttpDiscoveryUserProfile\\McpServerException\.$#'
-			identifier: class.notFound
-			count: 2
-			path: examples/http-discovery-userprofile/McpElements.php
-
-		-
-			message: '#^PHPDoc tag @throws with type Mcp\\Example\\HttpDiscoveryUserProfile\\McpServerException is not subtype of Throwable$#'
-			identifier: throws.notThrowable
-			count: 2
-			path: examples/http-discovery-userprofile/McpElements.php
-
 		-
 			message: '#^Method Mcp\\Schema\\Result\\ReadResourceResult\:\:jsonSerialize\(\) should return array\{contents\: array\<Mcp\\Schema\\Content\\BlobResourceContents\|Mcp\\Schema\\Content\\TextResourceContents\>\} but returns array\{contents\: array\<Mcp\\Schema\\Content\\ResourceContents\>\}\.$#'
 			identifier: return.type