Update README with fluent builder and ErrorBag docs

Document new v1.2.0 features:
- McpError fluent builder with factory methods
- ErrorBag for collecting multiple errors
- JSON-RPC 2.0 error code mapping
- Integration examples

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mowens3

README.md

@@ -6,7 +6,7 @@
 [![PHP Version](https://img.shields.io/packagist/php-v/code-wheel/mcp-error-codes.svg)](https://packagist.org/packages/code-wheel/mcp-error-codes)
 [![License](https://poser.pugx.org/code-wheel/mcp-error-codes/license)](https://packagist.org/packages/code-wheel/mcp-error-codes)
 
-Standardized error codes for MCP (Model Context Protocol) servers in PHP.
+Standardized error codes and fluent error builders for MCP (Model Context Protocol) servers in PHP.
 
 **Zero dependencies** - pure PHP 8.1+.
 
@@ -16,7 +16,71 @@ Standardized error codes for MCP (Model Context Protocol) servers in PHP.
 composer require code-wheel/mcp-error-codes
 ```
 
-## Usage
+## Quick Start
+
+### Fluent Error Builder
+
+```php
+use CodeWheel\McpErrorCodes\McpError;
+
+// Simple errors with factory methods
+$error = McpError::notFound('user', 'user-123');
+$error = McpError::accessDenied('delete', 'admin permission required');
+$error = McpError::validation('email', 'Invalid format');
+$error = McpError::rateLimited('tool_calls');
+
+// Add context and suggestions
+$error = McpError::notFound('user', 'user-123')
+    ->withSuggestion('Check if user ID is correct')
+    ->withContext(['searched_in' => 'active_users']);
+
+// Convert to different formats
+$array = $error->toArray();           // ['success' => false, 'error' => '...', 'code' => '...']
+$result = $error->toToolResult();     // ToolResult with success=false
+$rpcError = $error->toJsonRpcError(); // JSON-RPC 2.0 Error object
+
+// Rate limiting with retry hint
+$error = McpError::rateLimited('api_calls')
+    ->retryAfter(60);
+```
+
+### ErrorBag for Multiple Errors
+
+```php
+use CodeWheel\McpErrorCodes\ErrorBag;
+use CodeWheel\McpErrorCodes\McpError;
+
+$errors = new ErrorBag();
+
+// Collect validation errors
+if (empty($input['email'])) {
+    $errors->addValidation('email', 'Email is required');
+}
+if (!filter_var($input['email'] ?? '', FILTER_VALIDATE_EMAIL)) {
+    $errors->addValidation('email', 'Invalid email format');
+}
+if (strlen($input['name'] ?? '') < 2) {
+    $errors->addValidation('name', 'Name must be at least 2 characters');
+}
+
+// Check and return
+if ($errors->hasErrors()) {
+    return $errors->toToolResult();
+}
+
+// Filter errors by field
+$emailErrors = $errors->forField('email');
+
+// Merge error bags
+$errors->merge($otherErrors);
+
+// Iterate over errors
+foreach ($errors as $error) {
+    echo $error->getMessage();
+}
+```
+
+### Error Code Constants
 
 ```php
 use CodeWheel\McpErrorCodes\ErrorCode;
@@ -37,12 +101,46 @@ $shouldRetry = ErrorCode::isRecoverable(ErrorCode::RATE_LIMIT_EXCEEDED); // true
 // Map to HTTP status
 $httpStatus = ErrorCode::getHttpStatus(ErrorCode::NOT_FOUND); // 404
 
-// Validate error codes
-if (ErrorCode::isValid($code)) {
-    // Known error code
-}
+// Map to JSON-RPC 2.0 error codes
+$rpcCode = ErrorCode::getJsonRpcCode(ErrorCode::VALIDATION_ERROR); // -32602
+$rpcCode = ErrorCode::getJsonRpcCode(ErrorCode::NOT_FOUND);        // -32002
+$rpcCode = ErrorCode::getJsonRpcCode(ErrorCode::INTERNAL_ERROR);   // -32603
 ```
 
+## Available Factory Methods
+
+| Method | Description | Error Code |
+|--------|-------------|------------|
+| `McpError::notFound($type, $id)` | Entity not found | NOT_FOUND |
+| `McpError::accessDenied($action, $reason)` | Permission denied | ACCESS_DENIED |
+| `McpError::validation($field, $message)` | Input validation error | VALIDATION_ERROR |
+| `McpError::rateLimited($resource)` | Rate limit exceeded | RATE_LIMIT_EXCEEDED |
+| `McpError::alreadyExists($type, $id)` | Duplicate entity | ALREADY_EXISTS |
+| `McpError::insufficientScope($required)` | Missing scope | INSUFFICIENT_SCOPE |
+| `McpError::internalError($message)` | Server error | INTERNAL_ERROR |
+| `McpError::timeout($operation)` | Operation timed out | TIMEOUT |
+| `McpError::invalidInput($field, $message)` | Invalid input | VALIDATION_ERROR |
+| `McpError::missingRequired($field)` | Required field missing | MISSING_REQUIRED |
+| `McpError::operationFailed($message)` | Operation failed | OPERATION_FAILED |
+| `McpError::serviceUnavailable($service)` | External service down | SERVICE_UNAVAILABLE |
+| `McpError::entityProtected($type, $id)` | Cannot modify protected | ENTITY_PROTECTED |
+| `McpError::entityInUse($type, $id)` | Cannot delete in-use | ENTITY_IN_USE |
+| `McpError::confirmationRequired($action)` | Needs confirmation | CONFIRMATION_REQUIRED |
+
+## JSON-RPC 2.0 Error Code Mapping
+
+MCP uses JSON-RPC 2.0. This package maps semantic error codes to standard JSON-RPC codes:
+
+| Error Code | JSON-RPC Code | Description |
+|------------|---------------|-------------|
+| VALIDATION_ERROR | -32602 | Invalid params |
+| INVALID_TOOL | -32601 | Method not found |
+| NOT_FOUND | -32002 | Resource not found |
+| ACCESS_DENIED | -32003 | Access denied |
+| RATE_LIMIT_EXCEEDED | -32004 | Rate limited |
+| INTERNAL_ERROR | -32603 | Internal error |
+| TIMEOUT | -32001 | Timeout |
+
 ## Error Categories
 
 | Category | Codes | Description |
@@ -53,56 +151,6 @@ if (ErrorCode::isValid($code)) {
 | `operation` | INTERNAL_ERROR, OPERATION_FAILED, TIMEOUT, CONFIRMATION_REQUIRED | Operation execution errors |
 | `domain` | TEMPLATE_NOT_FOUND, CRON_FAILED, MIGRATION_FAILED, etc. | Domain-specific errors |
 
-## All Error Codes
-
-### Access Control
-- `INSUFFICIENT_SCOPE` - Write operations not allowed
-- `ADMIN_REQUIRED` - Operation requires admin scope
-- `ACCESS_DENIED` - Generic access denied
-- `RATE_LIMIT_EXCEEDED` - Rate limit exceeded
-
-### Resource
-- `NOT_FOUND` - Entity/resource not found
-- `ALREADY_EXISTS` - Duplicate entity
-- `ENTITY_IN_USE` - Cannot delete/modify entity in use
-- `ENTITY_PROTECTED` - Protected entity
-
-### Validation
-- `VALIDATION_ERROR` - Input validation failed
-- `INVALID_NAME` - Invalid machine name format
-- `INVALID_FILE_TYPE` - Invalid file type
-- `PAYLOAD_TOO_LARGE` - Size limit exceeded
-- `MISSING_REQUIRED` - Required parameter missing
-
-### Operation
-- `INTERNAL_ERROR` - Internal server error
-- `OPERATION_FAILED` - Operation failed
-- `TIMEOUT` - Operation timed out
-- `CONFIRMATION_REQUIRED` - Confirmation needed
-
-### Domain-Specific
-- `TEMPLATE_NOT_FOUND` - Template not found
-- `CRON_FAILED` - Cron job failed
-- `MIGRATION_FAILED` - Migration failed
-- `RECIPE_FAILED` - Recipe application failed
-- `CONFIG_ERROR` - Configuration error
-- `MEDIA_ERROR` - Media processing failed
-- `SERVICE_UNAVAILABLE` - External service unavailable
-
-## HTTP Status Mapping
-
-| Error Code | HTTP Status |
-|------------|-------------|
-| ACCESS_DENIED, INSUFFICIENT_SCOPE, ADMIN_REQUIRED | 403 |
-| RATE_LIMIT_EXCEEDED | 429 |
-| NOT_FOUND, TEMPLATE_NOT_FOUND | 404 |
-| ALREADY_EXISTS, ENTITY_IN_USE, ENTITY_PROTECTED | 409 |
-| VALIDATION_ERROR, INVALID_NAME, INVALID_FILE_TYPE, MISSING_REQUIRED | 400 |
-| PAYLOAD_TOO_LARGE | 413 |
-| TIMEOUT | 408 |
-| SERVICE_UNAVAILABLE | 503 |
-| All others | 500 |
-
 ## Recoverable Errors
 
 These errors may resolve on retry: