mcp-error-codes

Standardized MCP error codes with semantic categories, HTTP/JSON-RPC mapping, and fluent builders for Python.

Installation

pip install mcp-error-codes

Features

28 predefined error codes covering access, resource, validation, operation, and domain errors
Semantic categories for error classification
HTTP status code mapping for REST APIs
JSON-RPC 2.0 code mapping for MCP protocol compliance
Fluent error builder (McpError) for creating rich error responses
Error collection (ErrorBag) for aggregating multiple validation errors
Full type hints with strict mypy compliance
Zero runtime dependencies

Quick Start

Using Error Codes Directly

from mcp_error_codes import ErrorCode, NOT_FOUND

# Use constants
if user is None:
    return {"success": False, "code": NOT_FOUND}

# Use helper methods
ErrorCode.is_valid("NOT_FOUND")           # True
ErrorCode.get_category(NOT_FOUND)         # "resource"
ErrorCode.get_http_status(NOT_FOUND)      # 404
ErrorCode.get_json_rpc_code(NOT_FOUND)    # -32002
ErrorCode.is_recoverable(NOT_FOUND)       # False

Using Fluent Error Builder

from mcp_error_codes import McpError

# Simple errors
error = McpError.not_found("User", 123)
print(error.get_message())  # "User '123' not found."
print(error.get_http_status())  # 404

# With suggestions and context
detailed = (
    McpError.validation("email", "Invalid format")
    .with_suggestion("Use a valid email like user@example.com")
    .with_context({"provided": "not-an-email"})
)

# Convert to different formats
detailed.to_dict()          # {"success": False, "error": "...", ...}
detailed.to_json_rpc_error()  # {"code": -32602, "message": "...", ...}

Collecting Multiple Errors

from mcp_error_codes import ErrorBag, McpError

errors = ErrorBag()

if not data.get("email"):
    errors.add_validation("email", "Required")
if not data.get("name"):
    errors.add_validation("name", "Required")
if data.get("age", 0) < 0:
    errors.add(McpError.validation("age", "Must be positive"))

if errors.has_errors():
    return errors.to_dict()
    # {
    #   "success": False,
    #   "error": "3 validation errors occurred.",
    #   "code": "VALIDATION_ERROR",
    #   "error_count": 3,
    #   "errors": [...]
    # }

Error Codes

Access Control

| Code | Description | HTTP | JSON-RPC | |------|-------------|------|----------| | INSUFFICIENT_SCOPE | Write operations not allowed | 403 | -32001 | | ADMIN_REQUIRED | Admin privileges required | 403 | -32001 | | ACCESS_DENIED | Generic access denied | 403 | -32001 | | RATE_LIMIT_EXCEEDED | Rate limit exceeded | 429 | -32003 | | READ_ONLY_MODE | System in read-only mode | 403 | -32004 |

Resource

| Code | Description | HTTP | JSON-RPC | |------|-------------|------|----------| | NOT_FOUND | Resource not found | 404 | -32002 | | ALREADY_EXISTS | Resource already exists | 409 | -32005 | | ENTITY_IN_USE | Cannot delete, entity in use | 409 | -32005 | | ENTITY_PROTECTED | Entity is protected | 409 | -32005 | | MISSING_DEPENDENCY | Required dependency missing | 500 | -32006 |

Validation

| Code | Description | HTTP | JSON-RPC | |------|-------------|------|----------| | VALIDATION_ERROR | Input validation failed | 400 | -32602 | | INVALID_NAME | Invalid machine name | 400 | -32602 | | INVALID_FILE_TYPE | Invalid file type | 400 | -32602 | | PAYLOAD_TOO_LARGE | Payload exceeds limit | 413 | -32009 | | MISSING_REQUIRED | Required parameter missing | 400 | -32602 |

Operation

| Code | Description | HTTP | JSON-RPC | |------|-------------|------|----------| | INTERNAL_ERROR | Internal server error | 500 | -32603 | | OPERATION_FAILED | Operation failed | 500 | -32011 | | TIMEOUT | Operation timed out | 408 | -32007 | | CONFIRMATION_REQUIRED | Needs user confirmation | 500 | -32010 | | INVALID_TOOL | Tool not found/invalid | 400 | -32601 | | EXECUTION_FAILED | Tool execution failed | 500 | -32603 | | INSTANTIATION_FAILED | Tool instantiation failed | 500 | -32603 |

API Reference

ErrorCode

# All error code constants
ErrorCode.NOT_FOUND
ErrorCode.VALIDATION_ERROR
# ... etc

# Helper methods
ErrorCode.all() -> dict[str, str]
ErrorCode.is_valid(code: str) -> bool
ErrorCode.get_category(code: str) -> Literal["access", "resource", "validation", "operation", "domain"]
ErrorCode.is_recoverable(code: str) -> bool
ErrorCode.get_http_status(code: str) -> int
ErrorCode.get_json_rpc_code(code: str) -> int

McpError

# Factory methods
McpError.not_found(entity_type: str, identifier: str | int | None = None) -> McpError
McpError.access_denied(resource: str | None = None) -> McpError
McpError.validation(field: str, reason: str) -> McpError
McpError.rate_limited(retry_after: int | None = None) -> McpError
McpError.internal(message: str) -> McpError
# ... and more

# Builder methods
error.with_suggestion(suggestion: str) -> McpError
error.with_context(context: dict[str, Any]) -> McpError
error.with_detail(key: str, value: Any) -> McpError
error.retry_after(seconds: int) -> McpError

# Getters
error.get_code() -> str
error.get_message() -> str
error.get_category() -> str
error.get_http_status() -> int
error.get_json_rpc_code() -> int

# Conversion
error.to_dict() -> ErrorDict
error.to_json_rpc_error() -> JsonRpcError
error.to_call_tool_result() -> CallToolResult  # requires mcp package

ErrorBag

# Construction
ErrorBag()
ErrorBag.from_list(errors: list[McpError]) -> ErrorBag

# Adding errors
bag.add(error: McpError) -> ErrorBag
bag.add_validation(field: str, reason: str) -> ErrorBag
bag.merge(other: ErrorBag) -> ErrorBag

# Querying
bag.has_errors() -> bool
bag.is_empty() -> bool
bag.count() -> int
bag.all() -> list[McpError]
bag.first() -> McpError | None
bag.for_field(field: str) -> list[McpError]
bag.by_category(category: str) -> list[McpError]

# Conversion
bag.to_dict() -> ErrorBagDict
bag.to_json_rpc_error() -> dict
bag.to_call_tool_result() -> CallToolResult  # requires mcp package

Cross-Language Support

This package is part of the MCP error codes ecosystem:

| Language | Package | |----------|---------| | Python | mcp-error-codes | | TypeScript | @codewheel/mcp-error-codes | | PHP | code-wheel/mcp-error-codes |

All packages maintain API parity for consistent error handling across your stack.

License

MIT

MCP Servers