PHPackages code-wheel/mcp-error-codes - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. code-wheel/mcp-error-codes ActiveLibrary[API Development](/categories/api) code-wheel/mcp-error-codes ========================== Standardized error codes and fluent error builders for MCP (Model Context Protocol) servers in PHP v1.2.3(3mo ago)1826↓68.2%1MITPHPPHP >=8.1CI passing Since Jan 9Pushed 3mo agoCompare [ Source](https://github.com/code-wheel/mcp-error-codes-php)[ Packagist](https://packagist.org/packages/code-wheel/mcp-error-codes)[ RSS](/packages/code-wheel-mcp-error-codes/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (2)Dependencies (3)Versions (7)Used By (1) MCP Error Codes =============== [](#mcp-error-codes) [![CI](https://github.com/code-wheel/mcp-error-codes/actions/workflows/ci.yml/badge.svg)](https://github.com/code-wheel/mcp-error-codes/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/3cf150a3e142e7dcb78019a5e988c95084b634318fa981ec677558d26b4bf273/68747470733a2f2f636f6465636f762e696f2f67682f636f64652d776865656c2f6d63702d6572726f722d636f6465732f67726170682f62616467652e737667)](https://codecov.io/gh/code-wheel/mcp-error-codes)[![Latest Stable Version](https://camo.githubusercontent.com/d870d608d58906b6bddae1ee4e6ff52c8319683ecfad56134cebbb8e18b73ecc/68747470733a2f2f706f7365722e707567782e6f72672f636f64652d776865656c2f6d63702d6572726f722d636f6465732f76)](https://packagist.org/packages/code-wheel/mcp-error-codes)[![PHP Version](https://camo.githubusercontent.com/d17403b12459232bff09c0dd0eb40731310d6fe6e6a0e487d0e6821c26b8cd60/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f636f64652d776865656c2f6d63702d6572726f722d636f6465732e737667)](https://packagist.org/packages/code-wheel/mcp-error-codes)[![License](https://camo.githubusercontent.com/7f32db704066e5b968ac1eaedead00413bf8c2fdd53f3cc840cf6fe27c45d69f/68747470733a2f2f706f7365722e707567782e6f72672f636f64652d776865656c2f6d63702d6572726f722d636f6465732f6c6963656e7365)](https://packagist.org/packages/code-wheel/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 ------------ [](#installation) ``` composer require code-wheel/mcp-error-codes ``` Quick Start ----------- [](#quick-start) ### Fluent Error Builder [](#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 [](#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 [](#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 ------------------------- [](#available-factory-methods) MethodDescriptionError Code`McpError::notFound($type, $id)`Entity not foundNOT\_FOUND`McpError::accessDenied($action, $reason)`Permission deniedACCESS\_DENIED`McpError::validation($field, $message)`Input validation errorVALIDATION\_ERROR`McpError::rateLimited($resource)`Rate limit exceededRATE\_LIMIT\_EXCEEDED`McpError::alreadyExists($type, $id)`Duplicate entityALREADY\_EXISTS`McpError::insufficientScope($required)`Missing scopeINSUFFICIENT\_SCOPE`McpError::internalError($message)`Server errorINTERNAL\_ERROR`McpError::timeout($operation)`Operation timed outTIMEOUT`McpError::invalidInput($field, $message)`Invalid inputVALIDATION\_ERROR`McpError::missingRequired($field)`Required field missingMISSING\_REQUIRED`McpError::operationFailed($message)`Operation failedOPERATION\_FAILED`McpError::serviceUnavailable($service)`External service downSERVICE\_UNAVAILABLE`McpError::entityProtected($type, $id)`Cannot modify protectedENTITY\_PROTECTED`McpError::entityInUse($type, $id)`Cannot delete in-useENTITY\_IN\_USE`McpError::confirmationRequired($action)`Needs confirmationCONFIRMATION\_REQUIREDJSON-RPC 2.0 Error Code Mapping ------------------------------- [](#json-rpc-20-error-code-mapping) MCP uses JSON-RPC 2.0. This package maps semantic error codes to standard JSON-RPC codes: Error CodeJSON-RPC CodeDescriptionVALIDATION\_ERROR-32602Invalid paramsINVALID\_TOOL-32601Method not foundNOT\_FOUND-32002Resource not foundACCESS\_DENIED-32003Access deniedRATE\_LIMIT\_EXCEEDED-32004Rate limitedINTERNAL\_ERROR-32603Internal errorTIMEOUT-32001TimeoutError Categories ---------------- [](#error-categories) CategoryCodesDescription`access`INSUFFICIENT\_SCOPE, ADMIN\_REQUIRED, ACCESS\_DENIED, RATE\_LIMIT\_EXCEEDEDPermission/auth errors`resource`NOT\_FOUND, ALREADY\_EXISTS, ENTITY\_IN\_USE, ENTITY\_PROTECTEDEntity/resource state errors`validation`VALIDATION\_ERROR, INVALID\_NAME, INVALID\_FILE\_TYPE, PAYLOAD\_TOO\_LARGE, MISSING\_REQUIREDInput validation errors`operation`INTERNAL\_ERROR, OPERATION\_FAILED, TIMEOUT, CONFIRMATION\_REQUIREDOperation execution errors`domain`TEMPLATE\_NOT\_FOUND, CRON\_FAILED, MIGRATION\_FAILED, etc.Domain-specific errorsRecoverable 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 ------- [](#license) MIT ### Health Score 42 — FairBetter than 89% of packages Maintenance83 Actively maintained with recent releases Popularity21 Limited adoption so far Community8 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 6 Last Release 119d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/4cb6eebdce9234e8ad086e2786111257d1f959a3f7323c9fdae46c600082f646?d=identicon)[mowens3](/maintainers/mowens3) --- Top Contributors [![mowens3](https://avatars.githubusercontent.com/u/1635473?v=4)](https://github.com/mowens3 "mowens3 (23 commits)") --- Tags apimcpaierror handlingerror codesllmModel Context Protocol ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/code-wheel-mcp-error-codes/health.svg) ``` [![Health](https://phpackages.com/badges/code-wheel-mcp-error-codes/health.svg)](https://phpackages.com/packages/code-wheel-mcp-error-codes) ``` ### Alternatives [wordpress/mcp-adapter Adapter for Abilities API, letting WordPress abilities to be used as MCP tools, resources or prompts 74855.8k1](/packages/wordpress-mcp-adapter)[deepseek-php/deepseek-php-client deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities. 47073.9k5](/packages/deepseek-php-deepseek-php-client)[wordpress/wp-ai-client An AI client and API for WordPress to communicate with any generative AI models of various capabilities using a uniform API. 11117.5k1](/packages/wordpress-wp-ai-client)[claude-php/claude-php-sdk-laravel Laravel integration for the Claude PHP SDK - Anthropic Claude API 5010.8k](/packages/claude-php-claude-php-sdk-laravel)[vectorifyai/vectorify-laravel Vectorify package for Laravel. The fastest way to ask AI about your data. 206.1k](/packages/vectorifyai-vectorify-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)