MCP Error Codes

Standardized error codes and fluent error builders for MCP (Model Context Protocol) servers in PHP.

Zero dependencies - pure PHP 8.1+.

Installation

composer require code-wheel/mcp-error-codes

Quick Start

Fluent Error Builder

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

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

use CodeWheel\McpErrorCodes\ErrorCode;

// Use constants for consistent error responses
$response = [
    'success' => false,
    'code' => ErrorCode::NOT_FOUND,
    'error' => 'User not found',
];

// Check error category
$category = ErrorCode::getCategory(ErrorCode::NOT_FOUND); // 'resource'

// Check if client should retry
$shouldRetry = ErrorCode::isRecoverable(ErrorCode::RATE_LIMIT_EXCEEDED); // true

// Map to HTTP status
$httpStatus = ErrorCode::getHttpStatus(ErrorCode::NOT_FOUND); // 404

// 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 | |----------|-------|-------------| | access | INSUFFICIENT_SCOPE, ADMIN_REQUIRED, ACCESS_DENIED, RATE_LIMIT_EXCEEDED | Permission/auth errors | | resource | NOT_FOUND, ALREADY_EXISTS, ENTITY_IN_USE, ENTITY_PROTECTED | Entity/resource state errors | | validation | VALIDATION_ERROR, INVALID_NAME, INVALID_FILE_TYPE, PAYLOAD_TOO_LARGE, MISSING_REQUIRED | Input validation errors | | operation | INTERNAL_ERROR, OPERATION_FAILED, TIMEOUT, CONFIRMATION_REQUIRED | Operation execution errors | | domain | TEMPLATE_NOT_FOUND, CRON_FAILED, MIGRATION_FAILED, etc. | Domain-specific errors |

Recoverable Errors

These errors may resolve on retry:

• RATE_LIMIT_EXCEEDED - Wait and retry
• TIMEOUT - Retry with backoff
• SERVICE_UNAVAILABLE - External service may recover
• INTERNAL_ERROR - Transient server issue

License

MIT