@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

Resource

Validation

Operation

Domain-Specific

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:

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

License

MIT