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(2mo ago)1826↓68.2%1MITPHPPHP &gt;=8.1CI passing

Since Jan 9Pushed 2mo 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 today

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

43

—

FairBetter than 91% of packages

Maintenance86

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

74d 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

72644.2k1](/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.

46554.9k5](/packages/deepseek-php-deepseek-php-client)[wordpress/php-ai-client

A provider agnostic PHP AI client SDK to communicate with any generative AI models of various capabilities using a uniform API.

25427.3k8](/packages/wordpress-php-ai-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.

10713.9k1](/packages/wordpress-wp-ai-client)[claude-php/claude-php-sdk-laravel

Laravel integration for the Claude PHP SDK - Anthropic Claude API

505.5k](/packages/claude-php-claude-php-sdk-laravel)[vectorifyai/vectorify-laravel

Vectorify package for Laravel. The fastest way to ask AI about your data.

196.1k](/packages/vectorifyai-vectorify-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
