@aashari/boilerplate-mcp-server 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [1.5.1](https://github.com/aashari/boilerplate-mcp-server/compare/v1.5.0...v1.5.1) (2025-05-05)
+
+
+### Bug Fixes
+
+* Improve cross-platform compatibility for npx execution ([d840c51](https://github.com/aashari/boilerplate-mcp-server/commit/d840c51cc94ad3d54e5c38670b774cdb7d52b8a7))
+
+
+### Performance Improvements
+
+* Update dependencies ([cbc63fe](https://github.com/aashari/boilerplate-mcp-server/commit/cbc63fe692f563a3e1b68bb136b8f567408fbf9c))
+
 # [1.5.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.4.9...v1.5.0) (2025-05-05)
 
 

package/dist/index.js

@@ -105,6 +105,17 @@ async function main() {
         await startServer();
         mainLogger.info('Server is now running');
     }
+    // --- Start: Add Graceful Shutdown ---
+    const shutdown = async (signal) => {
+        mainLogger.info(`Received ${signal}. Shutting down gracefully...`);
+        // Add any specific cleanup logic here if needed in the future
+        // For now, just exiting cleanly is the main goal
+        // No need to explicitly call server disconnect if process exits
+        process.exit(0);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT')); // Ctrl+C
+    process.on('SIGTERM', () => shutdown('SIGTERM')); // kill command
+    // --- End: Add Graceful Shutdown ---
 }
 // If this file is being executed directly (not imported), run the main function
 if (require.main === module) {

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

@@ -3,27 +3,6 @@
  * 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.
- */
-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;
-}
 /**
  * Common response structure for controller operations.
  * All controller methods should return this structure.
@@ -35,8 +14,7 @@ export interface ControllerResponse {
      */
     content: string;
     /**
-     * Optional pagination information for list operations.
-     * If present, indicates that more results are available.
+     * Optional metadata for any extra information associated with the response.
      */
-    pagination?: ResponsePagination;
+    metadata?: Record<string, unknown>;
 }

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

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

@@ -2,7 +2,6 @@
  * Standardized formatting utilities for consistent output across all CLI and Tool interfaces.
  * These functions should be used by all formatters to ensure consistent formatting.
  */
-import type { ResponsePagination } from './pagination.util.js';
 /**
  * Format a date in a standardized way: YYYY-MM-DD HH:MM:SS UTC
  * @param dateString - ISO date string or Date object
@@ -35,10 +34,3 @@ export declare function formatBulletList(items: Record<string, unknown>, keyForm
  * @returns Separator line
  */
 export declare function formatSeparator(): string;
-/**
- * Formats the pagination information into a standardized footer string for CLI output.
- *
- * @param {ResponsePagination | undefined} pagination - The standardized pagination object.
- * @returns {string} A formatted string summarizing pagination and next steps, or an empty string if no pagination.
- */
-export declare function formatPagination(pagination: ResponsePagination | undefined): string;

package/dist/utils/formatter.util.js

@@ -9,7 +9,6 @@ exports.formatUrl = formatUrl;
 exports.formatHeading = formatHeading;
 exports.formatBulletList = formatBulletList;
 exports.formatSeparator = formatSeparator;
-exports.formatPagination = formatPagination;
 /**
  * Format a date in a standardized way: YYYY-MM-DD HH:MM:SS UTC
  * @param dateString - ISO date string or Date object
@@ -115,39 +114,3 @@ function formatValue(value) {
 function formatSeparator() {
     return '---';
 }
-/**
- * Formats the pagination information into a standardized footer string for CLI output.
- *
- * @param {ResponsePagination | undefined} pagination - The standardized pagination object.
- * @returns {string} A formatted string summarizing pagination and next steps, or an empty string if no pagination.
- */
-function formatPagination(pagination) {
-    if (!pagination) {
-        return '';
-    }
-    const { count, hasMore, total, nextCursor, startAt, limit, nextPage, entityType, } = pagination;
-    const entity = entityType ? ` ${entityType.toLowerCase()}` : ' items'; // Default to 'items'
-    const lines = [formatSeparator()];
-    if (total !== undefined && total !== null) {
-        lines.push(`*Showing ${count} of ${total}${entity}.*`);
-    }
-    else {
-        lines.push(`*Showing ${count}${entity}.*`);
-    }
-    if (hasMore) {
-        lines.push('More results are available.');
-        if (nextCursor) {
-            lines.push(`*Use --cursor "${nextCursor}" to view more.*`);
-        }
-        else if (nextPage !== undefined) {
-            lines.push(`*Use --page ${nextPage} to view more.*`);
-        }
-        else if (startAt !== undefined && limit !== undefined) {
-            const nextStartAt = startAt + limit;
-            lines.push(`*Use --start-at ${nextStartAt} to view more.*`);
-        }
-    }
-    // Add the standard timestamp footer at the very end
-    lines.push(`*Information retrieved at: ${formatDate(new Date())}*`);
-    return lines.join('\n');
-}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.5.0",
+	"version": "1.5.1",
 	"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",
@@ -14,11 +14,12 @@
 		"mcp-server": "./dist/index.js"
 	},
 	"scripts": {
-		"build": "tsc",
+		"build": "rimraf dist && tsc",
 		"prepare": "npm run build && chmod +x dist/index.js",
-		"postinstall": "chmod +x dist/index.js || true",
+		"postinstall": "node scripts/ensure-executable.js || true",
 		"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",
 		"format": "prettier --write 'src/**/*.ts' 'scripts/**/*.js'",
 		"publish:npm": "npm publish",
@@ -70,6 +71,7 @@
 		"nodemon": "^3.1.10",
 		"npm-check-updates": "^18.0.1",
 		"prettier": "^3.5.3",
+		"rimraf": "^6.0.1",
 		"semantic-release": "^24.2.3",
 		"ts-jest": "^29.3.2",
 		"ts-node": "^10.9.2",
@@ -84,7 +86,7 @@
 		"@modelcontextprotocol/sdk": "^1.11.0",
 		"commander": "^13.1.0",
 		"dotenv": "^16.5.0",
-		"zod": "^3.24.3"
+		"zod": "^3.24.4"
 	},
 	"directories": {
 		"example": "examples"

package/package.json.bak

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.4.9",
+	"version": "1.5.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",
@@ -14,11 +14,12 @@
 		"mcp-server": "./dist/index.js"
 	},
 	"scripts": {
-		"build": "tsc",
+		"build": "rimraf dist && tsc",
 		"prepare": "npm run build && chmod +x dist/index.js",
-		"postinstall": "chmod +x dist/index.js || true",
+		"postinstall": "node scripts/ensure-executable.js || true",
 		"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",
 		"format": "prettier --write 'src/**/*.ts' 'scripts/**/*.js'",
 		"publish:npm": "npm publish",
@@ -70,6 +71,7 @@
 		"nodemon": "^3.1.10",
 		"npm-check-updates": "^18.0.1",
 		"prettier": "^3.5.3",
+		"rimraf": "^6.0.1",
 		"semantic-release": "^24.2.3",
 		"ts-jest": "^29.3.2",
 		"ts-node": "^10.9.2",
@@ -84,7 +86,7 @@
 		"@modelcontextprotocol/sdk": "^1.11.0",
 		"commander": "^13.1.0",
 		"dotenv": "^16.5.0",
-		"zod": "^3.24.3"
+		"zod": "^3.24.4"
 	},
 	"directories": {
 		"example": "examples"

package/scripts/ensure-executable.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Use dynamic import meta for ESM compatibility
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '..');
+const entryPoint = path.join(rootDir, 'dist', 'index.js');
+
+try {
+	if (fs.existsSync(entryPoint)) {
+		// Ensure the file is executable (cross-platform)
+		const currentMode = fs.statSync(entryPoint).mode;
+		// Check if executable bits are set (user, group, or other)
+		// Mode constants differ slightly across platforms, checking broadly
+		const isExecutable =
+			currentMode & fs.constants.S_IXUSR ||
+			currentMode & fs.constants.S_IXGRP ||
+			currentMode & fs.constants.S_IXOTH;
+
+		if (!isExecutable) {
+			// Set permissions to 755 (rwxr-xr-x) if not executable
+			fs.chmodSync(entryPoint, 0o755);
+			console.log(
+				`Made ${path.relative(rootDir, entryPoint)} executable`,
+			);
+		} else {
+			// console.log(`${path.relative(rootDir, entryPoint)} is already executable`);
+		}
+	} else {
+		// console.warn(`${path.relative(rootDir, entryPoint)} not found, skipping chmod`);
+	}
+} catch (err) {
+	// console.warn(`Failed to set executable permissions: ${err.message}`);
+	// We use '|| true' in package.json, so no need to exit here
+}

package/dist/utils/constants.util.js.bak

@@ -1,24 +0,0 @@
-"use strict";
-/**
- * Application constants
- *
- * This file contains constants used throughout the application.
- * Centralizing these values makes them easier to maintain and update.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLI_NAME = exports.PACKAGE_NAME = exports.VERSION = void 0;
-/**
- * Current application version
- * This should match the version in package.json
- */
-exports.VERSION = '1.1.3';
-/**
- * Package name with scope
- * Used for initialization and identification
- */
-exports.PACKAGE_NAME = '@aashari/boilerplate-mcp-server';
-/**
- * CLI command name
- * Used for binary name and CLI help text
- */
-exports.CLI_NAME = 'mcp-boilerplate';

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

@@ -1,31 +0,0 @@
-/**
- * Enum for different pagination types used by APIs.
- */
-export declare enum PaginationType {
-    CURSOR = "CURSOR",// Cursor-based (e.g., Confluence v2)
-    OFFSET = "OFFSET",// Offset-based (e.g., Jira)
-    PAGE = "PAGE"
-}
-/**
- * Standardized pagination information returned by controllers.
- */
-export interface ResponsePagination {
-    count: number;
-    hasMore: boolean;
-    limit?: number;
-    startAt?: number;
-    total?: number;
-    nextCursor?: string;
-    nextPage?: number;
-    entityType?: string;
-}
-/**
- * Extracts standardized pagination information from various API response formats.
- *
- * @param data - The raw API response data. Expected to contain pagination fields.
- * @param type - The type of pagination the API uses (CURSOR, OFFSET, PAGE).
- * @param entityType - Optional name of the entity being paginated (for messages).
- * @returns A standardized ResponsePagination object, or undefined if no pagination info found.
- */
-export declare function extractPaginationInfo(data: any, // Using 'any' here as API responses vary greatly
-type: PaginationType, entityType?: string): ResponsePagination | undefined;

package/dist/utils/pagination.util.js

@@ -1,124 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PaginationType = void 0;
-exports.extractPaginationInfo = extractPaginationInfo;
-const logger_util_js_1 = require("./logger.util.js");
-const logger = logger_util_js_1.Logger.forContext('utils/pagination.util.ts');
-logger.debug('Pagination utility initialized');
-/**
- * Enum for different pagination types used by APIs.
- */
-var PaginationType;
-(function (PaginationType) {
-    PaginationType["CURSOR"] = "CURSOR";
-    PaginationType["OFFSET"] = "OFFSET";
-    PaginationType["PAGE"] = "PAGE";
-})(PaginationType || (exports.PaginationType = PaginationType = {}));
-/**
- * Extracts standardized pagination information from various API response formats.
- *
- * @param data - The raw API response data. Expected to contain pagination fields.
- * @param type - The type of pagination the API uses (CURSOR, OFFSET, PAGE).
- * @param entityType - Optional name of the entity being paginated (for messages).
- * @returns A standardized ResponsePagination object, or undefined if no pagination info found.
- */
-function extractPaginationInfo(
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-data, // Using 'any' here as API responses vary greatly
-type, entityType) {
-    if (!data) {
-        return undefined;
-    }
-    let count = 0;
-    let hasMore = false;
-    let total = undefined;
-    let nextCursor = undefined;
-    let nextPage = undefined;
-    let startAt = undefined;
-    let limit = undefined;
-    // Common count extraction
-    if (Array.isArray(data.results)) {
-        count = data.results.length;
-    }
-    else if (Array.isArray(data.values)) {
-        count = data.values.length;
-    }
-    else if (Array.isArray(data.issues)) {
-        count = data.issues.length;
-    }
-    else if (Array.isArray(data)) {
-        // Handle cases where the response is just an array (e.g., global statuses)
-        count = data.length;
-        // Assume no more pages if the response is just an array without metadata
-        hasMore = false;
-        return { count, hasMore, entityType };
-    }
-    switch (type) {
-        case PaginationType.CURSOR:
-            // Confluence v2 style (_links.next)
-            if (data._links?.next) {
-                hasMore = true;
-                // Extract cursor from the 'next' link query parameters
-                try {
-                    const nextUrl = new URL(data._links.next, 'http://dummy.base');
-                    nextCursor =
-                        nextUrl.searchParams.get('cursor') || undefined;
-                }
-                catch (e) {
-                    logger.warn('Failed to parse next link URL for cursor:', e);
-                }
-            }
-            // Limit might be present in the main response or derivable
-            limit = data.limit || data.size || count; // Use count as fallback limit if not explicit
-            break;
-        case PaginationType.OFFSET:
-            // Jira style (startAt, maxResults, total, isLast)
-            startAt = data.startAt ?? 0;
-            limit = data.maxResults;
-            total = data.total;
-            hasMore = data.isLast === false;
-            // Calculate next startAt if possible
-            if (hasMore && limit !== undefined) {
-                // Keep startAt as is, formatter will calculate next step
-            }
-            break;
-        case PaginationType.PAGE:
-            // Bitbucket style (page, pagelen, size, next)
-            limit = data.pagelen;
-            total = data.size; // Bitbucket uses 'size' for total
-            hasMore = !!data.next;
-            if (hasMore) {
-                // Try to parse the page number from the next URL
-                try {
-                    const nextUrl = new URL(data.next);
-                    nextPage = parseInt(nextUrl.searchParams.get('page') || '', 10);
-                    if (isNaN(nextPage)) {
-                        nextPage = (data.page || 1) + 1; // Fallback calculation
-                    }
-                }
-                catch (e) {
-                    logger.warn('Failed to parse next link URL for page:', e);
-                    nextPage = (data.page || 1) + 1; // Fallback calculation
-                }
-            }
-            break;
-        default:
-            logger.warn('Unknown pagination type provided:', type);
-            return undefined; // Unknown type
-    }
-    // If count is zero and there's no indication of more pages, return undefined
-    if (count === 0 && !hasMore && total === 0) {
-        return undefined;
-    }
-    // Return standardized pagination object
-    return {
-        count,
-        hasMore,
-        limit,
-        startAt,
-        total,
-        nextCursor,
-        nextPage,
-        entityType,
-    };
-}