@aashari/boilerplate-mcp-server 1.1.0 → 1.1.2

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,20 @@
+## [1.1.2](https://github.com/aashari/boilerplate-mcp-server/compare/v1.1.1...v1.1.2) (2025-03-28)
+
+
+### Performance Improvements
+
+* **ipaddress:** enhance formatter output and optimize service implementation ([f1ccdbf](https://github.com/aashari/boilerplate-mcp-server/commit/f1ccdbf58cb2518ca979363369904255e5de275b))
+
+## [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/README.md

@@ -1,215 +1,199 @@
 # Boilerplate MCP Server
 
-## About
+This project provides a Model Context Protocol (MCP) server template that serves as a starting point for building your own connections between AI assistants (like Anthropic's Claude, Cursor AI, or other MCP-compatible clients) and external data sources or APIs. It includes a working IP lookup tool example to demonstrate the pattern.
 
-This project is a customizable Model Context Protocol (MCP) server written in TypeScript, designed to extend AI assistants like Claude or Cursor with external tools and data sources. MCP is an open-source protocol by Anthropic for connecting AI systems to external capabilities securely and efficiently. For more details on MCP, see [https://modelcontextprotocol.io/docs/](https://modelcontextprotocol.io/docs/). This boilerplate provides a starting point with an IP lookup tool, CLI support, and a flexible architecture for adding your own features.
+## What is MCP and Why Use This Template?
 
-## Project Features
+Model Context Protocol (MCP) is an open standard enabling AI models to connect securely to external tools and data sources. This server implements the MCP standard with a flexible architecture for building custom tools.
 
-- **MCP Server**: Exposes tools and resources to AI clients (e.g., Claude Desktop, Cursor AI) via STDIO or HTTP.
-- **IP Address Lookup**: Includes an example tool (`get-ip-details`) for fetching IP details, configurable with [ipapi.co](https://ipapi.co).
-- **CLI Support**: Run tools directly from the command line without an AI client.
-- **Flexible Configuration**: Supports direct environment variables for quick use or a global config file at `$HOME/.mcp/configs.json` for managing multiple servers.
-- **Development Tools**: Built-in MCP Inspector for debugging, plus testing and linting utilities.
+**Benefits:**
 
-### Available Tools
+- **Quick Start:** Begin with a fully-functional MCP server structure including CLI support.
+- **Proven Patterns:** Follow established architecture patterns used in production MCP servers.
+- **Complete Example:** Includes a working IP lookup tool demonstrating the full pattern from CLI to API.
+- **Modern TypeScript:** Built with TypeScript and modern Node.js practices for type safety and maintainability.
+- **Testing Support:** Includes test infrastructure for both unit and CLI integration tests.
 
-- **`get-ip-details`**: Get information about an IP address or the current device's IP.
+## Available Tools
 
-## User Guide
+This MCP server provides the following example tool for your AI assistant:
 
-### Configuration Options
+- **Get IP Address Details (`get-ip-details`)**
 
-- **DEBUG**: Set to `true` for detailed logging (default: `false`).
-- **IPAPI_API_TOKEN**: Optional API token for [ipapi.co](https://ipapi.co) to enhance IP lookups (basic lookups work without it).
+    - **Purpose:** Retrieves geolocation information (country, city, region, coordinates), ISP, and organization details associated with an IP address.
+    - **Use When:** You need to find the geographical location of a given IP address, identify the ISP/organization owning an IP, or get your own public IP details.
+    - **Conversational Example:** "What's my public IP and where is it located?" or "Look up the location of IP 8.8.8.8"
+    - **Parameter Example:** `{}` (no parameters for current device IP) or `{ ipAddress: "8.8.8.8" }` (specific IP)
 
-#### Method 1: Environment Variables
+## Interface Philosophy: Simple Input, Rich Output
 
-Pass configs directly when running:
+This server follows a "Minimal Interface, Maximal Detail" approach:
 
-```bash
-DEBUG=true IPAPI_API_TOKEN=your_token npx -y @aashari/boilerplate-mcp-server
-```
+1. **Simple Tools:** Ask for only essential identifiers or parameters (like `ipAddress`).
+2. **Rich Details:** Provides comprehensive information in a well-formatted Markdown response.
 
-#### Method 2: Global Config File (Recommended)
+## Prerequisites
 
-Create `$HOME/.mcp/configs.json`:
+- **Node.js and npm:** Ensure you have Node.js (which includes npm) installed. Download from [nodejs.org](https://nodejs.org/).
+- **IP API Token (Optional):** For enhanced IP lookup capabilities, you can obtain a token from [ip-api.com](https://ip-api.com/) (basic lookups work without a token).
 
-```json
-{
-	"@aashari/boilerplate-mcp-server": {
-		"environments": {
-			"DEBUG": "true",
-			"IPAPI_API_TOKEN": "your_token"
-		}
-	}
-}
-```
+## Quick Start Guide
 
-You can also configure multiple MCP servers in the same file:
-
-```json
-{
-	"@aashari/boilerplate-mcp-server": {
-		"environments": {
-			"DEBUG": "true",
-			"IPAPI_API_TOKEN": "your_token"
-		}
-	},
-	"@aashari/mcp-server-atlassian-confluence": {
-		"environments": {
-			"DEBUG": "true",
-			"ATLASSIAN_SITE_NAME": "your-instance",
-			"ATLASSIAN_USER_EMAIL": "your-email@example.com",
-			"ATLASSIAN_API_TOKEN": "your_api_token"
-		}
-	},
-	"@aashari/mcp-server-atlassian-jira": {
-		"environments": {
-			"DEBUG": "true",
-			"ATLASSIAN_SITE_NAME": "your-instance",
-			"ATLASSIAN_USER_EMAIL": "your-email@example.com",
-			"ATLASSIAN_API_TOKEN": "your_api_token"
-		}
-	}
-}
-```
+Follow these steps to connect your AI assistant to this boilerplate server:
+
+### Step 1: Configure the Server (Optional)
+
+The server works without configuration, but for enhanced options:
 
-### Using with Claude Desktop
-
-1. **Open Settings**:
-    - Launch Claude Desktop, click the gear icon (top-right).
-2. **Edit Config**:
-    - Click "Edit Config" to open `claude_desktop_config.json` (e.g., `~/Library/Application Support/Claude` on macOS or `%APPDATA%\Claude` on Windows).
-3. **Add Server**:
-    - Use the global config file (recommended):
-        ```json
-        {
-        	"mcpServers": {
-        		"aashari/boilerplate-mcp-server": {
-        			"command": "npx",
-        			"args": ["-y", "@aashari/boilerplate-mcp-server"]
-        		}
-        	}
-        }
-        ```
-    - Or configure directly:
-        ```json
-        {
-        	"mcpServers": {
-        		"aashari/boilerplate-mcp-server": {
-        			"command": "npx",
-        			"args": [
-        				"-y",
-        				"DEBUG=true",
-        				"IPAPI_API_TOKEN=your_token",
-        				"@aashari/boilerplate-mcp-server"
-        			]
-        		}
-        	}
-        }
-        ```
-4. **Restart**: Close and reopen Claude Desktop.
-5. **Test**: Click the hammer icon, verify `get-ip-details` is listed, then ask: "What's my public IP?" or "Get details for IP 8.8.8.8".
-
-### Using with Cursor AI
-
-1. **Open Settings**:
-    - Launch Cursor, press `CMD + SHIFT + P` (or `CTRL + SHIFT + P`), select "Cursor Settings" > "MCP".
-2. **Add Server**:
-    - Click "+ Add new MCP server".
-    - **Name**: `aashari/boilerplate-mcp-server`.
-    - **Type**: `command`.
-    - **Command**:
-        - Global config: `npx -y @aashari/boilerplate-mcp-server`.
-        - Direct: `DEBUG=true IPAPI_API_TOKEN=your_token npx -y @aashari/boilerplate-mcp-server`.
-    - Click "Add".
-3. **Verify**: Check for a green indicator and `get-ip-details` tool listed.
-4. **Test**: In Agent mode, ask: "What's my public IP?" or "Get information about IP 8.8.8.8".
-
-### Using as a CLI Tool
-
-Run without installation:
+#### Method A: Global MCP Config File (Recommended)
+
+This keeps configurations separate and organized.
+
+1. **Create the directory** (if needed): `~/.mcp/`
+2. **Create/Edit the file:** `~/.mcp/configs.json`
+3. **Add the configuration:** Paste the following JSON structure, replacing the placeholders:
+
+    ```json
+    {
+    	"@aashari/boilerplate-mcp-server": {
+    		"environments": {
+    			"DEBUG": "true",
+    			"IPAPI_API_TOKEN": "<YOUR_OPTIONAL_IP_API_TOKEN>"
+    		}
+    	}
+    	// Add other servers here if needed
+    }
+    ```
+
+#### Method B: Environment Variables (Alternative)
+
+Set environment variables when running the server.
 
 ```bash
-# Help
-npx -y @aashari/boilerplate-mcp-server -- --help
-# Current IP
-npx -y @aashari/boilerplate-mcp-server -- get-ip-details
-# Specific IP
-npx -y @aashari/boilerplate-mcp-server -- get-ip-details 8.8.8.8
+DEBUG=true IPAPI_API_TOKEN="<YOUR_OPTIONAL_TOKEN>" npx -y @aashari/boilerplate-mcp-server
 ```
 
-Or install globally:
+### Step 2: Connect Your AI Assistant
+
+Configure your MCP client (Claude Desktop, Cursor, etc.) to run this server.
+
+#### Claude Desktop
+
+1. Open Settings (gear icon) > Edit Config.
+2. Add or merge into `mcpServers`:
+
+    ```json
+    {
+    	"mcpServers": {
+    		"aashari/boilerplate-mcp-server": {
+    			"command": "npx",
+    			"args": ["-y", "@aashari/boilerplate-mcp-server"]
+    		}
+    		// ... other servers
+    	}
+    }
+    ```
+
+3. Save and **Restart Claude Desktop**.
+4. **Verify:** Click the "Tools" (hammer) icon; the IP lookup tool should be listed.
+
+#### Cursor AI
+
+1. Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) > **Cursor Settings > MCP**.
+2. Click **+ Add new MCP server**.
+3. Enter:
+    - Name: `aashari/boilerplate-mcp-server`
+    - Type: `command`
+    - Command: `npx -y @aashari/boilerplate-mcp-server`
+4. Click **Add**.
+5. **Verify:** Wait for the indicator next to the server name to turn green.
+
+### Step 3: Using the Tools
+
+You can now ask your AI assistant IP-related questions:
+
+- "What's my public IP address and where is it located?"
+- "Can you get details for IP 8.8.8.8?"
+- "Look up the geolocation of 1.1.1.1"
+
+## Using as a Command-Line Tool (CLI)
+
+You can also use this package directly from your terminal:
+
+#### Quick Use with `npx`
 
 ```bash
-npm install -g @aashari/boilerplate-mcp-server
+npx -y @aashari/boilerplate-mcp-server get-ip-details
+npx -y @aashari/boilerplate-mcp-server get-ip-details 8.8.8.8
+npx -y @aashari/boilerplate-mcp-server --help
 ```
 
-Then run:
+#### Global Installation (Optional)
+
+1. `npm install -g @aashari/boilerplate-mcp-server`
+2. Use the `mcp-server` command:
 
 ```bash
-# Help
-mcp-server --help
-# Current IP
 mcp-server get-ip-details
-# Specific IP
 mcp-server get-ip-details 8.8.8.8
+mcp-server --help # See all commands
 ```
 
-Use the global config file or prefix with environment variables:
+## Extending the Project
 
-```bash
-DEBUG=true IPAPI_API_TOKEN=your_token mcp-server get-ip-details
-```
+This boilerplate is designed to be extended with your own custom tools:
 
-## Developer Guide
+### Architecture Overview
 
-### Development Scripts
+The project follows a clean layered architecture:
 
-The project includes several scripts for development and production use:
+- **CLI / Tool Layer** (`src/cli/*.cli.ts`, `src/tools/*.tool.ts`): User interfaces
+- **Controller Layer** (`src/controllers/*.controller.ts`): Business logic
+- **Service Layer** (`src/services/*.service.ts`): External API interactions
+- **Utils** (`src/utils/*.util.ts`): Shared functionality
 
-- **`npm run dev:server`**: Run the server in development mode with MCP Inspector and debug logging.
-- **`npm run dev:cli`**: Run CLI commands in development mode with debug logging.
-- **`npm run start:server`**: Run the server in production mode with MCP Inspector.
-- **`npm run start:cli`**: Run CLI commands in production mode.
+### Adding Your Own Tools
 
-Example usage:
+1. **Create a Service** in `src/services/` to interact with your API or data source.
+2. **Add a Controller** in `src/controllers/` with business logic and type definitions.
+3. **Implement a Tool** in `src/tools/` that defines the MCP tool interface.
+4. **Add CLI Support** in `src/cli/` to enable command-line use.
+5. **Register** your new tool in `src/index.ts`.
+
+## Developer Guide
+
+### Development Scripts
 
 ```bash
-# Start the server with Inspector and debug logging
+# Start server in development mode (with Inspector & debug logs)
 npm run dev:server
 
-# Run a CLI command with debug logging
+# Run CLI in development mode
 npm run dev:cli -- get-ip-details 8.8.8.8
 
-# Start the server with Inspector (no debug)
+# Production mode (server with Inspector)
 npm run start:server
 
-# Run a CLI command (no debug)
-npm run start:cli -- get-ip-details 8.8.8.8
+# Production mode (CLI command)
+npm run start:cli -- get-ip-details
 ```
 
-### Extending the Project
-
-To add custom tools or resources:
-
-1. **Services**: Add API/data logic in `src/services`.
-2. **Controllers**: Implement business logic in `src/controllers`.
-3. **Tools**: Define new tools in `src/tools`.
-4. **Resources**: Add data sources in `src/resources`.
-5. **Register**: Update `src/index.ts` with your tools/resources.
-
-### Additional Development Tools
+### Testing and Quality Tools
 
 ```bash
-# Run tests
+# Run all tests
 npm test
-# Test coverage
+
+# Run specific CLI tests
+npm test -- src/cli/ipaddress.cli.test.ts
+
+# Generate test coverage report
 npm run test:coverage
-# Lint
+
+# Lint code
 npm run lint
-# Format
+
+# Format code
 npm run format
 ```
 
@@ -217,9 +201,30 @@ npm run format
 
 The MCP Inspector provides a visual interface for debugging and testing your MCP server:
 
-1. The Inspector starts your MCP server.
-2. It launches a web UI (typically at `http://localhost:5173`).
-3. Use the UI to test tools, view requests/responses, and check errors.
+1. Run `npm run dev:server` or `npm run start:server`
+2. The Inspector launches a web UI (typically at `http://localhost:5173`)
+3. Use the UI to test tools, view requests/responses, and check errors
+
+## Troubleshooting
+
+- **Server Not Connecting (in AI Client):**
+    - Confirm the command (`npx ...`) in your client's config is correct
+    - Check Node.js/npm installation and PATH
+    - Run the `npx` command directly in your terminal for errors
+- **IP API Errors:**
+    - Basic lookups should work without configuration
+    - If using a token, verify `IPAPI_API_TOKEN` is set correctly
+    - Some IP ranges (private IPs like 192.168.x.x) may not return results
+- **Enable Debug Logs:** Set `DEBUG=true` environment variable for verbose logging
+
+## For Developers: Contributing
+
+Contributions are welcome! If you'd like to contribute:
+
+- **Setup:** Clone repo, `npm install`. Use `npm run dev:server` or `npm run dev:cli -- <command>`.
+- **Code Style:** Use `npm run lint` and `npm run format`.
+- **Tests:** Add tests via `npm test`.
+- **Consistency:** Follow existing patterns and the "Minimal Interface, Maximal Detail" philosophy.
 
 ## License
 

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.2'; // 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

@@ -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.0.1'; // 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/ipaddress.cli.js

@@ -11,16 +11,36 @@ 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) => {
+        .description(`Get geolocation and network details about an IP address or the current device.
+
+        PURPOSE: Retrieve comprehensive information about an IP address including geographical location, ISP, organization, and network details.
+        
+        Use Case: Useful for identifying the location of an IP address, determining network ownership, or checking your own public IP information.
+        
+        Output: Formatted Markdown containing location data (country, region, city), network information (ISP, organization, AS number), coordinates, and a link to view the location on a map.
+        
+        Examples:
+  $ mcp-ipaddress get-ip-details
+  $ mcp-ipaddress get-ip-details 8.8.8.8
+  $ mcp-ipaddress get-ip-details 1.1.1.1`)
+        .argument('[ipAddress]', 'IP address to lookup (optional, omit for current device)')
+        .option('--extended', 'Include extended data like ASN, mobile and proxy detection')
+        .option('--https', 'Use HTTPS for API requests (may require paid API key)')
+        .action(async (ipAddress, cmdOptions) => {
+        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'}...`);
-            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(`Fetching IP details for ${ipAddress || 'current device'}...`, cmdOptions);
+            // Map CLI options to controller options
+            const controllerOptions = {
+                includeExtendedData: cmdOptions?.extended || false,
+                useHttps: cmdOptions?.https || false,
+            };
+            const result = await ipaddress_controller_js_1.default.get(ipAddress, controllerOptions);
+            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,12 @@
-declare function get(ipAddress?: string): Promise<{
-    content: string;
-}>;
+import { ControllerResponse } from '../types/common.types.js';
+import { GetIpOptions } from './ipaddress.types.js';
+/**
+ * Get IP address details from the IP API.
+ * @param ipAddress Optional IP address to lookup (omit for current IP)
+ * @param options Optional configuration for the request
+ * @returns Controller response with formatted content
+ */
+declare function get(ipAddress?: string, options?: GetIpOptions): Promise<ControllerResponse>;
 declare const _default: {
     get: typeof get;
 };

package/dist/controllers/ipaddress.controller.js

@@ -5,29 +5,72 @@ 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");
-async function get(ipAddress) {
-    logger_util_js_1.logger.debug(`[src/controllers/ipaddress.controller.ts@get] Getting IP address details...`);
+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");
+/**
+ * Get IP address details from the IP API.
+ * @param ipAddress Optional IP address to lookup (omit for current IP)
+ * @param options Optional configuration for the request
+ * @returns Controller response with formatted content
+ */
+async function get(ipAddress, options = {}) {
+    const methodLogger = logger_util_js_1.Logger.forContext('controllers/ipaddress.controller.ts', 'get');
+    methodLogger.debug(`Getting IP address details for ${ipAddress || 'current device'}...`);
     try {
-        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'),
+        // Define controller defaults
+        const defaults = {
+            includeExtendedData: false,
+            useHttps: false,
+        };
+        // Apply defaults to provided options
+        const mergedOptions = (0, defaults_util_js_1.applyDefaults)(options, defaults);
+        methodLogger.debug('Using options after defaults:', mergedOptions);
+        // Map controller options to service options
+        const serviceOptions = {
+            useHttps: mergedOptions.useHttps,
         };
+        // If extended data is requested, include additional fields
+        if (mergedOptions.includeExtendedData) {
+            serviceOptions.fields = [
+                'status',
+                'message',
+                'country',
+                'countryCode',
+                'region',
+                'regionName',
+                'city',
+                'zip',
+                'lat',
+                'lon',
+                'timezone',
+                'isp',
+                'org',
+                'as',
+                'asname',
+                'reverse',
+                'mobile',
+                'proxy',
+                'hosting',
+                'query',
+            ];
+        }
+        // Call the service with the mapped options
+        const ipData = await vendor_ip_api_com_service_js_1.default.get(ipAddress, serviceOptions);
+        methodLogger.debug(`Got the response from the service`, ipData);
+        // Format the data using the formatter
+        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 with return
+        return (0, error_handler_util_js_1.handleControllerError)(error, {
+            entityType: 'IP Address Details',
+            operation: 'retrieving',
+            source: 'controllers/ipaddress.controller.ts@get',
+            additionalInfo: { ipAddress },
+        });
     }
 }
 exports.default = { get };

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

@@ -0,0 +1,7 @@
+import { IPDetail } from '../services/vendor.ip-api.com.types.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;