Enhance error handling with additional context data

Updated JsonRpcErrorException instances to include relevant context data for better debugging. Adjusted test cases accordingly to validate the new data fields. Added detailed comments to improve code clarity for message handling methods.

Author: klapaudius

src/Protocol/MCPProtocol.php

@@ -122,7 +122,7 @@ public function handleMessage(string $clientId, array $message): void
         $messageId = $message['id'] ?? null;
         try {
             if (! isset($message['jsonrpc']) || $message['jsonrpc'] !== '2.0') {
-                throw new JsonRpcErrorException(message: 'Invalid Request: Not a valid JSON-RPC 2.0 message', code: JsonRpcErrorCode::INVALID_REQUEST);
+                throw new JsonRpcErrorException(message: 'Invalid Request: Not a valid JSON-RPC 2.0 message', code: JsonRpcErrorCode::INVALID_REQUEST, data: $message);
             }
 
             $requestData = DataUtil::makeRequestData(message: $message);
@@ -137,7 +137,7 @@ public function handleMessage(string $clientId, array $message): void
                 return;
             }
 
-            throw new JsonRpcErrorException(message: 'Invalid Request: Message format not recognized', code: JsonRpcErrorCode::INVALID_REQUEST);
+            throw new JsonRpcErrorException(message: 'Invalid Request: Message format not recognized', code: JsonRpcErrorCode::INVALID_REQUEST, data: $message);
         } catch (JsonRpcErrorException $e) {
             $this->pushMessage(clientId: $clientId, message: new JsonRpcErrorResource(exception: $e, id: $messageId));
         } catch (Exception $e) {
@@ -168,7 +168,7 @@ private function handleRequestProcess(string $clientId, RequestData $requestData
                 }
             }
 
-            throw new JsonRpcErrorException("Method not found: {$requestData->method}", JsonRpcErrorCode::METHOD_NOT_FOUND);
+            throw new JsonRpcErrorException("Method not found: {$requestData->method}", JsonRpcErrorCode::METHOD_NOT_FOUND, data: $requestData->toArray());
         } catch (JsonRpcErrorException $e) {
             $this->pushMessage(clientId: $clientId, message: new JsonRpcErrorResource(exception: $e, id: $messageId));
         } catch (ToolParamsValidatorException $e) {
@@ -199,7 +199,7 @@ private function handleNotificationProcess(string $clientId, NotificationData $n
                 }
             }
 
-            throw new JsonRpcErrorException("Method not found: {$notificationData->method}", JsonRpcErrorCode::METHOD_NOT_FOUND);
+            throw new JsonRpcErrorException("Method not found: {$notificationData->method}", JsonRpcErrorCode::METHOD_NOT_FOUND, data: $notificationData->toArray());
         } catch (JsonRpcErrorException $e) {
             $this->pushMessage(clientId: $clientId, message: new JsonRpcErrorResource(exception: $e, id: null));
         } catch (Exception $e) {
@@ -209,7 +209,12 @@ private function handleNotificationProcess(string $clientId, NotificationData $n
     }
 
     /**
-     * @throws Exception
+     * Pushes a message to a specified client.
+     *
+     * @param string $clientId The unique identifier of the client to push the message to.
+     * @param array|JsonRpcResultResource|JsonRpcErrorResource $message The message to be pushed to the client, either as an array or an instance of JsonRpcResultResource/JsonRpcErrorResource.
+     *
+     * @throws Exception If transport is unable to push the message to client
      */
     private function pushMessage(string $clientId, array|JsonRpcResultResource|JsonRpcErrorResource $message): void
     {
@@ -222,6 +227,14 @@ private function pushMessage(string $clientId, array|JsonRpcResultResource|JsonR
         $this->transport->pushMessage(clientId: $clientId, message: $message);
     }
 
+    /**
+     * Process an incoming message from a specified client.
+     *
+     * @param string $clientId The unique identifier of the client.
+     * @param array $message The message data to be processed.
+     *
+     * @throws Exception If the message cannot be processed
+     */
     public function requestMessage(string $clientId, array $message): void
     {
         $this->transport->processMessage(clientId: $clientId, message: $message);

src/Server/MCPServer.php

@@ -164,7 +164,7 @@ public function registerNotificationHandler(NotificationHandler $handler): void
     public function initialize(InitializeData $data): InitializeResource
     {
         if ($this->initialized) {
-            throw new JsonRpcErrorException(message: 'Server already initialized', code: JsonRpcErrorCode::INVALID_REQUEST);
+            throw new JsonRpcErrorException(message: 'Server already initialized', code: JsonRpcErrorCode::INVALID_REQUEST, data: $data);
         }
 
         $this->initialized = true;

src/Server/Request/ToolsCallHandler.php

@@ -37,12 +37,12 @@ public function execute(string $method, ?array $params = null): array
     {
         $name = $params['name'] ?? null;
         if ($name === null) {
-            throw new JsonRpcErrorException(message: 'Tool name is required', code: JsonRpcErrorCode::INVALID_REQUEST);
+            throw new JsonRpcErrorException(message: 'Tool name is required', code: JsonRpcErrorCode::INVALID_REQUEST, data: $params);
         }
 
         $tool = $this->toolRepository->getTool($name);
         if (! $tool) {
-            throw new JsonRpcErrorException(message: "Tool '{$name}' not found", code: JsonRpcErrorCode::METHOD_NOT_FOUND);
+            throw new JsonRpcErrorException(message: "Tool '{$name}' not found", code: JsonRpcErrorCode::METHOD_NOT_FOUND, data:$params);
         }
 
         $arguments = $params['arguments'] ?? [];

tests/Server/MCPServerTest.php

@@ -249,11 +249,16 @@ public function test_initialize_throws_when_already_initialized(): void
         $server->initialize($initializeData);
 
         // Expect
-        $this->expectException(JsonRpcErrorException::class);
-        $this->expectExceptionMessage('Server already initialized');
 
         // Act
-        $server->initialize($initializeData);
+        try {
+            $server->initialize($initializeData);
+            $this->fail('Expected exception not thrown');
+        } catch (JsonRpcErrorException $e) {
+            $this->assertEquals(-32600, $e->getJsonRpcErrorCode());
+            $this->assertEquals('Server already initialized', $e->getMessage());
+            $this->assertEquals($initializeData, $e->getErrorData());
+        }
     }
 
     /**