@aashari/boilerplate-mcp-server 1.1.0 → 1.1.1

package/.releaserc.json

@@ -20,7 +20,12 @@
 		[
 			"@semantic-release/git",
 			{
-				"assets": ["package.json", "CHANGELOG.md", "src/index.ts"],
+				"assets": [
+					"package.json",
+					"CHANGELOG.md",
+					"src/index.ts",
+					"src/cli/index.ts"
+				],
 				"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
 			}
 		],

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [1.1.1](https://github.com/aashari/boilerplate-mcp-server/compare/v1.1.0...v1.1.1) (2025-03-27)
+
+
+### Performance Improvements
+
+* **core:** refactor code structure to align with Atlassian MCP patterns ([090fd56](https://github.com/aashari/boilerplate-mcp-server/commit/090fd5653ab62d70eb75c49828a9876f54cee6fc))
+* **standards:** align codebase with Atlassian MCP server patterns ([8b8eb13](https://github.com/aashari/boilerplate-mcp-server/commit/8b8eb13fd4ce18158e83c4f8c7044ce06287f23e))
+* **tests:** add CLI test infrastructure and ipaddress tests ([ccee308](https://github.com/aashari/boilerplate-mcp-server/commit/ccee308a86e076a67756e9113b481aa3848f40b7))
+* **utils:** implement standardized core utilities and error handling ([6c14a2f](https://github.com/aashari/boilerplate-mcp-server/commit/6c14a2f83397f79cc39f0b7ec70b40e9d9755b9c))
+
 # [1.1.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.0.3...v1.1.0) (2025-03-23)
 
 

package/dist/cli/index.js

@@ -8,21 +8,24 @@ const commander_1 = require("commander");
 const logger_util_js_1 = require("../utils/logger.util.js");
 const ipaddress_cli_js_1 = __importDefault(require("./ipaddress.cli.js"));
 // Get the version from package.json
-const VERSION = '1.1.0'; // This should match the version in src/index.ts
+const VERSION = '1.1.1'; // This should match the version in src/index.ts
 const NAME = '@aashari/boilerplate-mcp-server';
 const DESCRIPTION = 'A boilerplate Model Context Protocol (MCP) server implementation using TypeScript';
 async function runCli(args) {
+    const methodLogger = logger_util_js_1.Logger.forContext('cli/index.ts', 'runCli');
+    methodLogger.debug('Processing CLI arguments', args);
     const program = new commander_1.Command();
     program.name(NAME).description(DESCRIPTION).version(VERSION);
     // Register CLI commands
     ipaddress_cli_js_1.default.register(program);
     // Handle unknown commands
     program.on('command:*', (operands) => {
-        logger_util_js_1.logger.error(`[src/cli/index.ts] Unknown command: ${operands[0]}`);
+        methodLogger.error(`Unknown command: ${operands[0]}`);
         console.log('');
         program.help();
         process.exit(1);
     });
     // Parse arguments; default to help if no command provided
     await program.parseAsync(args.length ? args : ['--help'], { from: 'user' });
+    methodLogger.debug('CLI command execution completed');
 }

package/dist/cli/index.js.bak

@@ -12,17 +12,20 @@ const VERSION = '1.0.1'; // This should match the version in src/index.ts
 const NAME = '@aashari/boilerplate-mcp-server';
 const DESCRIPTION = 'A boilerplate Model Context Protocol (MCP) server implementation using TypeScript';
 async function runCli(args) {
+    const methodLogger = logger_util_js_1.Logger.forContext('cli/index.ts', 'runCli');
+    methodLogger.debug('Processing CLI arguments', args);
     const program = new commander_1.Command();
     program.name(NAME).description(DESCRIPTION).version(VERSION);
     // Register CLI commands
     ipaddress_cli_js_1.default.register(program);
     // Handle unknown commands
     program.on('command:*', (operands) => {
-        logger_util_js_1.logger.error(`[src/cli/index.ts] Unknown command: ${operands[0]}`);
+        methodLogger.error(`Unknown command: ${operands[0]}`);
         console.log('');
         program.help();
         process.exit(1);
     });
     // Parse arguments; default to help if no command provided
     await program.parseAsync(args.length ? args : ['--help'], { from: 'user' });
+    methodLogger.debug('CLI command execution completed');
 }

package/dist/cli/ipaddress.cli.js

@@ -11,16 +11,18 @@ const ipaddress_controller_js_1 = __importDefault(require("../controllers/ipaddr
  * @param program The Commander program instance
  */
 function register(program) {
-    logger_util_js_1.logger.debug(`[src/cli/ipaddress.cli.ts@register] Registering IP address CLI commands...`);
+    const methodLogger = logger_util_js_1.Logger.forContext('cli/ipaddress.cli.ts', 'register');
+    methodLogger.debug(`Registering IP address CLI commands...`);
     program
         .command('get-ip-details')
         .description('Get details about a specific IP address or the current device')
         .argument('[ipAddress]', 'IP address to lookup (optional)')
         .action(async (ipAddress) => {
+        const actionLogger = logger_util_js_1.Logger.forContext('cli/ipaddress.cli.ts', 'get-ip-details');
         try {
-            logger_util_js_1.logger.debug(`[src/cli/ipaddress.cli.ts@get-ip-details] Fetching IP details for ${ipAddress || 'current device'}...`);
+            actionLogger.debug(`Fetching IP details for ${ipAddress || 'current device'}...`);
             const result = await ipaddress_controller_js_1.default.get(ipAddress);
-            logger_util_js_1.logger.debug(`[src/cli/ipaddress.cli.ts@get-ip-details] IP details fetched successfully`, result);
+            actionLogger.debug(`IP details fetched successfully`, result);
             console.log(result.content);
         }
         catch (error) {

package/dist/cli/ipaddress.cli.test.d.ts

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

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

@@ -1,6 +1,5 @@
-declare function get(ipAddress?: string): Promise<{
-    content: string;
-}>;
+import { ControllerResponse } from '../types/common.types.js';
+declare function get(ipAddress?: string): Promise<ControllerResponse>;
 declare const _default: {
     get: typeof get;
 };

package/dist/controllers/ipaddress.controller.js

@@ -5,29 +5,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const vendor_ip_api_com_service_js_1 = __importDefault(require("../services/vendor.ip-api.com.service.js"));
 const logger_util_js_1 = require("../utils/logger.util.js");
-const error_util_js_1 = require("../utils/error.util.js");
+const ipaddress_formatter_js_1 = require("./ipaddress.formatter.js");
+const error_handler_util_js_1 = require("../utils/error-handler.util.js");
+const defaults_util_js_1 = require("../utils/defaults.util.js");
 async function get(ipAddress) {
-    logger_util_js_1.logger.debug(`[src/controllers/ipaddress.controller.ts@get] Getting IP address details...`);
+    const methodLogger = logger_util_js_1.Logger.forContext('controllers/ipaddress.controller.ts', 'get');
+    methodLogger.debug(`Getting IP address details...`);
     try {
+        // Create defaults object (even if empty now)
+        const defaults = {}; // Placeholder
+        // Apply defaults (will just return the empty options object for now)
+        const mergedOptions = (0, defaults_util_js_1.applyDefaults)({}, defaults);
+        methodLogger.debug('Using options after defaults:', mergedOptions); // Log merged options
         const ipData = await vendor_ip_api_com_service_js_1.default.get(ipAddress);
-        logger_util_js_1.logger.debug(`[src/controllers/ipaddress.controller.ts@get] Got the response from the service`, ipData);
-        const lines = [];
-        for (const [key, value] of Object.entries(ipData)) {
-            lines.push(`${key}: ${value}`);
-        }
-        return {
-            content: lines.join('\n'),
-        };
+        methodLogger.debug(`Got the response from the service`, ipData);
+        const formattedContent = (0, ipaddress_formatter_js_1.formatIpDetails)(ipData);
+        // Return the standard ControllerResponse structure
+        return { content: formattedContent };
     }
     catch (error) {
-        // Log the error
-        logger_util_js_1.logger.error(`[src/controllers/ipaddress.controller.ts@get] Error getting IP details`, error);
-        // Pass McpErrors through
-        if (error instanceof error_util_js_1.McpError) {
-            throw error;
-        }
-        // Wrap other errors
-        throw (0, error_util_js_1.createUnexpectedError)('Failed to get IP address details', error);
+        // Use the standardized error handler
+        (0, error_handler_util_js_1.handleControllerError)(error, {
+            entityType: 'IP Address Details',
+            operation: 'retrieving',
+            source: 'controllers/ipaddress.controller.ts@get',
+            additionalInfo: { ipAddress },
+        });
+        // handleControllerError always throws, so no return/throw is needed after it.
     }
 }
 exports.default = { get };

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

@@ -0,0 +1,7 @@
+import { IPDetail } from '../services/vendor.ip-api.com.type.js';
+/**
+ * Format IP address details into Markdown.
+ * @param ipData - Raw IP details from the ip-api.com service.
+ * @returns Formatted Markdown string.
+ */
+export declare function formatIpDetails(ipData: IPDetail): string;

package/dist/controllers/ipaddress.formatter.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatIpDetails = formatIpDetails;
+const formatter_util_js_1 = require("../utils/formatter.util.js"); // Import from the newly created util
+/**
+ * Format IP address details into Markdown.
+ * @param ipData - Raw IP details from the ip-api.com service.
+ * @returns Formatted Markdown string.
+ */
+function formatIpDetails(ipData) {
+    const lines = [];
+    // Add a main heading
+    lines.push((0, formatter_util_js_1.formatHeading)(`IP Address Details: ${ipData.query}`, 1));
+    lines.push('');
+    // Use formatBulletList for the properties
+    // First cast to unknown, then to Record<string, unknown> to avoid TypeScript error
+    lines.push((0, formatter_util_js_1.formatBulletList)(ipData));
+    // Add a timestamp footer
+    lines.push('');
+    lines.push(`*Details retrieved at ${(0, formatter_util_js_1.formatDate)(new Date())}*`);
+    return lines.join('\n');
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { logger } from './utils/logger.util.js';
+import { Logger } from './utils/logger.util.js';
 import { config } from './utils/config.util.js';
 export declare function startServer(mode?: 'stdio' | 'sse'): Promise<void>;
-export { logger, config };
-export * from './utils/error.util.js';
+export { config };
+export { Logger };

package/dist/index.js

@@ -1,50 +1,39 @@
 #!/usr/bin/env node
 "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 __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.config = exports.logger = void 0;
+exports.Logger = exports.config = void 0;
 exports.startServer = startServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const logger_util_js_1 = require("./utils/logger.util.js");
-Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_util_js_1.logger; } });
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_util_js_1.Logger; } });
 const config_util_js_1 = require("./utils/config.util.js");
 Object.defineProperty(exports, "config", { enumerable: true, get: function () { return config_util_js_1.config; } });
 const error_util_js_1 = require("./utils/error.util.js");
 const index_js_1 = require("./cli/index.js");
 const ipaddress_tool_js_1 = __importDefault(require("./tools/ipaddress.tool.js"));
 const ipaddress_resource_js_1 = __importDefault(require("./resources/ipaddress.resource.js"));
+// Create file-level logger
+const indexLogger = logger_util_js_1.Logger.forContext('index.ts');
 // Define version constant for easier management and consistent versioning
-const VERSION = '1.1.0';
+const VERSION = '1.1.1';
 let serverInstance = null;
 let transportInstance = null;
 async function startServer(mode = 'stdio') {
+    const methodLogger = logger_util_js_1.Logger.forContext('index.ts', 'startServer');
     // Load configuration
     config_util_js_1.config.load();
     // Enable debug logging if DEBUG is set to true
     if (config_util_js_1.config.getBoolean('DEBUG')) {
-        logger_util_js_1.logger.debug('[src/index.ts] Debug mode enabled');
+        methodLogger.debug('Debug mode enabled');
     }
     // Log the DEBUG value to verify configuration loading
-    logger_util_js_1.logger.info(`[src/index.ts] DEBUG value: ${process.env.DEBUG}`);
-    logger_util_js_1.logger.info(`[src/index.ts] IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
-    logger_util_js_1.logger.info(`[src/index.ts] Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
+    methodLogger.info(`DEBUG value: ${process.env.DEBUG}`);
+    methodLogger.info(`IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
+    methodLogger.info(`Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
     serverInstance = new mcp_js_1.McpServer({
         name: '@aashari/boilerplate-mcp-server',
         version: VERSION,
@@ -55,36 +44,45 @@ async function startServer(mode = 'stdio') {
     else {
         throw (0, error_util_js_1.createUnexpectedError)('SSE mode is not supported yet');
     }
-    logger_util_js_1.logger.info(`[src/index.ts] Starting server with ${mode.toUpperCase()} transport...`);
+    methodLogger.info(`Starting server with ${mode.toUpperCase()} transport...`);
     // register tools
     ipaddress_tool_js_1.default.register(serverInstance);
+    methodLogger.debug('Registered IP address tools');
     // register resources
     ipaddress_resource_js_1.default.register(serverInstance);
+    methodLogger.debug('Registered IP lookup resources');
     return serverInstance.connect(transportInstance).catch((err) => {
-        logger_util_js_1.logger.error(`[src/index.ts] Failed to start server`, err);
+        methodLogger.error(`Failed to start server`, err);
         process.exit(1);
     });
 }
 // Main entry point - this will run when executed directly
 async function main() {
+    const methodLogger = logger_util_js_1.Logger.forContext('index.ts', 'main');
     // Load configuration
     config_util_js_1.config.load();
     // Log the DEBUG value to verify configuration loading
-    logger_util_js_1.logger.info(`[src/index.ts] DEBUG value: ${process.env.DEBUG}`);
-    logger_util_js_1.logger.info(`[src/index.ts] IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
-    logger_util_js_1.logger.info(`[src/index.ts] Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
+    methodLogger.info(`DEBUG value: ${process.env.DEBUG}`);
+    methodLogger.info(`IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
+    methodLogger.info(`Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
     // Check if arguments are provided (CLI mode)
     if (process.argv.length > 2) {
         // CLI mode: Pass arguments to CLI runner
+        methodLogger.info('Starting in CLI mode');
         await (0, index_js_1.runCli)(process.argv.slice(2));
+        methodLogger.info('CLI execution completed');
     }
     else {
         // MCP Server mode: Start server with default STDIO
+        methodLogger.info('Starting in server mode');
         await startServer();
+        methodLogger.info('Server is now running');
     }
 }
 // If this file is being executed directly (not imported), run the main function
 if (require.main === module) {
-    main();
+    main().catch((err) => {
+        indexLogger.error('Unhandled error in main process', err);
+        process.exit(1);
+    });
 }
-__exportStar(require("./utils/error.util.js"), exports);

package/dist/index.js.bak

@@ -1,50 +1,39 @@
 #!/usr/bin/env node
 "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 __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.config = exports.logger = void 0;
+exports.Logger = exports.config = void 0;
 exports.startServer = startServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const logger_util_js_1 = require("./utils/logger.util.js");
-Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_util_js_1.logger; } });
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_util_js_1.Logger; } });
 const config_util_js_1 = require("./utils/config.util.js");
 Object.defineProperty(exports, "config", { enumerable: true, get: function () { return config_util_js_1.config; } });
 const error_util_js_1 = require("./utils/error.util.js");
 const index_js_1 = require("./cli/index.js");
 const ipaddress_tool_js_1 = __importDefault(require("./tools/ipaddress.tool.js"));
 const ipaddress_resource_js_1 = __importDefault(require("./resources/ipaddress.resource.js"));
+// Create file-level logger
+const indexLogger = logger_util_js_1.Logger.forContext('index.ts');
 // Define version constant for easier management and consistent versioning
-const VERSION = '1.0.3';
+const VERSION = '1.1.0';
 let serverInstance = null;
 let transportInstance = null;
 async function startServer(mode = 'stdio') {
+    const methodLogger = logger_util_js_1.Logger.forContext('index.ts', 'startServer');
     // Load configuration
     config_util_js_1.config.load();
     // Enable debug logging if DEBUG is set to true
     if (config_util_js_1.config.getBoolean('DEBUG')) {
-        logger_util_js_1.logger.debug('[src/index.ts] Debug mode enabled');
+        methodLogger.debug('Debug mode enabled');
     }
     // Log the DEBUG value to verify configuration loading
-    logger_util_js_1.logger.info(`[src/index.ts] DEBUG value: ${process.env.DEBUG}`);
-    logger_util_js_1.logger.info(`[src/index.ts] IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
-    logger_util_js_1.logger.info(`[src/index.ts] Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
+    methodLogger.info(`DEBUG value: ${process.env.DEBUG}`);
+    methodLogger.info(`IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
+    methodLogger.info(`Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
     serverInstance = new mcp_js_1.McpServer({
         name: '@aashari/boilerplate-mcp-server',
         version: VERSION,
@@ -55,36 +44,45 @@ async function startServer(mode = 'stdio') {
     else {
         throw (0, error_util_js_1.createUnexpectedError)('SSE mode is not supported yet');
     }
-    logger_util_js_1.logger.info(`[src/index.ts] Starting server with ${mode.toUpperCase()} transport...`);
+    methodLogger.info(`Starting server with ${mode.toUpperCase()} transport...`);
     // register tools
     ipaddress_tool_js_1.default.register(serverInstance);
+    methodLogger.debug('Registered IP address tools');
     // register resources
     ipaddress_resource_js_1.default.register(serverInstance);
+    methodLogger.debug('Registered IP lookup resources');
     return serverInstance.connect(transportInstance).catch((err) => {
-        logger_util_js_1.logger.error(`[src/index.ts] Failed to start server`, err);
+        methodLogger.error(`Failed to start server`, err);
         process.exit(1);
     });
 }
 // Main entry point - this will run when executed directly
 async function main() {
+    const methodLogger = logger_util_js_1.Logger.forContext('index.ts', 'main');
     // Load configuration
     config_util_js_1.config.load();
     // Log the DEBUG value to verify configuration loading
-    logger_util_js_1.logger.info(`[src/index.ts] DEBUG value: ${process.env.DEBUG}`);
-    logger_util_js_1.logger.info(`[src/index.ts] IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
-    logger_util_js_1.logger.info(`[src/index.ts] Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
+    methodLogger.info(`DEBUG value: ${process.env.DEBUG}`);
+    methodLogger.info(`IPAPI_API_TOKEN value exists: ${Boolean(process.env.IPAPI_API_TOKEN)}`);
+    methodLogger.info(`Config DEBUG value: ${config_util_js_1.config.get('DEBUG')}`);
     // Check if arguments are provided (CLI mode)
     if (process.argv.length > 2) {
         // CLI mode: Pass arguments to CLI runner
+        methodLogger.info('Starting in CLI mode');
         await (0, index_js_1.runCli)(process.argv.slice(2));
+        methodLogger.info('CLI execution completed');
     }
     else {
         // MCP Server mode: Start server with default STDIO
+        methodLogger.info('Starting in server mode');
         await startServer();
+        methodLogger.info('Server is now running');
     }
 }
 // If this file is being executed directly (not imported), run the main function
 if (require.main === module) {
-    main();
+    main().catch((err) => {
+        indexLogger.error('Unhandled error in main process', err);
+        process.exit(1);
+    });
 }
-__exportStar(require("./utils/error.util.js"), exports);

package/dist/resources/ipaddress.resource.js

@@ -11,12 +11,16 @@ const ipaddress_controller_js_1 = __importDefault(require("../controllers/ipaddr
  * @param server The MCP server instance
  */
 function register(server) {
-    logger_util_js_1.logger.debug(`[src/resources/iplookup.resource.ts@register] Registering IP lookup resources...`);
+    const methodLogger = logger_util_js_1.Logger.forContext('resources/ipaddress.resource.ts', 'register');
+    methodLogger.debug(`Registering IP lookup resources...`);
     server.resource('Current Device IP', 'ip://current', {
         description: 'Details about your current IP address',
     }, async (_uri, _extra) => {
+        const resourceMethodLogger = logger_util_js_1.Logger.forContext('resources/ipaddress.resource.ts', 'resourceHandler');
         try {
+            resourceMethodLogger.debug('Handling request for current IP details');
             const resourceContent = await ipaddress_controller_js_1.default.get();
+            resourceMethodLogger.debug('Successfully retrieved IP details');
             return {
                 contents: [
                     {
@@ -29,7 +33,7 @@ function register(server) {
             };
         }
         catch (error) {
-            logger_util_js_1.logger.error(`[src/resources/ipaddress.resource.ts] Error getting IP details`, error);
+            resourceMethodLogger.error(`Error getting IP details`, error);
             return (0, error_util_js_1.formatErrorForMcpResource)(error, 'ip://current');
         }
     });

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

@@ -1,43 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const logger_util_js_1 = require("../utils/logger.util.js");
-const config_util_js_1 = require("../utils/config.util.js");
 const error_util_js_1 = require("../utils/error.util.js");
-const ENDPOINT = 'http://ip-api.com/json';
+const transport_util_js_1 = require("../utils/transport.util.js");
+// Create a contextualized logger for this file
+const serviceLogger = logger_util_js_1.Logger.forContext('services/vendor.ip-api.com.service.ts');
+// Log service initialization
+serviceLogger.debug('IP API service initialized');
 async function get(ipAddress) {
-    logger_util_js_1.logger.debug(`[src/services/vendor.ip-api.com.ts@get] Calling the API...`);
-    // Get API token from configuration
-    const apiToken = config_util_js_1.config.get('IPAPI_API_TOKEN');
-    // Build URL with token if available
-    let url = `${ENDPOINT}/${ipAddress ?? ''}`;
-    if (apiToken) {
-        url += `?key=${apiToken}`;
-        logger_util_js_1.logger.debug(`[src/services/vendor.ip-api.com.ts@get] Using API token`);
-    }
+    const methodLogger = logger_util_js_1.Logger.forContext('services/vendor.ip-api.com.service.ts', 'get');
+    methodLogger.debug(`Calling IP API for IP: ${ipAddress || 'current'}`);
     try {
-        const response = await fetch(url);
-        // Handle HTTP errors
-        if (!response.ok) {
-            throw (0, error_util_js_1.createApiError)(`IP API request failed: ${response.status} ${response.statusText}`, response.status);
-        }
-        const data = (await response.json());
-        // Handle API-level errors
+        // Use the centralized fetchIpApi utility
+        // Explicitly type the expected response structure
+        const data = await (0, transport_util_js_1.fetchIpApi)(ipAddress || '');
+        // Handle API-level success/failure specific to ip-api.com
         if (data.status !== 'success') {
             throw (0, error_util_js_1.createApiError)(`IP API error: ${data.message || 'Unknown error'}`);
         }
-        return data;
+        methodLogger.debug(`Received successful data from IP API`);
+        return data; // Already validated as IPDetail structure implicitly by status check
     }
     catch (error) {
-        // Rethrow McpErrors
+        // Log the error caught at the service level
+        methodLogger.error(`Service error fetching IP data`, error);
+        // Rethrow McpErrors (could be from fetchApi or the status check)
         if (error instanceof error_util_js_1.McpError) {
             throw error;
         }
-        // Handle fetch errors
-        if (error instanceof TypeError) {
-            throw (0, error_util_js_1.createApiError)('Network error while contacting IP API', undefined, error);
-        }
-        // Handle unexpected errors
-        throw (0, error_util_js_1.createUnexpectedError)('Unexpected error while fetching IP data', error);
+        // Wrap any other unexpected errors
+        throw (0, error_util_js_1.createUnexpectedError)('Unexpected service error while fetching IP data', error);
     }
 }
 exports.default = { get };

package/dist/tools/ipaddress.tool.js

@@ -8,10 +8,11 @@ const ipaddress_type_js_1 = require("./ipaddress.type.js");
 const error_util_js_1 = require("../utils/error.util.js");
 const ipaddress_controller_js_1 = __importDefault(require("../controllers/ipaddress.controller.js"));
 async function getIpAddressDetails(args, _extra) {
-    logger_util_js_1.logger.debug(`[src/tools/ipaddress.tool.ts@getIpAddressDetails] Getting IP address details...`);
+    const methodLogger = logger_util_js_1.Logger.forContext('tools/ipaddress.tool.ts', 'getIpAddressDetails');
+    methodLogger.debug(`Getting IP address details...`);
     try {
         const message = await ipaddress_controller_js_1.default.get(args.ipAddress);
-        logger_util_js_1.logger.debug(`[src/tools/ipaddress.tool.ts@getIpAddressDetails] Got the response from the controller`, message);
+        methodLogger.debug(`Got the response from the controller`, message);
         return {
             content: [
                 {
@@ -22,12 +23,36 @@ async function getIpAddressDetails(args, _extra) {
         };
     }
     catch (error) {
-        logger_util_js_1.logger.error(`[src/tools/ipaddress.tool.ts@getIpAddressDetails] Error getting details for IP: ${args.ipAddress || 'current IP'}`, error);
+        methodLogger.error(`Error getting details for IP: ${args.ipAddress || 'current IP'}`, error);
         return (0, error_util_js_1.formatErrorForMcpTool)(error);
     }
 }
 function register(server) {
-    logger_util_js_1.logger.debug(`[src/tools/ipaddress.ts@register] Registering tools...`);
-    server.tool('get-ip-details', 'Get details about a specific IP address or the current device (if no IP address is provided)', ipaddress_type_js_1.IpAddressToolArgs.shape, getIpAddressDetails);
+    const methodLogger = logger_util_js_1.Logger.forContext('tools/ipaddress.tool.ts', 'register');
+    methodLogger.debug(`Registering tools...`);
+    server.tool('get-ip-details', `Get details about a specific IP address or the current device's public IP address.
+
+            PURPOSE: Retrieves geolocation information (country, city, region, coordinates), ISP, and organization details associated with an IP address.
+
+            WHEN TO USE:
+            - To find the geographical location of a given IP address.
+            - To identify the ISP or organization owning an IP address.
+            - To get your own public IP address details (by omitting the 'ipAddress' argument).
+
+            WHEN NOT TO USE:
+            - For internal/private IP addresses (this tool queries a public database).
+            - When you need historical IP data (this provides current lookup).
+            - For operations other than retrieving IP geolocation details.
+
+            RETURNS: Formatted Markdown containing details such as country, city, region, latitude, longitude, ISP, organization, and the queried IP itself.
+
+            EXAMPLES:
+            - Get details for a specific IP: { ipAddress: "8.8.8.8" }
+            - Get details for the current device's IP: {}
+
+            ERRORS:
+            - Invalid IP format: If the provided 'ipAddress' is not a valid IP.
+            - Private/Reserved IP: If the IP address is in a private range.
+            - API errors: If the external ip-api.com service fails.`, ipaddress_type_js_1.IpAddressToolArgs.shape, getIpAddressDetails);
 }
 exports.default = { register };