mcp-error-code-mapper

name	mcp-error-code-mapper
description	Map application errors to MCP error codes with proper messages, error types, and recovery suggestions.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
graph	{"domains":["domain:software-engineering"],"specializations":["specialization:cli-mcp-development"],"skillAreas":["skill-area:mcp-server-implementation","skill-area:error-handling-exception-management"],"roles":["role:backend-engineer","role:platform-engineer"],"workflows":["workflow:feature-development"],"topics":["topic:developer-experience"]}

MCP Error Code Mapper

Map application errors to MCP error codes with proper handling.

Capabilities

• Map errors to MCP error codes
• Create structured error responses
• Generate error documentation
• Implement error recovery hints
• Configure error serialization
• Create error handler utilities

Usage

Invoke this skill when you need to:

• Map application errors to MCP errors
• Create structured error responses
• Implement error handling for tools
• Generate error documentation

Inputs

Parameter	Type	Required	Description
language	string	Yes	Target language
errors	array	Yes	Error definitions
includeRecovery	boolean	No	Include recovery hints

Error Structure

{
  "errors": [
    {
      "name": "FileNotFound",
      "mcpCode": -32002,
      "message": "File not found: {path}",
      "recovery": "Check if the file exists and the path is correct"
    },
    {
      "name": "InvalidInput",
      "mcpCode": -32602,
      "message": "Invalid input: {reason}",
      "recovery": "Review the input parameters and try again"
    }
  ]
}

Generated Patterns

TypeScript Error Mapper

import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

// Standard MCP Error Codes
export const MCP_ERROR_CODES = {
  PARSE_ERROR: -32700,
  INVALID_REQUEST: -32600,
  METHOD_NOT_FOUND: -32601,
  INVALID_PARAMS: -32602,
  INTERNAL_ERROR: -32603,
  // Custom codes (-32000 to -32099)
  FILE_NOT_FOUND: -32001,
  PERMISSION_DENIED: -32002,
  RESOURCE_NOT_FOUND: -32003,
  VALIDATION_ERROR: -32004,
} as const;

// Error with recovery hint
interface McpErrorWithRecovery extends McpError {
  data?: {
    recovery?: string;
    details?: unknown;
  };
}

// Error factory functions
export function fileNotFoundError(path: string): McpErrorWithRecovery {
  return {
    code: MCP_ERROR_CODES.,
    : ,
    : {
      : ,
      : { path },
    },
  };
}

  ():  {
   {
    : .,
    : ,
    : {
      : ,
    },
  };
}


  ():  {
   (error  ) {
    
     (error..()) {
       (error.);
    }
     (error..()) {
       {
        : .,
        : ,
        : { :  },
      };
    }
    
     {
      : .,
      : error.,
    };
  }
   {
    : .,
    : ,
  };
}

Python Error Mapper

from enum import IntEnum
from typing import Any, Optional
from dataclasses import dataclass

class McpErrorCode(IntEnum):
    PARSE_ERROR = -32700
    INVALID_REQUEST = -32600
    METHOD_NOT_FOUND = -32601
    INVALID_PARAMS = -32602
    INTERNAL_ERROR = -32603
    # Custom codes
    FILE_NOT_FOUND = -32001
    PERMISSION_DENIED = -32002
    RESOURCE_NOT_FOUND = -32003

@dataclass
class McpError(Exception):
    code: int
    message: str
    recovery: Optional[str] = None
    details: Optional[Any] = None

    def to_dict(self) -> dict:
        result = {'code': self.code, 'message': self.message}
        if self.recovery or self.details:
            result['data'] = {}
            if self.recovery:
                result['data']['recovery'] = .recovery
             .details:
                result[][] = .details
         result

 () -> McpError:
     McpError(
        code=McpErrorCode.FILE_NOT_FOUND,
        message=,
        recovery=,
        details={: path}
    )

 () -> McpError:
    error_msg = (error)
       (error).__name__:
         file_not_found_error(error_msg)
       (error).__name__:
         McpError(
            code=McpErrorCode.PERMISSION_DENIED,
            message=,
            recovery=
        )
     McpError(
        code=McpErrorCode.INTERNAL_ERROR,
        message=error_msg
    )

Workflow

1. Define errors - List application errors
2. Map codes - Assign MCP error codes
3. Create messages - User-friendly messages
4. Add recovery - Recovery suggestions
5. Generate handlers - Error handling code
6. Document errors - Error documentation

Target Processes

• mcp-tool-implementation
• mcp-server-security-hardening
• error-handling-user-feedback