refactor(exception): replace InvalidArgumentException with ValidationError and ProtocolError for improved error handling

Author: lihq1403

docs/cn/server/http-server.md

@@ -195,7 +195,7 @@ function createFileUploadTool(): RegisteredTool {
         // 验证文件名
         $filename = basename($filename);
         if (empty($filename)) {
-            throw new InvalidArgumentException('无效的文件名');
+                            throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('无效的文件名');
         }
 
         // 如果目录不存在则创建
@@ -207,7 +207,7 @@ function createFileUploadTool(): RegisteredTool {
         // 解码并保存文件
         $decodedContent = base64_decode($content);
         if ($decodedContent === false) {
-            throw new InvalidArgumentException('无效的 base64 内容');
+                                throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('无效的 base64 内容');
         }
 
         $filepath = $uploadDir . '/' . $filename;

docs/cn/server/hyperf-integration.md

@@ -873,7 +873,7 @@ class UserService
         ];
 
         if (!isset($users[$userId])) {
-            throw new \InvalidArgumentException("用户 {$userId} 不存在");
+                            throw ValidationError::requiredFieldMissing('user', '用户 {$userId} 不存在');
         }
 
         return ['user' => $users[$userId]];

docs/cn/server/stdio-server.md

@@ -277,11 +277,11 @@ function createCalculatorTool(): RegisteredTool {
             case 'subtract': $result = $a - $b; break;
             case 'multiply': $result = $a * $b; break;
             case 'divide':
-                if ($b == 0) throw new InvalidArgumentException('除零错误');
+                if ($b == 0) throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('除零错误');
                 $result = $a / $b;
                 break;
             default:
-                throw new InvalidArgumentException('未知操作: ' . $operation);
+                throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('未知操作: ' . $operation);
         }
 
         return [

docs/en/server/http-server.md

@@ -195,7 +195,7 @@ function createFileUploadTool(): RegisteredTool {
         // Validate filename
         $filename = basename($filename);
         if (empty($filename)) {
-            throw new InvalidArgumentException('Invalid filename');
+                            throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('Invalid filename');
         }
 
         // Create directory if it doesn't exist
@@ -207,7 +207,7 @@ function createFileUploadTool(): RegisteredTool {
         // Decode and save file
         $decodedContent = base64_decode($content);
         if ($decodedContent === false) {
-            throw new InvalidArgumentException('Invalid base64 content');
+                                throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('Invalid base64 content');
         }
 
         $filepath = $uploadDir . '/' . $filename;

docs/en/server/hyperf-integration.md

@@ -873,7 +873,7 @@ class UserService
         ];
 
         if (!isset($users[$userId])) {
-            throw new \InvalidArgumentException("User {$userId} not found");
+                            throw ValidationError::requiredFieldMissing('user', 'User {$userId} not found');
         }
 
         return ['user' => $users[$userId]];

docs/en/server/stdio-server.md

@@ -280,11 +280,11 @@ function createCalculatorTool(): RegisteredTool {
             case 'subtract': $result = $a - $b; break;
             case 'multiply': $result = $a * $b; break;
             case 'divide':
-                if ($b == 0) throw new InvalidArgumentException('Division by zero');
+                if ($b == 0) throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('Division by zero');
                 $result = $a / $b;
                 break;
             default:
-                throw new InvalidArgumentException('Unknown operation: ' . $operation);
+                throw new \Dtyq\PhpMcp\Shared\Exceptions\ValidationError('Unknown operation: ' . $operation);
         }
 
         return [

examples/http-server-test.php

@@ -11,6 +11,7 @@
 use Dtyq\PhpMcp\Server\FastMcp\Resources\RegisteredResourceTemplate;
 use Dtyq\PhpMcp\Server\FastMcp\Tools\RegisteredTool;
 use Dtyq\PhpMcp\Server\McpServer;
+use Dtyq\PhpMcp\Shared\Exceptions\ValidationError;
 use Dtyq\PhpMcp\Shared\Kernel\Application;
 use Dtyq\PhpMcp\Types\Constants\MessageConstants;
 use Dtyq\PhpMcp\Types\Content\TextContent;
@@ -287,12 +288,12 @@ function createCalculatorTool(): RegisteredTool
                 break;
             case 'divide':
                 if ($b == 0) {
-                    throw new InvalidArgumentException('Division by zero');
+                    throw ValidationError::invalidFieldValue('divisor', 'cannot be zero');
                 }
                 $result = $a / $b;
                 break;
             default:
-                throw new InvalidArgumentException('Unknown operation: ' . $operation);
+                throw ValidationError::invalidFieldValue('operation', 'unknown operation: ' . $operation);
         }
 
         return [

examples/stdio-server-test.php

@@ -11,6 +11,7 @@
 use Dtyq\PhpMcp\Server\FastMcp\Resources\RegisteredResourceTemplate;
 use Dtyq\PhpMcp\Server\FastMcp\Tools\RegisteredTool;
 use Dtyq\PhpMcp\Server\McpServer;
+use Dtyq\PhpMcp\Shared\Exceptions\ValidationError;
 use Dtyq\PhpMcp\Shared\Kernel\Application;
 use Dtyq\PhpMcp\Types\Constants\MessageConstants;
 use Dtyq\PhpMcp\Types\Content\TextContent;
@@ -140,12 +141,12 @@ function createCalculatorTool(): RegisteredTool
                 break;
             case 'divide':
                 if ($b == 0) {
-                    throw new InvalidArgumentException('Division by zero');
+                    throw ValidationError::invalidFieldValue('divisor', 'cannot be zero');
                 }
                 $result = $a / $b;
                 break;
             default:
-                throw new InvalidArgumentException('Unknown operation: ' . $operation);
+                throw ValidationError::invalidFieldValue('operation', 'unknown operation: ' . $operation);
         }
 
         return [

examples/stdio_sequential-thinking-test.php

@@ -7,6 +7,7 @@
 require_once __DIR__ . '/../vendor/autoload.php';
 
 use Dtyq\PhpMcp\Client\McpClient;
+use Dtyq\PhpMcp\Shared\Exceptions\SystemException;
 use Dtyq\PhpMcp\Shared\Kernel\Application;
 use Psr\Container\ContainerInterface;
 use Psr\EventDispatcher\EventDispatcherInterface;
@@ -80,7 +81,7 @@ public function dispatch(object $event): object
     public function get(string $id): object
     {
         if (! isset($this->services[$id])) {
-            throw new RuntimeException("Service {$id} not found");
+            throw new SystemException("Service {$id} not found");
         }
 
         return $this->services[$id];

src/Client/Core/AbstractSession.php

@@ -17,7 +17,6 @@
 use Dtyq\PhpMcp\Types\Core\JsonRpcResponseInterface;
 use Dtyq\PhpMcp\Types\Core\RequestInterface;
 use Exception;
-use InvalidArgumentException;
 
 /**
  * Abstract base class for MCP client session implementations.
@@ -202,7 +201,7 @@ protected function generateRequestId(): string
     protected function setDefaultTimeout(float $timeout): void
     {
         if ($timeout <= 0) {
-            throw new InvalidArgumentException('Timeout must be greater than 0');
+            throw new ProtocolError('Timeout must be greater than 0');
         }
         $this->defaultTimeout = $timeout;
     }