@aashari/boilerplate-mcp-server 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [1.17.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.16.1...v1.17.0) (2025-12-03)
+
+
+### Bug Fixes
+
+* regenerate package-lock.json to sync with package.json ([aeb3d63](https://github.com/aashari/boilerplate-mcp-server/commit/aeb3d63234a2deaa1257f17a3db6a6538d5345b1))
+
+
+### Features
+
+* add raw response logging with truncation for large API responses ([3ed7b19](https://github.com/aashari/boilerplate-mcp-server/commit/3ed7b191fc51ff2562f9f5ad2d6dc46ff0a22714))
+
+## [1.16.1](https://github.com/aashari/boilerplate-mcp-server/compare/v1.16.0...v1.16.1) (2025-12-01)
+
+
+### Bug Fixes
+
+* **deps:** resolve security vulnerabilities in body-parser and js-yaml ([abd1c08](https://github.com/aashari/boilerplate-mcp-server/commit/abd1c08d9c777ffb04dc851c3c14eeb8a4a09e1c))
+
 # [1.16.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.15.0...v1.16.0) (2025-12-01)
 
 

package/dist/controllers/ipaddress.controller.d.ts

@@ -1,13 +1,8 @@
+import { ControllerResponse } from '../types/common.types.js';
 /**
  * Output format type
  */
 type OutputFormat = 'toon' | 'json';
-/**
- * Controller response type
- */
-interface ControllerResponse {
-    content: string;
-}
 /**
  * @namespace IpAddressController
  * @description Controller responsible for handling IP address lookup logic.

package/dist/controllers/ipaddress.controller.js

@@ -74,9 +74,12 @@ async function get(args = {}) {
             isTestEnvironment,
         });
         let data;
+        let rawResponsePath = null;
         try {
             // Call the service with ipAddress and the mapped serviceOptions
-            data = await vendor_ip_api_com_service_js_1.default.get(args.ipAddress, serviceOptions);
+            const response = await vendor_ip_api_com_service_js_1.default.get(args.ipAddress, serviceOptions);
+            data = response.data;
+            rawResponsePath = response.rawResponsePath;
             methodLogger.debug(`Got the response from the service`, data);
         }
         catch (error) {
@@ -88,10 +91,12 @@ async function get(args = {}) {
                     error.message.includes('Access denied'))) {
                 methodLogger.warn('HTTPS request failed, falling back to HTTP');
                 // Try again with HTTP
-                data = await vendor_ip_api_com_service_js_1.default.get(args.ipAddress, {
+                const fallbackResponse = await vendor_ip_api_com_service_js_1.default.get(args.ipAddress, {
                     ...serviceOptions,
                     useHttps: false,
                 });
+                data = fallbackResponse.data;
+                rawResponsePath = fallbackResponse.rawResponsePath;
                 methodLogger.debug(`Got the response from HTTP fallback`, data);
             }
             else {
@@ -105,7 +110,7 @@ async function get(args = {}) {
         const useToon = args.outputFormat !== 'json';
         // Format the output
         const content = await (0, jq_util_js_1.toOutputString)(filteredData, useToon);
-        return { content };
+        return { content, rawResponsePath };
     }
     catch (error) {
         throw (0, error_handler_util_js_1.handleControllerError)(error, (0, error_handler_util_js_2.buildErrorContext)('IP Address', 'get', 'controllers/ipaddress.controller.ts@get', args.ipAddress || 'current device', { args }));

package/dist/services/vendor.ip-api.com.service.d.ts

@@ -1,4 +1,11 @@
 import { IPDetail, IPApiRequestOptions } from './vendor.ip-api.com.types.js';
+/**
+ * Service response wrapper that includes the data and the path to the raw response file
+ */
+export interface ServiceResponse<T> {
+    data: T;
+    rawResponsePath: string | null;
+}
 /**
  * @namespace VendorIpApiService
  * @description Service layer for interacting directly with the ip-api.com vendor API.
@@ -12,7 +19,7 @@ import { IPDetail, IPApiRequestOptions } from './vendor.ip-api.com.types.js';
  * @memberof VendorIpApiService
  * @param {string} [ipAddress] - Optional IP address to look up. If omitted, fetches details for the current device's public IP.
  * @param {IPApiRequestOptions} [options={}] - Optional request options for the ip-api.com service, such as `useHttps`, `fields`, and `lang`.
- * @returns {Promise<IPDetail>} A promise that resolves to the detailed IP information if the API call is successful.
+ * @returns {Promise<ServiceResponse<IPDetail>>} A promise that resolves to the detailed IP information and raw response path if the API call is successful.
  * @throws {McpError} Throws an `McpError` (specifically `ApiError` or `UnexpectedError`) if:
  *  - The `fetchIpApi` call fails (network error, non-2xx response).
  *  - The ip-api.com response status is not 'success'.
@@ -23,7 +30,7 @@ import { IPDetail, IPApiRequestOptions } from './vendor.ip-api.com.types.js';
  * // Get extended details using HTTPS
  * const extendedDetails = await get('1.1.1.1', { useHttps: true, fields: [...] });
  */
-declare function get(ipAddress?: string, options?: IPApiRequestOptions): Promise<IPDetail>;
+declare function get(ipAddress?: string, options?: IPApiRequestOptions): Promise<ServiceResponse<IPDetail>>;
 declare const _default: {
     get: typeof get;
 };

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

@@ -22,7 +22,7 @@ serviceLogger.debug('IP API service initialized');
  * @memberof VendorIpApiService
  * @param {string} [ipAddress] - Optional IP address to look up. If omitted, fetches details for the current device's public IP.
  * @param {IPApiRequestOptions} [options={}] - Optional request options for the ip-api.com service, such as `useHttps`, `fields`, and `lang`.
- * @returns {Promise<IPDetail>} A promise that resolves to the detailed IP information if the API call is successful.
+ * @returns {Promise<ServiceResponse<IPDetail>>} A promise that resolves to the detailed IP information and raw response path if the API call is successful.
  * @throws {McpError} Throws an `McpError` (specifically `ApiError` or `UnexpectedError`) if:
  *  - The `fetchIpApi` call fails (network error, non-2xx response).
  *  - The ip-api.com response status is not 'success'.
@@ -39,11 +39,13 @@ async function get(ipAddress, options = {}) {
     try {
         // Make the API call with correctly typed response
         // Use a more specific type here since we know the API returns at least status + potential message
-        const rawData = await (0, transport_util_js_1.fetchIpApi)(ipAddress || '', {
+        const response = await (0, transport_util_js_1.fetchIpApi)(ipAddress || '', {
             useHttps: options.useHttps,
             fields: options.fields,
             lang: options.lang,
         });
+        // Extract data and rawResponsePath from TransportResponse
+        const { data: rawData, rawResponsePath } = response;
         // First check API-level success/failure before Zod validation
         // This avoids unnecessary validation errors for known API errors
         if (rawData.status !== 'success') {
@@ -63,7 +65,7 @@ async function get(ipAddress, options = {}) {
         // 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;
+        return { data: validatedData, rawResponsePath };
     }
     catch (error) {
         methodLogger.error(`Service error fetching IP data`, error);

package/dist/tools/ipaddress.tool.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const logger_util_js_1 = require("../utils/logger.util.js");
 const ipaddress_types_js_1 = require("./ipaddress.types.js");
 const error_util_js_1 = require("../utils/error.util.js");
+const formatter_util_js_1 = require("../utils/formatter.util.js");
 const zod_1 = require("zod");
 const ipaddress_controller_js_1 = __importDefault(require("../controllers/ipaddress.controller.js"));
 /**
@@ -35,12 +36,12 @@ async function handleGetIpDetails(args) {
         // Pass args directly to the controller
         const result = await ipaddress_controller_js_1.default.get(args);
         methodLogger.debug(`Got the response from the controller`, result);
-        // Format the response for the MCP tool
+        // Format the response for the MCP tool, applying truncation for large responses
         return {
             content: [
                 {
                     type: 'text',
-                    text: result.content,
+                    text: (0, formatter_util_js_1.truncateForAI)(result.content, result.rawResponsePath),
                 },
             ],
         };

package/dist/types/common.types.d.ts

@@ -3,6 +3,34 @@
  * These types provide a standard interface for controller interactions.
  * Centralized here to ensure consistency across the codebase.
  */
+/**
+ * Common pagination information for API responses.
+ * This is used for providing consistent pagination details to clients.
+ * Note: This is now only used internally by controllers.
+ * The formatted pagination information will be integrated into the content string.
+ */
+export interface ResponsePagination {
+    /**
+     * Cursor for the next page of results, if available.
+     * This should be passed to subsequent requests to retrieve the next page.
+     */
+    nextCursor?: string;
+    /**
+     * Whether more results are available beyond the current page.
+     * When true, clients should use the nextCursor to retrieve more results.
+     */
+    hasMore: boolean;
+    /**
+     * The number of items in the current result set.
+     * This helps clients track how many items they've received.
+     */
+    count?: number;
+    /**
+     * The total number of items available.
+     * This helps clients understand the total scope of their results.
+     */
+    total?: number;
+}
 /**
  * Common response structure for controller operations.
  * All controller methods should return this structure.
@@ -17,4 +45,9 @@ export interface ControllerResponse {
      * including pagination details and any additional metadata.
      */
     content: string;
+    /**
+     * Optional path to the raw API response file.
+     * When the response is truncated, this path allows AI to access the full data.
+     */
+    rawResponsePath?: string | null;
 }

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.16.0";
+export declare const VERSION = "1.17.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.16.0';
+exports.VERSION = '1.17.0';
 /**
  * Package name with scope
  * Used for initialization and identification

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

@@ -34,3 +34,15 @@ export declare function formatBulletList(items: Record<string, unknown>, keyForm
  * @returns Separator line
  */
 export declare function formatSeparator(): string;
+/**
+ * Truncate content for AI consumption and add guidance if truncated
+ *
+ * When responses exceed the token limit, this function truncates the content
+ * and appends guidance for the AI to either access the full response from
+ * the raw log file or refine the request with better filtering.
+ *
+ * @param content - The formatted response content
+ * @param rawResponsePath - Optional path to the raw response file in /tmp/mcp/
+ * @returns Truncated content with guidance if needed, or original content if within limits
+ */
+export declare function truncateForAI(content: string, rawResponsePath?: string | null): string;

package/dist/utils/formatter.util.js

@@ -9,6 +9,7 @@ exports.formatUrl = formatUrl;
 exports.formatHeading = formatHeading;
 exports.formatBulletList = formatBulletList;
 exports.formatSeparator = formatSeparator;
+exports.truncateForAI = truncateForAI;
 /**
  * Format a date in a standardized way: YYYY-MM-DD HH:MM:SS UTC
  * @param dateString - ISO date string or Date object
@@ -114,3 +115,50 @@ function formatValue(value) {
 function formatSeparator() {
     return '---';
 }
+/**
+ * Maximum character limit for AI responses (~10k tokens)
+ * 1 token ≈ 4 characters, so 10k tokens ≈ 40,000 characters
+ */
+const MAX_RESPONSE_CHARS = 40000;
+/**
+ * Truncate content for AI consumption and add guidance if truncated
+ *
+ * When responses exceed the token limit, this function truncates the content
+ * and appends guidance for the AI to either access the full response from
+ * the raw log file or refine the request with better filtering.
+ *
+ * @param content - The formatted response content
+ * @param rawResponsePath - Optional path to the raw response file in /tmp/mcp/
+ * @returns Truncated content with guidance if needed, or original content if within limits
+ */
+function truncateForAI(content, rawResponsePath) {
+    if (content.length <= MAX_RESPONSE_CHARS) {
+        return content;
+    }
+    // Truncate at a reasonable boundary (try to find a newline near the limit)
+    let truncateAt = MAX_RESPONSE_CHARS;
+    const searchStart = Math.max(0, MAX_RESPONSE_CHARS - 500);
+    const lastNewline = content.lastIndexOf('\n', MAX_RESPONSE_CHARS);
+    if (lastNewline > searchStart) {
+        truncateAt = lastNewline;
+    }
+    const truncatedContent = content.substring(0, truncateAt);
+    const originalSize = content.length;
+    const truncatedSize = truncatedContent.length;
+    const percentShown = Math.round((truncatedSize / originalSize) * 100);
+    // Build guidance section
+    const guidance = [
+        '',
+        formatSeparator(),
+        formatHeading('Response Truncated', 2),
+        '',
+        `This response was truncated to ~${Math.round(truncatedSize / 4000)}k tokens (${percentShown}% of original ${Math.round(originalSize / 1000)}k chars).`,
+        '',
+        '**To access the complete data:**',
+    ];
+    if (rawResponsePath) {
+        guidance.push(`- The full raw API response is saved at: \`${rawResponsePath}\``);
+    }
+    guidance.push('- Consider refining your request with more specific filters or selecting fewer fields', '- For paginated data, use smaller page sizes or specific identifiers', '- When searching, use more targeted queries to reduce result sets');
+    return truncatedContent + guidance.join('\n');
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Save raw API response to a file in /tmp/mcp/<project-name>/
+ *
+ * @param url The URL that was called
+ * @param method The HTTP method used
+ * @param requestBody The request body (if any)
+ * @param responseData The raw response data
+ * @param statusCode The HTTP status code
+ * @param durationMs The request duration in milliseconds
+ * @returns The path to the saved file, or null if saving failed
+ */
+export declare function saveRawResponse(url: string, method: string, requestBody: unknown, responseData: unknown, statusCode: number, durationMs: number): string | null;

package/dist/utils/response.util.js

@@ -0,0 +1,149 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveRawResponse = saveRawResponse;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const logger_util_js_1 = require("./logger.util.js");
+const constants_util_js_1 = require("./constants.util.js");
+// Create a contextualized logger for this file
+const responseLogger = logger_util_js_1.Logger.forContext('utils/response.util.ts');
+/**
+ * Get the project name from PACKAGE_NAME, stripping the scope prefix
+ * e.g., "@aashari/boilerplate-mcp-server" -> "boilerplate-mcp-server"
+ */
+function getProjectName() {
+    const name = constants_util_js_1.PACKAGE_NAME.replace(/^@[^/]+\//, '');
+    return name;
+}
+/**
+ * Generate a unique filename with timestamp and random string
+ * Format: <timestamp>-<random>.txt
+ */
+function generateFilename() {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const randomStr = crypto.randomBytes(4).toString('hex');
+    return `${timestamp}-${randomStr}.txt`;
+}
+/**
+ * Ensure the directory exists, creating it if necessary
+ */
+function ensureDirectoryExists(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+        responseLogger.debug(`Created directory: ${dirPath}`);
+    }
+}
+/**
+ * Save raw API response to a file in /tmp/mcp/<project-name>/
+ *
+ * @param url The URL that was called
+ * @param method The HTTP method used
+ * @param requestBody The request body (if any)
+ * @param responseData The raw response data
+ * @param statusCode The HTTP status code
+ * @param durationMs The request duration in milliseconds
+ * @returns The path to the saved file, or null if saving failed
+ */
+function saveRawResponse(url, method, requestBody, responseData, statusCode, durationMs) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/response.util.ts', 'saveRawResponse');
+    try {
+        const projectName = getProjectName();
+        const dirPath = path.join('/tmp', 'mcp', projectName);
+        const filename = generateFilename();
+        const filePath = path.join(dirPath, filename);
+        ensureDirectoryExists(dirPath);
+        // Build the content
+        const content = buildResponseContent(url, method, requestBody, responseData, statusCode, durationMs);
+        // Write to file
+        fs.writeFileSync(filePath, content, 'utf8');
+        methodLogger.debug(`Saved raw response to: ${filePath}`);
+        return filePath;
+    }
+    catch (error) {
+        methodLogger.error('Failed to save raw response', error);
+        return null;
+    }
+}
+/**
+ * Build the content string for the response file
+ */
+function buildResponseContent(url, method, requestBody, responseData, statusCode, durationMs) {
+    const timestamp = new Date().toISOString();
+    const separator = '='.repeat(80);
+    let content = `${separator}
+RAW API RESPONSE LOG
+${separator}
+
+Timestamp: ${timestamp}
+URL: ${url}
+Method: ${method}
+Status Code: ${statusCode}
+Duration: ${durationMs.toFixed(2)}ms
+
+${separator}
+REQUEST BODY
+${separator}
+`;
+    if (requestBody) {
+        content +=
+            typeof requestBody === 'string'
+                ? requestBody
+                : JSON.stringify(requestBody, null, 2);
+    }
+    else {
+        content += '(no request body)';
+    }
+    content += `
+
+${separator}
+RESPONSE DATA
+${separator}
+`;
+    if (responseData !== undefined && responseData !== null) {
+        content +=
+            typeof responseData === 'string'
+                ? responseData
+                : JSON.stringify(responseData, null, 2);
+    }
+    else {
+        content += '(no response data)';
+    }
+    content += `
+${separator}
+`;
+    return content;
+}

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

@@ -13,3 +13,19 @@
  * const output = await toToonOrJson(data, json);
  */
 export declare function toToonOrJson(data: unknown, jsonFallback: string): Promise<string>;
+/**
+ * Synchronous TOON conversion with JSON fallback.
+ *
+ * Uses cached encoder if available, otherwise returns JSON fallback.
+ * Prefer toToonOrJson for first-time conversion.
+ *
+ * @param data - The data to convert
+ * @param jsonFallback - The JSON string to return if TOON is unavailable
+ * @returns TOON formatted string, or JSON fallback
+ */
+export declare function toToonOrJsonSync(data: unknown, jsonFallback: string): string;
+/**
+ * Pre-load the TOON encoder for synchronous usage later.
+ * Call this during server initialization.
+ */
+export declare function preloadToonEncoder(): Promise<boolean>;

package/dist/utils/toon.util.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toToonOrJson = toToonOrJson;
+exports.toToonOrJsonSync = toToonOrJsonSync;
+exports.preloadToonEncoder = preloadToonEncoder;
 const logger_util_js_1 = require("./logger.util.js");
 const logger = logger_util_js_1.Logger.forContext('utils/toon.util.ts');
 /**
@@ -63,3 +65,37 @@ async function toToonOrJson(data, jsonFallback) {
         return jsonFallback;
     }
 }
+/**
+ * Synchronous TOON conversion with JSON fallback.
+ *
+ * Uses cached encoder if available, otherwise returns JSON fallback.
+ * Prefer toToonOrJson for first-time conversion.
+ *
+ * @param data - The data to convert
+ * @param jsonFallback - The JSON string to return if TOON is unavailable
+ * @returns TOON formatted string, or JSON fallback
+ */
+function toToonOrJsonSync(data, jsonFallback) {
+    const methodLogger = logger.forMethod('toToonOrJsonSync');
+    if (!toonEncode) {
+        methodLogger.debug('TOON encoder not loaded, using JSON fallback');
+        return jsonFallback;
+    }
+    try {
+        const toonResult = toonEncode(data, { indent: 2 });
+        methodLogger.debug('Successfully converted to TOON format');
+        return toonResult;
+    }
+    catch (error) {
+        methodLogger.error('TOON conversion failed, using JSON fallback', error);
+        return jsonFallback;
+    }
+}
+/**
+ * Pre-load the TOON encoder for synchronous usage later.
+ * Call this during server initialization.
+ */
+async function preloadToonEncoder() {
+    const encode = await loadToonEncoder();
+    return encode !== null;
+}

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

@@ -13,6 +13,13 @@ export interface RequestOptions {
     headers?: Record<string, string>;
     body?: unknown;
 }
+/**
+ * Transport response wrapper that includes the data and the path to the raw response file
+ */
+export interface TransportResponse<T> {
+    data: T;
+    rawResponsePath: string | null;
+}
 /**
  * Retrieves IP API credentials from configuration.
  * Specifically checks for IPAPI_API_TOKEN.
@@ -29,21 +36,21 @@ export declare function getIpApiCredentials(): IpApiCredentials;
  * @param options.useHttps - Use HTTPS (requires paid plan for ip-api.com). Defaults to false.
  * @param options.fields - Specific fields to request from ip-api.com.
  * @param options.lang - Language code for response data.
- * @returns The response data parsed as type T.
+ * @returns Transport response with data and raw response path.
  * @throws {McpError} If the request fails, including network errors, API errors, or parsing issues.
  */
 export declare function fetchIpApi<T>(path: string, options?: RequestOptions & {
     useHttps?: boolean;
     fields?: string[];
     lang?: string;
-}): Promise<T>;
+}): Promise<TransportResponse<T>>;
 /**
  * Generic and reusable function to fetch data from any API endpoint.
  * Handles standard HTTP request setup, response checking, basic error handling, and logging.
  *
  * @param url The full URL to fetch data from.
  * @param options Request options including method, headers, and body.
- * @returns The response data parsed as type T.
+ * @returns Transport response with data and raw response path.
  * @throws {McpError} If the request fails, including network errors, non-OK HTTP status, or JSON parsing issues.
  */
-export declare function fetchApi<T>(url: string, options?: RequestOptions): Promise<T>;
+export declare function fetchApi<T>(url: string, options?: RequestOptions): Promise<TransportResponse<T>>;

package/dist/utils/transport.util.js

@@ -6,6 +6,7 @@ exports.fetchApi = fetchApi;
 const logger_util_js_1 = require("./logger.util.js");
 const config_util_js_1 = require("./config.util.js");
 const error_util_js_1 = require("./error.util.js");
+const response_util_js_1 = require("./response.util.js");
 // Create a contextualized logger for this file
 const transportLogger = logger_util_js_1.Logger.forContext('utils/transport.util.ts');
 // Log transport utility initialization
@@ -37,7 +38,7 @@ function getIpApiCredentials() {
  * @param options.useHttps - Use HTTPS (requires paid plan for ip-api.com). Defaults to false.
  * @param options.fields - Specific fields to request from ip-api.com.
  * @param options.lang - Language code for response data.
- * @returns The response data parsed as type T.
+ * @returns Transport response with data and raw response path.
  * @throws {McpError} If the request fails, including network errors, API errors, or parsing issues.
  */
 async function fetchIpApi(path, options = {}) {
@@ -86,7 +87,7 @@ async function fetchIpApi(path, options = {}) {
  *
  * @param url The full URL to fetch data from.
  * @param options Request options including method, headers, and body.
- * @returns The response data parsed as type T.
+ * @returns Transport response with data and raw response path.
  * @throws {McpError} If the request fails, including network errors, non-OK HTTP status, or JSON parsing issues.
  */
 async function fetchApi(url, options = {}) {
@@ -134,7 +135,9 @@ async function fetchApi(url, options = {}) {
         try {
             const responseData = await response.json();
             methodLogger.debug('Response body successfully parsed as JSON.');
-            return responseData;
+            // Save raw response to file and capture the path
+            const rawResponsePath = (0, response_util_js_1.saveRawResponse)(url, requestOptions.method || 'GET', options.body, responseData, response.status, parseFloat(duration));
+            return { data: responseData, rawResponsePath };
         }
         catch (parseError) {
             methodLogger.error('Failed to parse API response JSON:', parseError);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.16.0",
+	"version": "1.17.0",
 	"description": "TypeScript MCP server boilerplate with STDIO and HTTP transport support, CLI tools, and extensible architecture",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -19,15 +19,23 @@
 		"clean": "rm -rf dist coverage",
 		"test": "jest",
 		"test:coverage": "jest --coverage",
+		"test:cli": "jest src/cli/.*\\.cli\\.test\\.ts --runInBand --testTimeout=60000",
 		"lint": "eslint src --ext .ts --config eslint.config.mjs",
-		"update:deps": "npx npm-check-updates -u && npm install --legacy-peer-deps",
 		"format": "prettier --write 'src/**/*.ts' 'scripts/**/*.js'",
-		"cli": "npm run build && node dist/index.js",
-		"mcp:stdio": "npm run build && TRANSPORT_MODE=stdio node dist/index.js",
-		"mcp:http": "npm run build && TRANSPORT_MODE=http node dist/index.js",
-		"mcp:inspect": "npm run build && (TRANSPORT_MODE=http node dist/index.js &) && sleep 2 && npx @modelcontextprotocol/inspector http://localhost:3000/mcp",
+		"publish:npm": "npm publish",
+		"update:check": "npx npm-check-updates",
+		"update:deps": "npx npm-check-updates -u && npm install --legacy-peer-deps",
+		"update:version": "node scripts/update-version.js",
+		"mcp:stdio": "TRANSPORT_MODE=stdio npm run build && node dist/index.js",
+		"mcp:http": "TRANSPORT_MODE=http npm run build && node dist/index.js",
+		"mcp:inspect": "TRANSPORT_MODE=http npm run build && (node dist/index.js &) && sleep 2 && npx @modelcontextprotocol/inspector http://localhost:3000/mcp",
 		"dev:stdio": "npm run build && npx @modelcontextprotocol/inspector -e TRANSPORT_MODE=stdio -e DEBUG=true node dist/index.js",
-		"dev:http": "npm run build && DEBUG=true TRANSPORT_MODE=http node dist/index.js"
+		"dev:http": "DEBUG=true TRANSPORT_MODE=http npm run build && node dist/index.js",
+		"dev:server": "DEBUG=true npm run build && npx @modelcontextprotocol/inspector -e DEBUG=true node dist/index.js",
+		"dev:cli": "DEBUG=true npm run build && DEBUG=true node dist/index.js",
+		"start:server": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
+		"start:cli": "npm run build && node dist/index.js",
+		"cli": "npm run build && node dist/index.js"
 	},
 	"keywords": [
 		"mcp",
@@ -66,11 +74,15 @@
 		"@typescript-eslint/parser": "^8.48.0",
 		"eslint": "^9.39.1",
 		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-filenames": "^1.3.2",
 		"eslint-plugin-prettier": "^5.5.4",
 		"jest": "^30.2.0",
+		"nodemon": "^3.1.11",
+		"npm-check-updates": "^19.1.2",
 		"prettier": "^3.7.3",
 		"semantic-release": "^25.0.2",
 		"ts-jest": "^29.4.5",
+		"ts-node": "^10.9.2",
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.48.0"
 	},
@@ -100,7 +112,17 @@
 		"collectCoverageFrom": [
 			"src/**/*.ts",
 			"!src/**/*.test.ts",
-			"!src/utils/jest.setup.ts"
+			"!src/**/*.spec.ts"
+		],
+		"coveragePathIgnorePatterns": [
+			"/node_modules/",
+			"/dist/",
+			"/coverage/"
+		],
+		"coverageReporters": [
+			"text",
+			"lcov",
+			"json-summary"
 		],
 		"transform": {
 			"^.+\\.tsx?$": [
@@ -115,6 +137,14 @@
 		},
 		"extensionsToTreatAsEsm": [
 			".ts"
+		],
+		"moduleFileExtensions": [
+			"ts",
+			"tsx",
+			"js",
+			"jsx",
+			"json",
+			"node"
 		]
 	}
 }

package/package.json.bak

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.15.0",
+	"version": "1.16.1",
 	"description": "TypeScript MCP server boilerplate with STDIO and HTTP transport support, CLI tools, and extensible architecture",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -19,15 +19,23 @@
 		"clean": "rm -rf dist coverage",
 		"test": "jest",
 		"test:coverage": "jest --coverage",
+		"test:cli": "jest src/cli/.*\\.cli\\.test\\.ts --runInBand --testTimeout=60000",
 		"lint": "eslint src --ext .ts --config eslint.config.mjs",
-		"update:deps": "npx npm-check-updates -u && npm install --legacy-peer-deps",
 		"format": "prettier --write 'src/**/*.ts' 'scripts/**/*.js'",
-		"cli": "npm run build && node dist/index.js",
-		"mcp:stdio": "npm run build && TRANSPORT_MODE=stdio node dist/index.js",
-		"mcp:http": "npm run build && TRANSPORT_MODE=http node dist/index.js",
-		"mcp:inspect": "npm run build && (TRANSPORT_MODE=http node dist/index.js &) && sleep 2 && npx @modelcontextprotocol/inspector http://localhost:3000/mcp",
+		"publish:npm": "npm publish",
+		"update:check": "npx npm-check-updates",
+		"update:deps": "npx npm-check-updates -u && npm install --legacy-peer-deps",
+		"update:version": "node scripts/update-version.js",
+		"mcp:stdio": "TRANSPORT_MODE=stdio npm run build && node dist/index.js",
+		"mcp:http": "TRANSPORT_MODE=http npm run build && node dist/index.js",
+		"mcp:inspect": "TRANSPORT_MODE=http npm run build && (node dist/index.js &) && sleep 2 && npx @modelcontextprotocol/inspector http://localhost:3000/mcp",
 		"dev:stdio": "npm run build && npx @modelcontextprotocol/inspector -e TRANSPORT_MODE=stdio -e DEBUG=true node dist/index.js",
-		"dev:http": "npm run build && DEBUG=true TRANSPORT_MODE=http node dist/index.js"
+		"dev:http": "DEBUG=true TRANSPORT_MODE=http npm run build && node dist/index.js",
+		"dev:server": "DEBUG=true npm run build && npx @modelcontextprotocol/inspector -e DEBUG=true node dist/index.js",
+		"dev:cli": "DEBUG=true npm run build && DEBUG=true node dist/index.js",
+		"start:server": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
+		"start:cli": "npm run build && node dist/index.js",
+		"cli": "npm run build && node dist/index.js"
 	},
 	"keywords": [
 		"mcp",
@@ -66,11 +74,15 @@
 		"@typescript-eslint/parser": "^8.48.0",
 		"eslint": "^9.39.1",
 		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-filenames": "^1.3.2",
 		"eslint-plugin-prettier": "^5.5.4",
 		"jest": "^30.2.0",
+		"nodemon": "^3.1.11",
+		"npm-check-updates": "^19.1.2",
 		"prettier": "^3.7.3",
 		"semantic-release": "^25.0.2",
 		"ts-jest": "^29.4.5",
+		"ts-node": "^10.9.2",
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.48.0"
 	},
@@ -100,7 +112,17 @@
 		"collectCoverageFrom": [
 			"src/**/*.ts",
 			"!src/**/*.test.ts",
-			"!src/utils/jest.setup.ts"
+			"!src/**/*.spec.ts"
+		],
+		"coveragePathIgnorePatterns": [
+			"/node_modules/",
+			"/dist/",
+			"/coverage/"
+		],
+		"coverageReporters": [
+			"text",
+			"lcov",
+			"json-summary"
 		],
 		"transform": {
 			"^.+\\.tsx?$": [
@@ -115,6 +137,14 @@
 		},
 		"extensionsToTreatAsEsm": [
 			".ts"
+		],
+		"moduleFileExtensions": [
+			"ts",
+			"tsx",
+			"js",
+			"jsx",
+			"json",
+			"node"
 		]
 	}
 }