@aashari/boilerplate-mcp-server 1.5.9 → 1.6.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.6.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.5.10...v1.6.0) (2025-05-15)
+
+
+### Features
+
+* enhanced error handling across the application ([75aa905](https://github.com/aashari/boilerplate-mcp-server/commit/75aa90528e615d1c1a9a411ddd1bf1931edfde61))
+
+## [1.5.10](https://github.com/aashari/boilerplate-mcp-server/compare/v1.5.9...v1.5.10) (2025-05-14)
+
+
+### Bug Fixes
+
+* remove Dockerfile and smithery.yaml ([582e9f9](https://github.com/aashari/boilerplate-mcp-server/commit/582e9f9e66087fd2211d6fcf1aaa79c9ee54a123))
+
 ## [1.5.9](https://github.com/aashari/boilerplate-mcp-server/compare/v1.5.8...v1.5.9) (2025-05-13)
 
 

package/dist/controllers/ipaddress.controller.js

@@ -9,6 +9,7 @@ const ipaddress_formatter_js_1 = require("./ipaddress.formatter.js");
 const error_handler_util_js_1 = require("../utils/error-handler.util.js");
 const config_util_js_1 = require("../utils/config.util.js");
 const error_util_js_1 = require("../utils/error.util.js");
+const error_handler_util_js_2 = require("../utils/error-handler.util.js");
 /**
  * @namespace IpAddressController
  * @description Controller responsible for handling IP address lookup logic.
@@ -97,12 +98,7 @@ async function get(ipAddress, options = {
         }
     }
     catch (error) {
-        throw (0, error_handler_util_js_1.handleControllerError)(error, {
-            entityType: 'IP Address',
-            operation: 'get',
-            source: 'controllers/ipaddress.controller.ts@get',
-            additionalInfo: { ipAddress, options },
-        });
+        throw (0, error_handler_util_js_1.handleControllerError)(error, (0, error_handler_util_js_2.buildErrorContext)('IP Address', 'get', 'controllers/ipaddress.controller.ts@get', ipAddress || 'current device', { options }));
     }
 }
 /** Helper to define all fields for extended data */

package/dist/services/vendor.ip-api.com.service.js

@@ -47,26 +47,23 @@ async function get(ipAddress, options = {}) {
         // First check API-level success/failure before Zod validation
         // This avoids unnecessary validation errors for known API errors
         if (rawData.status !== 'success') {
-            throw (0, error_util_js_1.createApiError)(`IP API error: ${rawData.message || 'Unknown error'}`);
-        }
-        // Now parse with Zod for successful responses
-        try {
-            const validatedData = vendor_ip_api_com_types_js_1.IPDetailSchema.parse(rawData);
-            methodLogger.debug(`Received and validated successful data from IP API`);
-            return validatedData;
-        }
-        catch (zodError) {
-            // Throw error on validation failure
-            methodLogger.error('Zod validation failed', zodError);
-            if (zodError instanceof zod_1.z.ZodError) {
-                throw (0, error_util_js_1.createApiError)(`API response validation failed: ${zodError.errors
-                    .map((e) => `${e.path.join('.')}: ${e.message}`)
-                    .join(', ')}`, undefined, // No specific HTTP status for validation errors
-                zodError);
+            // Handle specific ip-api.com error responses
+            if (rawData.message) {
+                if (rawData.message.includes('private range')) {
+                    throw (0, error_util_js_1.createApiError)(`Private IP addresses are not supported: ${rawData.message}`, 400, rawData);
+                }
+                else if (rawData.message.includes('reserved range')) {
+                    throw (0, error_util_js_1.createApiError)(`Reserved IP addresses are not supported: ${rawData.message}`, 400, rawData);
+                }
             }
-            // Rethrow if it's not a ZodError (shouldn't happen here)
-            throw zodError;
+            throw (0, error_util_js_1.createApiError)(`IP API error: ${rawData.message || 'Unknown error'}`, 400, // Use 400 for client errors from ip-api.com
+            rawData);
         }
+        // Now parse with Zod for successful responses
+        // Validate with Zod schema and return
+        const validatedData = vendor_ip_api_com_types_js_1.IPDetailSchema.parse(rawData);
+        methodLogger.debug(`Received and validated successful data from IP API`);
+        return validatedData;
     }
     catch (error) {
         methodLogger.error(`Service error fetching IP data`, error);
@@ -74,7 +71,7 @@ async function get(ipAddress, options = {}) {
         if (error instanceof zod_1.z.ZodError) {
             throw (0, error_util_js_1.createApiError)(`API response validation failed: ${error.errors
                 .map((e) => `${e.path.join('.')}: ${e.message}`)
-                .join(', ')}`, undefined, // No specific HTTP status for validation errors
+                .join(', ')}`, 500, // Use 500 for validation errors as it's a server-side issue
             error);
         }
         // Rethrow other McpErrors

package/dist/utils/constants.util.d.ts

@@ -8,7 +8,7 @@
  * Current application version
  * This should match the version in package.json
  */
-export declare const VERSION = "1.5.9";
+export declare const VERSION = "1.6.0";
 /**
  * Package name with scope
  * Used for initialization and identification

package/dist/utils/constants.util.js

@@ -11,7 +11,7 @@ exports.CLI_NAME = exports.PACKAGE_NAME = exports.VERSION = void 0;
  * Current application version
  * This should match the version in package.json
  */
-exports.VERSION = '1.5.9';
+exports.VERSION = '1.6.0';
 /**
  * Package name with scope
  * Used for initialization and identification

package/dist/utils/error-handler.util.d.ts

@@ -6,7 +6,11 @@ export declare enum ErrorCode {
     INVALID_CURSOR = "INVALID_CURSOR",
     ACCESS_DENIED = "ACCESS_DENIED",
     VALIDATION_ERROR = "VALIDATION_ERROR",
-    UNEXPECTED_ERROR = "UNEXPECTED_ERROR"
+    UNEXPECTED_ERROR = "UNEXPECTED_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR",
+    PRIVATE_IP_ERROR = "PRIVATE_IP_ERROR",
+    RESERVED_RANGE_ERROR = "RESERVED_RANGE_ERROR"
 }
 /**
  * Context information for error handling
@@ -33,6 +37,16 @@ export interface ErrorContext {
      */
     additionalInfo?: Record<string, unknown>;
 }
+/**
+ * Helper function to create a consistent error context object
+ * @param entityType Type of entity being processed
+ * @param operation Operation being performed
+ * @param source Source of the error (typically file path and function)
+ * @param entityId Optional identifier of the entity
+ * @param additionalInfo Optional additional information for debugging
+ * @returns A formatted ErrorContext object
+ */
+export declare function buildErrorContext(entityType: string, operation: string, source: string, entityId?: string | Record<string, string>, additionalInfo?: Record<string, unknown>): ErrorContext;
 /**
  * Detect specific error types from raw errors
  * @param error The error to analyze

package/dist/utils/error-handler.util.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorCode = void 0;
+exports.buildErrorContext = buildErrorContext;
 exports.detectErrorType = detectErrorType;
 exports.createUserFriendlyErrorMessage = createUserFriendlyErrorMessage;
 exports.handleControllerError = handleControllerError;
@@ -16,7 +17,29 @@ var ErrorCode;
     ErrorCode["ACCESS_DENIED"] = "ACCESS_DENIED";
     ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
     ErrorCode["UNEXPECTED_ERROR"] = "UNEXPECTED_ERROR";
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCode["RATE_LIMIT_ERROR"] = "RATE_LIMIT_ERROR";
+    ErrorCode["PRIVATE_IP_ERROR"] = "PRIVATE_IP_ERROR";
+    ErrorCode["RESERVED_RANGE_ERROR"] = "RESERVED_RANGE_ERROR";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+/**
+ * Helper function to create a consistent error context object
+ * @param entityType Type of entity being processed
+ * @param operation Operation being performed
+ * @param source Source of the error (typically file path and function)
+ * @param entityId Optional identifier of the entity
+ * @param additionalInfo Optional additional information for debugging
+ * @returns A formatted ErrorContext object
+ */
+function buildErrorContext(entityType, operation, source, entityId, additionalInfo) {
+    return {
+        entityType,
+        operation,
+        source,
+        ...(entityId && { entityId }),
+        ...(additionalInfo && { additionalInfo }),
+    };
+}
 /**
  * Detect specific error types from raw errors
  * @param error The error to analyze
@@ -30,6 +53,51 @@ function detectErrorType(error, context = {}) {
     const statusCode = error instanceof Error && 'statusCode' in error
         ? error.statusCode
         : undefined;
+    // Network error detection
+    if (errorMessage.includes('network error') ||
+        errorMessage.includes('fetch failed') ||
+        errorMessage.includes('ECONNREFUSED') ||
+        errorMessage.includes('ENOTFOUND') ||
+        errorMessage.includes('Failed to fetch') ||
+        errorMessage.includes('Network request failed')) {
+        return { code: ErrorCode.NETWORK_ERROR, statusCode: 500 };
+    }
+    // Rate limiting detection
+    if (errorMessage.includes('rate limit') ||
+        errorMessage.includes('too many requests') ||
+        statusCode === 429) {
+        return { code: ErrorCode.RATE_LIMIT_ERROR, statusCode: 429 };
+    }
+    // ip-api.com specific error detection
+    if (errorMessage.includes('private range') ||
+        errorMessage.includes('private IP')) {
+        return { code: ErrorCode.PRIVATE_IP_ERROR, statusCode: 400 };
+    }
+    if (errorMessage.includes('reserved range')) {
+        return { code: ErrorCode.RESERVED_RANGE_ERROR, statusCode: 400 };
+    }
+    // Check for ip-api.com status="fail" in originalError
+    if (error instanceof Error &&
+        'originalError' in error &&
+        error.originalError &&
+        typeof error.originalError === 'object') {
+        const originalError = error.originalError;
+        if (originalError.status === 'fail') {
+            const apiMessage = originalError.message
+                ? String(originalError.message)
+                : '';
+            if (apiMessage.includes('private')) {
+                return { code: ErrorCode.PRIVATE_IP_ERROR, statusCode: 400 };
+            }
+            if (apiMessage.includes('reserved')) {
+                return {
+                    code: ErrorCode.RESERVED_RANGE_ERROR,
+                    statusCode: 400,
+                };
+            }
+            return { code: ErrorCode.VALIDATION_ERROR, statusCode: 400 };
+        }
+    }
     // Not Found detection
     if (errorMessage.includes('not found') ||
         errorMessage.includes('does not exist') ||
@@ -110,6 +178,18 @@ function createUserFriendlyErrorMessage(code, context = {}, originalMessage) {
                 originalMessage ||
                     `Invalid data provided for ${operation || 'operation'} ${entity.toLowerCase()}.`;
             break;
+        case ErrorCode.NETWORK_ERROR:
+            message = `Network error while ${operation || 'connecting to'} the service. Please check your internet connection and try again.`;
+            break;
+        case ErrorCode.RATE_LIMIT_ERROR:
+            message = `Rate limit exceeded. Please wait a moment and try again, or reduce the frequency of requests.`;
+            break;
+        case ErrorCode.PRIVATE_IP_ERROR:
+            message = `Private IP addresses are not supported. Please provide a public IP address.`;
+            break;
+        case ErrorCode.RESERVED_RANGE_ERROR:
+            message = `Reserved range IP addresses are not supported. Please provide a public IP address.`;
+            break;
         default:
             message = `An unexpected error occurred while ${operation || 'processing'} ${entity.toLowerCase()}.`;
     }

package/dist/utils/error-handler.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/error.util.d.ts

@@ -36,6 +36,12 @@ export declare function createUnexpectedError(message?: string, originalError?:
  * Ensure an error is an McpError
  */
 export declare function ensureMcpError(error: unknown): McpError;
+/**
+ * Get the deepest original error from an error chain
+ * @param error The error to extract the original cause from
+ * @returns The deepest original error or the error itself
+ */
+export declare function getDeepOriginalError(error: unknown): unknown;
 /**
  * Format error for MCP tool response
  */
@@ -44,6 +50,11 @@ export declare function formatErrorForMcpTool(error: unknown): {
         type: 'text';
         text: string;
     }>;
+    metadata?: {
+        errorType: ErrorType;
+        statusCode?: number;
+        errorDetails?: unknown;
+    };
 };
 /**
  * Format error for MCP resource response
@@ -57,6 +68,6 @@ export declare function formatErrorForMcpResource(error: unknown, uri: string):
     }>;
 };
 /**
- * Handle error in CLI context
+ * Handle error in CLI context with improved user feedback
  */
 export declare function handleCliError(error: unknown): never;

package/dist/utils/error.util.js

@@ -6,6 +6,7 @@ exports.createAuthInvalidError = createAuthInvalidError;
 exports.createApiError = createApiError;
 exports.createUnexpectedError = createUnexpectedError;
 exports.ensureMcpError = ensureMcpError;
+exports.getDeepOriginalError = getDeepOriginalError;
 exports.formatErrorForMcpTool = formatErrorForMcpTool;
 exports.formatErrorForMcpResource = formatErrorForMcpResource;
 exports.handleCliError = handleCliError;
@@ -69,6 +70,27 @@ function ensureMcpError(error) {
     }
     return createUnexpectedError(String(error));
 }
+/**
+ * Get the deepest original error from an error chain
+ * @param error The error to extract the original cause from
+ * @returns The deepest original error or the error itself
+ */
+function getDeepOriginalError(error) {
+    if (!error) {
+        return error;
+    }
+    let current = error;
+    let depth = 0;
+    const maxDepth = 10; // Prevent infinite recursion
+    while (depth < maxDepth &&
+        current instanceof Error &&
+        'originalError' in current &&
+        current.originalError) {
+        current = current.originalError;
+        depth++;
+    }
+    return current;
+}
 /**
  * Format error for MCP tool response
  */
@@ -76,6 +98,12 @@ function formatErrorForMcpTool(error) {
     const methodLogger = logger_util_js_1.Logger.forContext('utils/error.util.ts', 'formatErrorForMcpTool');
     const mcpError = ensureMcpError(error);
     methodLogger.error(`${mcpError.type} error`, mcpError);
+    // Get the deep original error for additional context
+    const originalError = getDeepOriginalError(mcpError.originalError);
+    // Safely extract details from the original error
+    const errorDetails = originalError instanceof Error
+        ? { message: originalError.message }
+        : originalError;
     return {
         content: [
             {
@@ -83,6 +111,11 @@ function formatErrorForMcpTool(error) {
                 text: `Error: ${mcpError.message}`,
             },
         ],
+        metadata: {
+            errorType: mcpError.type,
+            statusCode: mcpError.statusCode,
+            errorDetails,
+        },
     };
 }
 /**
@@ -104,12 +137,38 @@ function formatErrorForMcpResource(error, uri) {
     };
 }
 /**
- * Handle error in CLI context
+ * Handle error in CLI context with improved user feedback
  */
 function handleCliError(error) {
     const methodLogger = logger_util_js_1.Logger.forContext('utils/error.util.ts', 'handleCliError');
     const mcpError = ensureMcpError(error);
     methodLogger.error(`${mcpError.type} error`, mcpError);
+    // Get the deep original error for more context
+    const originalError = getDeepOriginalError(mcpError.originalError);
+    // Print the error message
     console.error(`Error: ${mcpError.message}`);
+    // Provide helpful context based on error type
+    if (mcpError.type === ErrorType.AUTH_MISSING) {
+        console.error('\nTip: Make sure to set up your API token in the configuration file or environment variables.');
+    }
+    else if (mcpError.type === ErrorType.AUTH_INVALID) {
+        console.error('\nTip: Check that your API token is correct and has not expired.');
+    }
+    else if (mcpError.type === ErrorType.API_ERROR) {
+        if (mcpError.statusCode === 429) {
+            console.error('\nTip: You may have exceeded your API rate limits. Try again later or upgrade your API plan.');
+        }
+        // Add ip-api.com specific context if available
+        if (originalError && typeof originalError === 'object') {
+            const origErr = originalError;
+            if (origErr.status === 'fail' && origErr.message) {
+                console.error(`\nAPI returned failure: ${String(origErr.message)}`);
+            }
+        }
+    }
+    // Display DEBUG tip
+    if (process.env.DEBUG !== 'mcp:*') {
+        console.error('\nFor more detailed error information, run with DEBUG=mcp:* environment variable.');
+    }
     process.exit(1);
 }

package/dist/utils/error.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.5.9",
+	"version": "1.6.0",
 	"description": "TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/package.json.bak

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.5.8",
+	"version": "1.5.10",
 	"description": "TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/Dockerfile

@@ -1,25 +0,0 @@
-# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
-FROM node:lts-alpine
-
-# Create app directory
-WORKDIR /usr/src/app
-
-# Copy package files
-COPY package*.json ./
-
-# Install dependencies without running prepare scripts
-RUN npm install --ignore-scripts
-
-# Copy source code
-COPY . .
-
-# Build the TypeScript code
-RUN npm run build
-
-# Ensure the entrypoint is executable (already set in prepare, but reensure here)
-RUN chmod +x dist/index.js
-
-EXPOSE 3000
-
-# Start the MCP server
-CMD [ "npm", "start" ]

package/smithery.yaml

@@ -1,34 +0,0 @@
-# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
-
-startCommand:
-  type: stdio
-  configSchema:
-    # JSON Schema defining the configuration options for the MCP.
-    type: object
-    required: []
-    properties:
-      debug:
-        type: boolean
-        default: false
-        description: Enable debug logging
-      ipapiApiToken:
-        type: string
-        default: ""
-        description: API token for the IP API service
-  commandFunction:
-    # A JS function that produces the CLI command based on the given config to start the MCP on stdio.
-    |-
-    (config) => {
-      // Setup environment variables based on provided config
-      const env = Object.assign({}, process.env);
-      if (config.debug) {
-        env.DEBUG = 'true';
-      }
-      if (config.ipapiApiToken) {
-        env.IPAPI_API_TOKEN = config.ipapiApiToken;
-      }
-      return { command: 'node', args: ['dist/index.js'], env };
-    }
-  exampleConfig:
-    debug: true
-    ipapiApiToken: YOUR_API_TOKEN