@codewheel/mcp-error-codes

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

Installation

``bash
npm install @codewheel/mcp-error-codes
`

Features

- 20+ 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 TypeScript support with strict types
- Zero runtime dependencies
- Tree-shakeable ESM and CommonJS builds

Quick Start

$3

`typescript
import { ErrorCode, NOT_FOUND, getHttpStatus } from '@codewheel/mcp-error-codes';

// Use constants
if (!user) {
return {
success: false,
code: NOT_FOUND,
message: 'User not found',
};
}

// Use helper functions
ErrorCode.isValid('NOT_FOUND'); // true
ErrorCode.getCategory(NOT_FOUND); // 'resource'
ErrorCode.getHttpStatus(NOT_FOUND); // 404
ErrorCode.getJsonRpcCode(NOT_FOUND); // -32002
ErrorCode.isRecoverable(NOT_FOUND); // false
`

$3

`typescript
import { McpError } from '@codewheel/mcp-error-codes';

// Simple errors
const error = McpError.notFound('User', 123);
console.log(error.getMessage()); // "User '123' not found."
console.log(error.getHttpStatus()); // 404

// With suggestions and context
const detailed = McpError.validation('email', 'Invalid format')
.withSuggestion('Use a valid email like user@example.com')
.withContext({ provided: 'not-an-email' });

// Convert to different formats
detailed.toArray(); // { success: false, error: '...', code: '...', ... }
detailed.toJsonRpcError(); // { code: -32602, message: '...', data: {...} }
`

$3

`typescript
import { ErrorBag, McpError } from '@codewheel/mcp-error-codes';

const errors = new ErrorBag();

if (!input.email) {
errors.addValidation('email', 'Required');
}
if (!input.name) {
errors.addValidation('name', 'Required');
}
if (input.age < 0) {
errors.add(McpError.validation('age', 'Must be positive'));
}

if (errors.hasErrors()) {
return errors.toArray();
// {
// success: false,
// error: '3 validation errors occurred.',
// code: 'VALIDATION_ERROR',
// error_count: 3,
// errors: [...]
// }
}
`

Error Codes

$3

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

$3

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

$3

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

$3

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

$3

| Code | Description | HTTP | JSON-RPC |
|------|-------------|------|----------|
| TEMPLATE_NOT_FOUND | Template not found | 404 | -32002 |
| CRON_FAILED | Cron job failed | 500 | -32011 |
| MIGRATION_FAILED | Migration failed | 500 | -32011 |
| SERVICE_UNAVAILABLE | External service down | 503 | -32008 |

API Reference

$3

`typescript
// All error code constants
ErrorCode.NOT_FOUND
ErrorCode.VALIDATION_ERROR
// ... etc

// Helper functions
ErrorCode.all(): Record
ErrorCode.isValid(code: string): boolean
ErrorCode.getCategory(code: string): 'access' | 'resource' | 'validation' | 'operation' | 'domain'
ErrorCode.isRecoverable(code: string): boolean
ErrorCode.getHttpStatus(code: string): number
ErrorCode.getJsonRpcCode(code: string): number
`

$3

`typescript
// Factory methods
McpError.notFound(entityType: string, identifier?: string | number): McpError
McpError.accessDenied(resource?: string): McpError
McpError.validation(field: string, reason: string): McpError
McpError.rateLimited(retryAfter?: number): McpError
McpError.internal(message: string): McpError
// ... and more

// Builder methods
error.withSuggestion(suggestion: string): McpError
error.withContext(context: Record): McpError
error.withDetail(key: string, value: unknown): McpError
error.retryAfter(seconds: number): McpError

// Getters
error.getCode(): string
error.getMessage(): string
error.getCategory(): string
error.getHttpStatus(): number
error.getJsonRpcCode(): number

// Conversion
error.toArray(): ErrorArray
error.toJsonRpcError(): JsonRpcError
error.toCallToolResult(): CallToolResult // requires @modelcontextprotocol/sdk
`

$3

`typescript
// Construction
new ErrorBag()
ErrorBag.fromArray(errors: McpError[]): ErrorBag

// Adding errors
bag.add(error: McpError): ErrorBag
bag.addValidation(field: string, reason: string): ErrorBag
bag.merge(other: ErrorBag): ErrorBag

// Querying
bag.hasErrors(): boolean
bag.isEmpty(): boolean
bag.count(): number
bag.all(): McpError[]
bag.first(): McpError | undefined
bag.forField(field: string): McpError[]
bag.byCategory(category: string): McpError[]

// Conversion
bag.toArray(): ErrorBagArray
bag.toJsonRpcError(): JsonRpcError
bag.toCallToolResult(): CallToolResult // requires @modelcontextprotocol/sdk
`

Cross-Language Support

This package is part of the MCP error codes ecosystem:

| Language | Package |
|----------|---------|
| TypeScript | @codewheel/mcp-error-codes |
| PHP | code-wheel/mcp-error-codes |
| Python | mcp-error-codes` (coming soon) |

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

License

MIT