@codewheel/mcp-error-codes

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

Installation

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

Using Error Codes Directly

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

Using Fluent Error Builder

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: {...} }

Collecting Multiple Errors

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

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 |

Domain-Specific

| 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

ErrorCode

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

// Helper functions
ErrorCode.all(): Record<string, string>
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

McpError

// 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<string, unknown>): 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

ErrorBag

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

MCP Servers