fix: standardize error handling across handlers with MCP specification compliance

Author: CodeWithKyrian

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:
+**Tools should ONLY throw `ToolCallException` for any error that occurs during tool execution.**
 
 ```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.
+**Critical Rule:** For tool handlers, **ALWAYS** throw `ToolCallException` for any error condition - validation errors, file not found, processing errors, etc. Do not use generic PHP exceptions.
+
+**Error Handling Behavior:**
+- **`ToolCallException`**: Converted to `CallToolResult` with `isError: true`, allowing the LLM to see the error message and self-correct
+- **Any other exception**: Treated as internal server error and returns a generic error message to client
 
 ## Resources
 
@@ -298,24 +304,33 @@ public function getMultipleResources(): array
 
 #### Error Handling
 
-Resource handlers can throw exceptions for error cases:
+**Resource handlers should ONLY throw `ResourceReadException` for any error that occurs during resource reading.**
 
 ```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);
 }
 ```
 
+**Critical Rule:** For resource handlers, **ALWAYS** throw `ResourceReadException` for any error condition - file not found, permission errors, data format issues, etc. Do not use generic PHP exceptions.
+
+**Error Handling Behavior:**
+- **`ResourceReadException`**: Converted to JSON-RPC error response with the actual exception message
+- **Any other exception**: Treated as internal server error and returns a generic error message to client
+
+
 ## Resource Templates
 
 Resource templates are **dynamic resources** that use parameterized URIs with variables. They follow all the same rules
@@ -456,26 +471,34 @@ public function explicitMessages(): array
 
 #### Error Handling
 
-Prompt handlers can throw exceptions for invalid inputs:
+**Prompt handlers should ONLY throw `PromptGetException` for any error that occurs during prompt generation.**
 
 ```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"]
     ];
 }
 ```
 
+**Critical Rule:** For prompt handlers, **ALWAYS** throw `PromptGetException` for any error condition - invalid parameters, data validation errors, template processing issues, etc. Do not use generic PHP exceptions.
+
+**Error Handling Behavior:**
+- **`PromptGetException`**: Converted to JSON-RPC error response with the actual exception message
+- **Any other exception**: Treated as internal server error and returns a generic error message to client
+
 The SDK automatically validates that all messages have valid roles and converts the result into the appropriate MCP prompt message format.
 
 ## Completion Providers

src/Schema/JsonRpc/Error.php

@@ -106,6 +106,11 @@ public static function forServerError(string $message, string|int $id = ''): sel
         return new self($id, self::SERVER_ERROR, $message);
     }
 
+    public static function forResourceNotFound(string $message, string|int $id = ''): self
+    {
+        return new self($id, self::RESOURCE_NOT_FOUND, $message);
+    }
+
     public function getId(): string|int
     {
         return $this->id;

src/Server/Handler/Request/CallToolHandler.php

@@ -13,9 +13,9 @@
 
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\Registry\ReferenceProviderInterface;
-use Mcp\Exception\ExceptionInterface;
 use Mcp\Exception\ToolCallException;
 use Mcp\Exception\ToolNotFoundException;
+use Mcp\Schema\Content\TextContent;
 use Mcp\Schema\JsonRpc\Error;
 use Mcp\Schema\JsonRpc\Request;
 use Mcp\Schema\JsonRpc\Response;
@@ -77,17 +77,19 @@ public function handle(Request $request, SessionInterface $session): Response|Er
             ]);
 
             return new Response($request->getId(), $result);
-        } catch (ToolNotFoundException $e) {
-            $this->logger->error('Tool not found', ['name' => $toolName]);
-
-            return new Error($request->getId(), Error::METHOD_NOT_FOUND, $e->getMessage());
-        } catch (ToolCallException|ExceptionInterface $e) {
+        } catch (ToolCallException $e) {
             $this->logger->error(\sprintf('Error while executing tool "%s": "%s".', $toolName, $e->getMessage()), [
                 'tool' => $toolName,
                 'arguments' => $arguments,
             ]);
 
-            return Error::forInternalError('Error while executing tool', $request->getId());
+            $errorContent = [new TextContent($e->getMessage())];
+
+            return new Response($request->getId(), CallToolResult::error($errorContent));
+        } catch (ToolNotFoundException $e) {
+            $this->logger->error('Tool not found', ['name' => $toolName]);
+
+            return new Error($request->getId(), Error::METHOD_NOT_FOUND, $e->getMessage());
         } catch (\Throwable $e) {
             $this->logger->error('Unhandled error during tool execution', [
                 'name' => $toolName,

src/Server/Handler/Request/GetPromptHandler.php

@@ -13,7 +13,6 @@
 
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\Registry\ReferenceProviderInterface;
-use Mcp\Exception\ExceptionInterface;
 use Mcp\Exception\PromptGetException;
 use Mcp\Exception\PromptNotFoundException;
 use Mcp\Schema\JsonRpc\Error;
@@ -67,18 +66,18 @@ public function handle(Request $request, SessionInterface $session): Response|Er
             $formatted = $reference->formatResult($result);
 
             return new Response($request->getId(), new GetPromptResult($formatted));
+        } catch (PromptGetException $e) {
+            $this->logger->error(\sprintf('Error while handling prompt "%s": "%s".', $promptName, $e->getMessage()));
+
+            return Error::forInternalError($e->getMessage(), $request->getId());
         } catch (PromptNotFoundException $e) {
             $this->logger->error('Prompt not found', ['prompt_name' => $promptName]);
 
-            return new Error($request->getId(), Error::METHOD_NOT_FOUND, $e->getMessage());
-        } catch (PromptGetException|ExceptionInterface $e) {
-            $this->logger->error('Error while handling prompt', ['prompt_name' => $promptName]);
-
-            return Error::forInternalError('Error while handling prompt: '.$e->getMessage(), $request->getId());
+            return Error::forResourceNotFound($e->getMessage(), $request->getId());
         } catch (\Throwable $e) {
-            $this->logger->error('Error while handling prompt', ['prompt_name' => $promptName]);
+            $this->logger->error(\sprintf('Unexpected error while handling prompt "%s": "%s".', $promptName, $e->getMessage()));
 
-            return Error::forInternalError('Error while handling prompt: '.$e->getMessage(), $request->getId());
+            return Error::forInternalError('Error while handling prompt', $request->getId());
         }
     }
 }

src/Server/Handler/Request/ReadResourceHandler.php

@@ -15,6 +15,7 @@
 use Mcp\Capability\Registry\ReferenceProviderInterface;
 use Mcp\Capability\Registry\ResourceTemplateReference;
 use Mcp\Exception\ResourceNotFoundException;
+use Mcp\Exception\ResourceReadException;
 use Mcp\Schema\JsonRpc\Error;
 use Mcp\Schema\JsonRpc\Request;
 use Mcp\Schema\JsonRpc\Response;
@@ -74,12 +75,16 @@ public function handle(Request $request, SessionInterface $session): Response|Er
             }
 
             return new Response($request->getId(), new ReadResourceResult($formatted));
+        } catch (ResourceReadException $e) {
+            $this->logger->error(\sprintf('Error while reading resource "%s": "%s".', $uri, $e->getMessage()));
+
+            return Error::forInternalError($e->getMessage(), $request->getId());
         } catch (ResourceNotFoundException $e) {
             $this->logger->error('Resource not found', ['uri' => $uri]);
 
-            return new Error($request->getId(), Error::RESOURCE_NOT_FOUND, $e->getMessage());
+            return Error::forResourceNotFound($e->getMessage(), $request->getId());
         } catch (\Throwable $e) {
-            $this->logger->error(\sprintf('Error while reading resource "%s": "%s".', $uri, $e->getMessage()));
+            $this->logger->error(\sprintf('Unexpected error while reading resource "%s": "%s".', $uri, $e->getMessage()));
 
             return Error::forInternalError('Error while reading resource', $request->getId());
         }

tests/Unit/Server/Handler/Request/CallToolHandlerTest.php

@@ -177,7 +177,7 @@ public function testHandleToolNotFoundExceptionReturnsError(): void
         $this->assertEquals(Error::METHOD_NOT_FOUND, $response->code);
     }
 
-    public function testHandleToolExecutionExceptionReturnsError(): void
+    public function testHandleToolCallExceptionReturnsResponseWithErrorResult(): void
     {
         $request = $this->createCallToolRequest('failing_tool', ['param' => 'value']);
         $exception = new ToolCallException($request, new \RuntimeException('Tool execution failed'));
@@ -201,9 +201,15 @@ public function testHandleToolExecutionExceptionReturnsError(): void
 
         $response = $this->handler->handle($request, $this->session);
 
-        $this->assertInstanceOf(Error::class, $response);
+        $this->assertInstanceOf(Response::class, $response);
         $this->assertEquals($request->getId(), $response->id);
-        $this->assertEquals(Error::INTERNAL_ERROR, $response->code);
+
+        $result = $response->result;
+        $this->assertInstanceOf(CallToolResult::class, $result);
+        $this->assertTrue($result->isError);
+        $this->assertCount(1, $result->content);
+        $this->assertInstanceOf(TextContent::class, $result->content[0]);
+        $this->assertEquals('Tool call "failing_tool" failed with error: "Tool execution failed".', $result->content[0]->text);
     }
 
     public function testHandleWithNullResult(): void
@@ -274,8 +280,43 @@ public function testHandleLogsErrorWithCorrectParameters(): void
 
         $response = $this->handler->handle($request, $this->session);
 
+        // ToolCallException should now return Response with CallToolResult having isError=true
+        $this->assertInstanceOf(Response::class, $response);
+        $this->assertEquals($request->getId(), $response->id);
+
+        $result = $response->result;
+        $this->assertInstanceOf(CallToolResult::class, $result);
+        $this->assertTrue($result->isError);
+        $this->assertCount(1, $result->content);
+        $this->assertInstanceOf(TextContent::class, $result->content[0]);
+        $this->assertEquals('Tool call "test_tool" failed with error: "Custom error message".', $result->content[0]->text);
+    }
+
+    public function testHandleGenericExceptionReturnsError(): void
+    {
+        $request = $this->createCallToolRequest('failing_tool', ['param' => 'value']);
+        $exception = new \RuntimeException('Internal database connection failed');
+
+        $toolReference = $this->createMock(ToolReference::class);
+        $this->referenceProvider
+            ->expects($this->once())
+            ->method('getTool')
+            ->with('failing_tool')
+            ->willReturn($toolReference);
+
+        $this->referenceHandler
+            ->expects($this->once())
+            ->method('handle')
+            ->with($toolReference, ['param' => 'value', '_session' => $this->session])
+            ->willThrowException($exception);
+
+        $response = $this->handler->handle($request, $this->session);
+
+        // Generic exceptions should return Error, not Response
         $this->assertInstanceOf(Error::class, $response);
+        $this->assertEquals($request->getId(), $response->id);
         $this->assertEquals(Error::INTERNAL_ERROR, $response->code);
+        $this->assertEquals('Error while executing tool', $response->message);
     }
 
     public function testHandleWithSpecialCharactersInToolName(): void

tests/Unit/Server/Handler/Request/GetPromptHandlerTest.php

@@ -243,7 +243,7 @@ public function testHandlePromptNotFoundExceptionReturnsError(): void
 
         $this->assertInstanceOf(Error::class, $response);
         $this->assertEquals($request->getId(), $response->id);
-        $this->assertEquals(Error::METHOD_NOT_FOUND, $response->code);
+        $this->assertEquals(Error::RESOURCE_NOT_FOUND, $response->code);
         $this->assertEquals('Prompt not found for name: "nonexistent_prompt".', $response->message);
     }
 
@@ -263,7 +263,7 @@ public function testHandlePromptGetExceptionReturnsError(): void
         $this->assertInstanceOf(Error::class, $response);
         $this->assertEquals($request->getId(), $response->id);
         $this->assertEquals(Error::INTERNAL_ERROR, $response->code);
-        $this->assertEquals('Error while handling prompt: Handling prompt "failing_prompt" failed with error: "Failed to get prompt".', $response->message);
+        $this->assertEquals('Handling prompt "failing_prompt" failed with error: "Failed to get prompt".', $response->message);
     }
 
     public function testHandlePromptGetWithComplexArguments(): void

tests/Unit/Server/Handler/Request/ReadResourceHandlerTest.php

@@ -194,7 +194,7 @@ public function testHandleResourceNotFoundExceptionReturnsSpecificError(): void
         $this->assertEquals('Resource not found for uri: "'.$uri.'".', $response->message);
     }
 
-    public function testHandleResourceReadExceptionReturnsGenericError(): void
+    public function testHandleResourceReadExceptionReturnsActualErrorMessage(): void
     {
         $uri = 'file://corrupted/file.txt';
         $request = $this->createReadResourceRequest($uri);
@@ -211,6 +211,26 @@ public function testHandleResourceReadExceptionReturnsGenericError(): void
 
         $response = $this->handler->handle($request, $this->session);
 
+        $this->assertInstanceOf(Error::class, $response);
+        $this->assertEquals($request->getId(), $response->id);
+        $this->assertEquals(Error::INTERNAL_ERROR, $response->code);
+        $this->assertEquals('Reading resource "file://corrupted/file.txt" failed with error: "Failed to read resource: corrupted data".', $response->message);
+    }
+
+    public function testHandleGenericExceptionReturnsGenericError(): void
+    {
+        $uri = 'file://problematic/file.txt';
+        $request = $this->createReadResourceRequest($uri);
+        $exception = new \RuntimeException('Internal database connection failed');
+
+        $this->referenceProvider
+            ->expects($this->once())
+            ->method('getResource')
+            ->with($uri)
+            ->willThrowException($exception);
+
+        $response = $this->handler->handle($request, $this->session);
+
         $this->assertInstanceOf(Error::class, $response);
         $this->assertEquals($request->getId(), $response->id);
         $this->assertEquals(Error::INTERNAL_ERROR, $response->code);