@aashari/boilerplate-mcp-server 3.0.0 → 3.2.0

package/.releaserc.json

@@ -1,5 +1,7 @@
 {
-	"branches": ["main"],
+	"branches": [
+		"main"
+	],
 	"plugins": [
 		"@semantic-release/commit-analyzer",
 		"@semantic-release/release-notes-generator",
@@ -24,7 +26,8 @@
 					"package.json",
 					"CHANGELOG.md",
 					"src/index.ts",
-					"src/cli/index.ts"
+					"src/cli/index.ts",
+					"src/utils/constants.util.ts"
 				],
 				"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
 			}

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [3.2.0](https://github.com/aashari/boilerplate-mcp-server/compare/v3.1.0...v3.2.0) (2026-02-17)
+
+
+### Features
+
+* harden HTTP transport security and add tool annotations ([5919f9f](https://github.com/aashari/boilerplate-mcp-server/commit/5919f9f4c1e416da1a6f5c9ce01174a56624ba90))
+
+# [3.1.0](https://github.com/aashari/boilerplate-mcp-server/compare/v3.0.0...v3.1.0) (2026-02-17)
+
+
+### Features
+
+* modernize HTTP transport and standardize MCP tool contracts ([615b373](https://github.com/aashari/boilerplate-mcp-server/commit/615b3732c10ad2c607a899de0f6632221b6f7bc3))
+
 # [3.0.0](https://github.com/aashari/boilerplate-mcp-server/compare/v2.0.0...v3.0.0) (2026-02-04)
 
 

package/README.md

@@ -5,7 +5,7 @@ A production-ready foundation for developing custom Model Context Protocol (MCP)
 [![NPM Version](https://img.shields.io/npm/v/@aashari/boilerplate-mcp-server)](https://www.npmjs.com/package/@aashari/boilerplate-mcp-server)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
-> **Latest Update (Feb 2026)**: Updated to MCP SDK 1.25.3 and Zod 4.3.6 with new features like `z.fromJSONSchema()`, `z.xor()`, and improved validation. See [docs/MODERNIZATION.md](docs/MODERNIZATION.md) for details.
+> **Latest Update (Feb 2026)**: Updated to MCP SDK 1.26.0 and Zod 4.3.6 with continued modern `registerTool` patterns and streamable HTTP improvements. See [docs/MODERNIZATION.md](docs/MODERNIZATION.md) for details.
 
 ## Features
 
@@ -18,7 +18,7 @@ A production-ready foundation for developing custom Model Context Protocol (MCP)
 - **TOON Output Format**: Token-Oriented Object Notation for 30-60% fewer tokens than JSON
 - **JMESPath Filtering**: Extract only needed fields from responses to reduce token costs
 - **Raw Response Logging**: Automatic logging of large API responses to `/tmp/mcp/<project>/` with truncation guidance
-- **Modern SDK**: Uses MCP SDK v1.25.3 with `registerTool` API pattern (ready for v2 migration)
+- **Modern SDK**: Uses MCP SDK v1.26.0 with `registerTool` API pattern (ready for v2 migration)
 - **Complete IP Address Example**: Tools, resources, prompts, and CLI commands for IP geolocation
 - **Comprehensive Testing**: Unit and integration tests with coverage reporting (47 tests passing)
 - **Production Tooling**: ESLint, Prettier, semantic-release, and MCP Inspector integration
@@ -31,7 +31,7 @@ Model Context Protocol (MCP) is an open standard for securely connecting AI syst
 
 ## Prerequisites
 
-- **Node.js** (>=18.x): [Download](https://nodejs.org/)
+- **Node.js** (>=20.x): [Download](https://nodejs.org/)
 - **Git**: For version control
 
 ## Quick Start
@@ -263,10 +263,6 @@ npm run mcp:stdio           # STDIO transport for AI assistants
 npm run mcp:http            # HTTP transport on port 3000
 npm run mcp:inspect         # HTTP + auto-open MCP Inspector
 
-# Development with Debugging
-npm run dev:stdio           # STDIO with MCP Inspector integration
-npm run dev:http            # HTTP with debug logging enabled
-
 # Testing
 npm test                    # Run all tests (Jest)
 npm run test:coverage       # Generate coverage report
@@ -275,7 +271,6 @@ npm run test:cli            # Run CLI-specific tests
 # Code Quality
 npm run lint                # ESLint with TypeScript rules
 npm run format              # Prettier formatting
-npm run update:deps         # Update dependencies
 ```
 
 ### Environment Variables
@@ -665,12 +660,18 @@ npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}"  # JM
 
 **MCP Tools:**
 - `ip_get_details` - IP geolocation lookup for AI assistants
-  - Parameters:
-    - `ipAddress` (optional): IP address to lookup (omit for current device's public IP)
-    - `includeExtendedData` (optional, default: `false`): Include ASN, host, organization data (requires API token)
-    - `useHttps` (optional, default: `true`): Use HTTPS for API calls
-    - `jq` (optional): JMESPath expression to filter/transform response
-    - `outputFormat` (optional, default: `"toon"`): Output format - "toon" or "json"
+- `ip_get_details_link` - Same lookup + resource link output for resource-aware clients
+
+Both tools share the same parameters:
+- `ipAddress` (optional): IP address to lookup (omit for current device's public IP)
+- `includeExtendedData` (optional, default: `false`): Include ASN, host, organization data (requires API token)
+- `useHttps` (optional, default: `true`): Use HTTPS for API calls
+- `jq` (optional): JMESPath expression to filter/transform response
+- `outputFormat` (optional, default: `"toon"`): Output format - "toon" or "json"
+
+Output behavior:
+- `ip_get_details`: returns one `text` content block
+- `ip_get_details_link`: returns the same first `text` block plus a `resource_link` block (`ip://<resolved-ip>`)
 
 **MCP Resources:**
 - `ip://{ipAddress}` - IP details resource template (e.g., `ip://8.8.8.8`, `ip://1.1.1.1`)
@@ -718,7 +719,7 @@ PORT=3001                    # Custom port
    npm run cli -- your-command
    npm run mcp:stdio    # Test with MCP Inspector
    ```
-4. **Publish:** `npm publish` (requires npm login)
+4. **Release:** Push conventional commits to `main` and let semantic-release publish automatically via GitHub Actions (OIDC trusted publishing).
 
 ## Testing Strategy
 

package/SECURITY.md

@@ -322,8 +322,8 @@ logger.warn('Failed authentication attempt', {
 ### 5. Regular Updates
 Keep dependencies up-to-date:
 ```bash
-npm run update:check
-npm run update:deps
+npm outdated
+npx npm-check-updates
 ```
 
 ---

package/dist/controllers/ipaddress.controller.js

@@ -110,7 +110,8 @@ 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, rawResponsePath };
+        // Expose canonical resolved IP so callers do not need to parse rendered output
+        return { content, rawResponsePath, resolvedIp: data.query };
     }
     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/index.js

@@ -5,9 +5,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startServer = startServer;
+const node_crypto_1 = require("node:crypto");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const logger_util_js_1 = require("./utils/logger.util.js");
 const config_util_js_1 = require("./utils/config.util.js");
 const constants_util_js_1 = require("./utils/constants.util.js");
@@ -22,6 +24,29 @@ const analysis_prompt_js_1 = __importDefault(require("./prompts/analysis.prompt.
 const logger = logger_util_js_1.Logger.forContext('index.ts');
 let serverInstance = null;
 let transportInstance = null;
+let httpServerInstance = null;
+const httpSessions = new Map();
+function createMcpServer() {
+    const server = new mcp_js_1.McpServer({
+        name: constants_util_js_1.PACKAGE_NAME,
+        version: constants_util_js_1.VERSION,
+    });
+    ipaddress_tool_js_1.default.registerTools(server);
+    ipaddress_link_tool_js_1.default.registerTools(server);
+    ipaddress_resource_js_1.default.registerResources(server);
+    analysis_prompt_js_1.default.registerPrompts(server);
+    return server;
+}
+function getSessionId(req) {
+    const rawSessionId = req.headers['mcp-session-id'];
+    if (Array.isArray(rawSessionId)) {
+        return rawSessionId[0] ?? null;
+    }
+    if (typeof rawSessionId === 'string' && rawSessionId.length > 0) {
+        return rawSessionId;
+    }
+    return null;
+}
 /**
  * Start the MCP server with the specified transport mode
  */
@@ -34,19 +59,11 @@ async function startServer(mode = 'stdio') {
     if (config_util_js_1.config.getBoolean('DEBUG')) {
         serverLogger.debug('Debug mode enabled');
     }
-    serverLogger.info(`Initializing Boilerplate MCP server v${constants_util_js_1.VERSION}`);
-    serverInstance = new mcp_js_1.McpServer({
-        name: constants_util_js_1.PACKAGE_NAME,
-        version: constants_util_js_1.VERSION,
-    });
-    // Register tools, resources, and prompts
-    serverLogger.info('Registering MCP tools, resources, and prompts...');
-    ipaddress_tool_js_1.default.registerTools(serverInstance);
-    ipaddress_link_tool_js_1.default.registerTools(serverInstance);
-    ipaddress_resource_js_1.default.registerResources(serverInstance);
-    analysis_prompt_js_1.default.registerPrompts(serverInstance);
-    serverLogger.debug('All tools, resources, and prompts registered');
     if (mode === 'stdio') {
+        serverLogger.info(`Initializing Boilerplate MCP server v${constants_util_js_1.VERSION}`);
+        serverLogger.info('Registering MCP tools, resources, and prompts...');
+        serverInstance = createMcpServer();
+        serverLogger.debug('All tools, resources, and prompts registered');
         serverLogger.info('Using STDIO transport');
         transportInstance = new stdio_js_1.StdioServerTransport();
         try {
@@ -76,8 +93,10 @@ async function startServer(mode = 'stdio') {
             const allowedOrigins = [
                 'http://localhost',
                 'http://127.0.0.1',
+                'http://[::1]',
                 'https://localhost',
                 'https://127.0.0.1',
+                'https://[::1]',
             ];
             const isAllowed = allowedOrigins.some((allowed) => origin === allowed || origin.startsWith(`${allowed}:`));
             if (!isAllowed) {
@@ -90,30 +109,138 @@ async function startServer(mode = 'stdio') {
             }
             next();
         });
-        app.use((0, cors_1.default)());
-        app.use(express_1.default.json());
+        app.use((0, cors_1.default)({ origin: true }));
+        app.use(express_1.default.json({ limit: '1mb' }));
         const mcpEndpoint = '/mcp';
         serverLogger.debug(`MCP endpoint: ${mcpEndpoint}`);
-        // Create transport instance
-        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
-            // sessionIdGenerator is optional
-            sessionIdGenerator: undefined,
-        });
-        // Connect server to transport
-        await serverInstance.connect(transport);
-        transportInstance = transport;
-        // Handle all MCP requests
-        app.all(mcpEndpoint, (req, res) => {
-            transport
-                .handleRequest(req, res, req.body)
-                .catch((err) => {
-                serverLogger.error('Error in transport.handleRequest', err);
+        // Handle MCP POST requests (initialize + normal RPC calls)
+        app.post(mcpEndpoint, async (req, res) => {
+            const sessionId = getSessionId(req);
+            try {
+                if (sessionId) {
+                    const session = httpSessions.get(sessionId);
+                    if (!session) {
+                        res.status(404).json({
+                            jsonrpc: '2.0',
+                            error: {
+                                code: -32001,
+                                message: 'Session not found for provided Mcp-Session-Id',
+                            },
+                            id: null,
+                        });
+                        return;
+                    }
+                    session.lastActivity = Date.now();
+                    await session.transport.handleRequest(req, res, req.body);
+                    return;
+                }
+                if (!(0, types_js_1.isInitializeRequest)(req.body)) {
+                    res.status(400).json({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: Missing Mcp-Session-Id header',
+                        },
+                        id: null,
+                    });
+                    return;
+                }
+                serverLogger.info('Creating new HTTP MCP session for initialize request');
+                let initializedSessionId = null;
+                const sessionServer = createMcpServer();
+                const sessionTransport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => (0, node_crypto_1.randomUUID)(),
+                    onsessioninitialized: (newSessionId) => {
+                        initializedSessionId = newSessionId;
+                        httpSessions.set(newSessionId, {
+                            server: sessionServer,
+                            transport: sessionTransport,
+                            lastActivity: Date.now(),
+                        });
+                        serverLogger.info(`Initialized HTTP MCP session ${newSessionId}`);
+                    },
+                    onsessionclosed: (closedSessionId) => {
+                        const session = httpSessions.get(closedSessionId);
+                        if (!session) {
+                            return;
+                        }
+                        httpSessions.delete(closedSessionId);
+                        void session.server.close().catch((err) => {
+                            serverLogger.error(`Error closing server for session ${closedSessionId}`, err);
+                        });
+                        serverLogger.info(`Closed HTTP MCP session ${closedSessionId}`);
+                    },
+                });
+                await sessionServer.connect(sessionTransport);
+                try {
+                    await sessionTransport.handleRequest(req, res, req.body);
+                }
+                catch (err) {
+                    if (initializedSessionId) {
+                        httpSessions.delete(initializedSessionId);
+                    }
+                    await sessionTransport.close();
+                    await sessionServer.close();
+                    throw err;
+                }
+            }
+            catch (err) {
+                serverLogger.error('Error in HTTP MCP handler', err);
                 if (!res.headersSent) {
                     res.status(500).json({
-                        error: 'Internal Server Error',
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32603,
+                            message: 'Internal server error',
+                        },
+                        id: null,
                     });
                 }
-            });
+            }
+        });
+        // Handle optional GET requests for streamable HTTP SSE
+        app.get(mcpEndpoint, async (req, res) => {
+            const sessionId = getSessionId(req);
+            if (!sessionId) {
+                res.status(400).send('Missing Mcp-Session-Id header');
+                return;
+            }
+            const session = httpSessions.get(sessionId);
+            if (!session) {
+                res.status(404).send('Session not found');
+                return;
+            }
+            try {
+                await session.transport.handleRequest(req, res);
+            }
+            catch (err) {
+                serverLogger.error('Error in HTTP MCP GET handler', err);
+                if (!res.headersSent) {
+                    res.status(500).send('Internal Server Error');
+                }
+            }
+        });
+        // Handle session termination requests
+        app.delete(mcpEndpoint, async (req, res) => {
+            const sessionId = getSessionId(req);
+            if (!sessionId) {
+                res.status(400).send('Missing Mcp-Session-Id header');
+                return;
+            }
+            const session = httpSessions.get(sessionId);
+            if (!session) {
+                res.status(404).send('Session not found');
+                return;
+            }
+            try {
+                await session.transport.handleRequest(req, res);
+            }
+            catch (err) {
+                serverLogger.error('Error in HTTP MCP DELETE handler', err);
+                if (!res.headersSent) {
+                    res.status(500).send('Internal Server Error');
+                }
+            }
         });
         // Health check endpoint
         app.get('/', (_req, res) => {
@@ -123,14 +250,34 @@ async function startServer(mode = 'stdio') {
         const PORT = Number(process.env.PORT ?? 3000);
         const HOST = '127.0.0.1'; // Explicit localhost binding for security
         await new Promise((resolve) => {
-            app.listen(PORT, HOST, () => {
+            httpServerInstance = app.listen(PORT, HOST, () => {
                 serverLogger.info(`HTTP transport listening on http://${HOST}:${PORT}${mcpEndpoint}`);
                 serverLogger.info('Server bound to localhost only for security');
                 resolve();
             });
         });
+        // Reap idle sessions every 5 minutes (TTL: 30 minutes)
+        const SESSION_TTL_MS = 30 * 60 * 1000;
+        const REAP_INTERVAL_MS = 5 * 60 * 1000;
+        const reapInterval = setInterval(() => {
+            const now = Date.now();
+            for (const [sessionId, session] of httpSessions.entries()) {
+                if (now - session.lastActivity > SESSION_TTL_MS) {
+                    serverLogger.info(`Reaping idle HTTP session ${sessionId}`);
+                    httpSessions.delete(sessionId);
+                    void session.transport
+                        .close()
+                        .catch((err) => serverLogger.debug(`Error closing transport for reaped session ${sessionId}`, err))
+                        .then(() => session.server.close())
+                        .catch((err) => serverLogger.debug(`Error closing server for reaped session ${sessionId}`, err));
+                }
+            }
+        }, REAP_INTERVAL_MS);
+        reapInterval.unref();
         setupGracefulShutdown();
-        return serverInstance;
+        // HTTP mode uses per-session servers (managed in httpSessions map).
+        // Return a reference server for API compatibility; not connected to any transport.
+        return createMcpServer();
     }
 }
 /**
@@ -174,9 +321,36 @@ if (require.main === module) {
  */
 function setupGracefulShutdown() {
     const shutdownLogger = logger_util_js_1.Logger.forContext('index.ts', 'shutdown');
+    let shuttingDown = false;
     const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         try {
             shutdownLogger.info('Shutting down gracefully...');
+            if (httpSessions.size > 0) {
+                shutdownLogger.info(`Closing ${httpSessions.size} active HTTP session(s)`);
+            }
+            for (const [sessionId, session] of httpSessions.entries()) {
+                try {
+                    await session.transport.close();
+                }
+                catch (err) {
+                    shutdownLogger.error(`Error closing transport for session ${sessionId}`, err);
+                }
+                try {
+                    await session.server.close();
+                }
+                catch (err) {
+                    shutdownLogger.error(`Error closing server for session ${sessionId}`, err);
+                }
+            }
+            httpSessions.clear();
+            if (httpServerInstance) {
+                await new Promise((resolve) => {
+                    httpServerInstance.close(() => resolve());
+                });
+            }
             if (transportInstance &&
                 'close' in transportInstance &&
                 typeof transportInstance.close === 'function') {

package/dist/tools/ipaddress-link.tool.js

@@ -5,68 +5,61 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const logger_util_js_1 = require("../utils/logger.util.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"));
+const ipaddress_types_js_1 = require("./ipaddress.types.js");
 const logger = logger_util_js_1.Logger.forContext('tools/ipaddress-link.tool.ts');
 /**
  * Zod schema for the resource-link tool arguments
+ * Keep argument shape aligned with ip_get_details for consistency.
  */
 const GetIpDetailsLinkToolSchema = zod_1.z.object({
     ipAddress: zod_1.z
         .string()
         .optional()
         .describe('IP address to lookup (omit for current IP)'),
-    includeExtendedData: zod_1.z
-        .boolean()
-        .optional()
-        .describe('Include extended data (ASN, host, proxy detection)'),
+    ...ipaddress_types_js_1.IpAddressToolArgs.shape,
 });
 /**
  * Tool description for ip_get_details_link
  */
-const IP_GET_DETAILS_LINK_DESCRIPTION = `Retrieve IP address details and return as a resource reference (ResourceLink pattern).
-
-**This demonstrates the ResourceLink pattern** - instead of embedding full data inline, the tool returns a reference to a resource. This is useful for:
-- Large responses that would consume many tokens
-- Data that clients may cache and reuse
-- Responses that other tools can reference
-
-**When to use ResourceLink vs inline content:**
-- ResourceLink: Large data, cacheable, reusable across multiple tools
-- Inline: Small data, one-time use, immediate context
+const IP_GET_DETAILS_LINK_DESCRIPTION = `Retrieve IP address details and return both direct content and a resource link.
 
-**Parameters:**
-- \`ipAddress\` - IP to lookup (omit for current device's public IP)
-- \`includeExtendedData\` - Include ASN, host, proxy detection (requires API token)
+**Consistency with ip_get_details:**
+- Uses the same arguments: \`ipAddress\`, \`includeExtendedData\`, \`useHttps\`, \`jq\`, \`outputFormat\`
+- Uses the same output rendering pipeline (TOON by default, JSON when \`outputFormat: "json"\`)
 
-**Returns:** A resource reference (resourceLink) instead of inline text.
+**What this returns:**
+- A normal text response (same rendered output as \`ip_get_details\`)
+- A \`resource_link\` entry pointing to \`ip://<resolved-ip>\` for resource-style clients
 
 **Note:** Cannot lookup private IPs (192.168.x.x, 10.x.x.x). Powered by ip-api.com.`;
 /**
- * Handle IP lookup with ResourceLink pattern
+ * Handle IP lookup with resource-link + text output consistency.
  */
 async function handleGetIpDetailsLink(args) {
     const methodLogger = logger.forMethod('handleGetIpDetailsLink');
     methodLogger.debug(`Getting IP address details link for ${args.ipAddress || 'current IP'}...`, args);
     try {
-        // First, verify we can get the data
         const result = await ipaddress_controller_js_1.default.get(args);
-        // Extract the actual IP from the result
-        // The result.content includes the IP in TOON or JSON format
-        const ipMatch = result.content.match(/query[:\s]+([0-9.]+)/);
-        const actualIp = ipMatch?.[1] || args.ipAddress || 'current';
-        methodLogger.debug(`IP resolved to: ${actualIp}`);
-        // Return a ResourceLink instead of inline content
-        // This tells the client to fetch the resource separately
+        const actualIp = result.resolvedIp ||
+            (typeof args.ipAddress === 'string' ? args.ipAddress : 'current');
+        methodLogger.debug(`Resolved IP for resource URI: ${actualIp}`);
+        const textContent = (0, formatter_util_js_1.truncateForAI)(result.content, result.rawResponsePath);
+        const mimeType = args.outputFormat === 'json' ? 'application/json' : 'text/plain';
         return {
             content: [
                 {
-                    type: 'resource',
-                    resource: {
-                        uri: `ip://${actualIp}`,
-                        text: `IP lookup result available at resource ip://${actualIp}`,
-                        mimeType: 'text/markdown',
-                    },
+                    type: 'text',
+                    text: textContent,
+                },
+                {
+                    type: 'resource_link',
+                    uri: `ip://${actualIp}`,
+                    name: `IP lookup ${actualIp}`,
+                    description: `Resource link for IP lookup result ${actualIp}`,
+                    mimeType,
                 },
             ],
         };
@@ -86,6 +79,12 @@ function registerTools(server) {
         title: 'IP Address Lookup (ResourceLink)',
         description: IP_GET_DETAILS_LINK_DESCRIPTION,
         inputSchema: GetIpDetailsLinkToolSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, handleGetIpDetailsLink);
     methodLogger.debug('Successfully registered ip_get_details_link tool.');
 }

package/dist/tools/ipaddress.tool.js

@@ -93,6 +93,12 @@ function registerTools(server) {
         title: 'IP Address Lookup',
         description: IP_GET_DETAILS_DESCRIPTION,
         inputSchema: GetIpDetailsToolSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
     }, handleGetIpDetails);
     methodLogger.debug('Successfully registered ip_get_details tool.');
 }

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

@@ -50,4 +50,9 @@ export interface ControllerResponse {
      * When the response is truncated, this path allows AI to access the full data.
      */
     rawResponsePath?: string | null;
+    /**
+     * Canonical resolved IP from the upstream API response.
+     * Use this to avoid parsing formatted output when consumers need the queried IP value.
+     */
+    resolvedIp?: string;
 }

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

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

@@ -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.19.0';
+exports.VERSION = '3.1.0';
 /**
  * Package name with scope
  * Used for initialization and identification

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

@@ -162,7 +162,7 @@ function createUserFriendlyErrorMessage(code, context = {}, originalMessage) {
     const entity = entityType
         ? `${entityType}${entityIdStr ? ` ${entityIdStr}` : ''}`
         : 'Resource';
-    let message = '';
+    let message;
     switch (code) {
         case ErrorCode.NOT_FOUND:
             message = `${entity} not found${entityIdStr ? `: ${entityIdStr}` : ''}. Verify the ID is correct and that you have access to this ${entityType?.toLowerCase() || 'resource'}.`;

package/docs/MCP-MODERNIZATION-RELEASE-RUNBOOK.md

@@ -0,0 +1,306 @@
+# MCP Modernization + Release Runbook
+
+## Purpose
+
+This runbook documents the exact modernization + release approach used in this repository so other MCP servers can follow the same pattern with predictable outcomes.
+
+Scope covered:
+
+- Baseline audit (history, diffs, dependencies, CI)
+- Streamable HTTP transport hardening
+- Tool input/output contract standardization
+- Inspector-based validation
+- Semantic-release driven publishing
+
+---
+
+## Case Study Window (This Repo)
+
+Reference range analyzed:
+
+- From: `v3.0.0` (`fadd464`)
+- To: `HEAD` (`08f8a02`)
+
+Key commits:
+
+- `615b373` `feat: modernize HTTP transport and standardize MCP tool contracts`
+- `287cb4c` `chore(release): 3.1.0 [skip ci]`
+- `08f8a02` `docs: sync README and security guidance with current tooling`
+
+### File-Level Change Summary (`v3.0.0..HEAD`)
+
+- `.releaserc.json`
+- `CHANGELOG.md`
+- `README.md`
+- `SECURITY.md`
+- `package-lock.json`
+- `package.json`
+- `src/controllers/ipaddress.controller.ts`
+- `src/index.ts`
+- `src/tools/ipaddress-link.tool.ts`
+- `src/types/common.types.ts`
+- `src/utils/constants.util.ts`
+- `src/utils/error-handler.util.ts`
+
+High-impact deltas:
+
+- `src/index.ts`: moved HTTP handling to session-aware streamable transport flow.
+- `src/tools/ipaddress-link.tool.ts`: aligned input schema with `ip_get_details`, standardized output to `text` + `resource_link`.
+- `src/controllers/ipaddress.controller.ts` + `src/types/common.types.ts`: exposed canonical `resolvedIp` to avoid parsing rendered output.
+- `package.json` + `package-lock.json`: dependency upgrades and script surface simplification.
+- `.releaserc.json`: added `src/utils/constants.util.ts` to git release assets to prevent version drift.
+
+---
+
+## Phase 1: Baseline Audit
+
+### 1.1 Capture release baseline
+
+```bash
+git tag --sort=-v:refname | head -n 10
+git log --oneline --decorate vX.Y.Z..HEAD
+git diff --name-status vX.Y.Z..HEAD
+git diff --stat vX.Y.Z..HEAD
+```
+
+### 1.2 Validate release pipeline wiring
+
+Check:
+
+- `.releaserc.json`
+- `.github/workflows/ci-semantic-release.yml`
+- `package.json` `engines`, scripts, dependencies
+
+Release prerequisites:
+
+- Conventional commits
+- Semantic-release workflow on push to `main`
+- OIDC trusted publishing (no `NPM_TOKEN` required)
+
+---
+
+## Phase 2: Modernize Streamable HTTP Transport
+
+## Problem Pattern
+
+Stateless `StreamableHTTPServerTransport` reuse across requests causes failures after `initialize`.
+
+## Correct Pattern
+
+Use stateful session management:
+
+- Create a transport on initialize
+- Generate `Mcp-Session-Id`
+- Store per-session `{ server, transport }`
+- Route POST/GET/DELETE by session
+- Cleanup on session close + process shutdown
+
+## Implementation Checklist
+
+- Add session map keyed by `Mcp-Session-Id`
+- Validate initialize requests with `isInitializeRequest`
+- Reject non-initialize requests without session header
+- Implement:
+    - `POST /mcp` for initialize + rpc
+    - `GET /mcp` for SSE stream channel if used
+    - `DELETE /mcp` for session termination
+- Add graceful shutdown over all sessions
+
+---
+
+## Phase 3: Standardize Tool Contracts
+
+Target rule for related tools:
+
+- Same input schema unless there is a strong functional reason to diverge.
+- Same base output shape for primary payload.
+- Additive behavior only where required (e.g., extra link item).
+
+## Applied Pattern
+
+For `ip_get_details` and `ip_get_details_link`:
+
+- Input parity:
+    - `ipAddress`
+    - `includeExtendedData`
+    - `useHttps`
+    - `jq`
+    - `outputFormat`
+- Output parity:
+    - First content block is always `text` from the same toon/json renderer.
+- Link tool extension:
+    - Second block is `resource_link` (`ip://<resolved-ip>`).
+
+## Critical anti-pattern to avoid
+
+Do not parse rendered text (regex on TOON/JSON output) to recover structured fields.
+
+Instead:
+
+- expose canonical data from controller/service boundary (`resolvedIp`) and consume that.
+
+---
+
+## Phase 4: Test Matrix (Required)
+
+### 4.1 Static quality gates
+
+```bash
+npm run lint
+npm run build
+npm test -- --runInBand
+```
+
+### 4.2 Streamable HTTP protocol flow test (curl)
+
+Required sequence:
+
+1. `initialize`
+2. `notifications/initialized`
+3. `tools/list`
+4. `tools/call`
+
+Assertions:
+
+- `initialize` -> `200`, has `mcp-session-id`
+- `notifications/initialized` -> `202`
+- `tools/list` -> `200`
+- `tools/call` -> `200`
+
+### 4.3 SDK client compatibility test
+
+Use official transport:
+
+- `StreamableHTTPClientTransport`
+- `Client` from MCP TS SDK
+
+Assertions:
+
+- `connect()` succeeds
+- `tools/list` succeeds
+- representative `tools/call` succeeds
+
+### 4.4 Inspector validation
+
+- CLI check:
+
+```bash
+npx @modelcontextprotocol/inspector --cli "http://127.0.0.1:PORT/mcp" --transport http --method tools/list
+```
+
+- UI check via proxy token URL.
+
+For remote access:
+
+- `HOST=0.0.0.0`
+- `ALLOWED_ORIGINS` includes remote UI origin
+- set `MCP_PROXY_FULL_ADDRESS` to reachable host:port
+
+Security note: keep auth enabled (`MCP_PROXY_AUTH_TOKEN`), do not use `DANGEROUSLY_OMIT_AUTH`.
+
+---
+
+## Phase 5: Semantic Release Procedure
+
+### 5.1 Pre-release checks
+
+```bash
+git status --short
+npm run lint && npm run build && npm test -- --runInBand
+```
+
+### 5.2 Commit strategy
+
+Use conventional commits:
+
+- `fix:` -> patch
+- `feat:` -> minor
+- `feat!:` or `BREAKING CHANGE:` -> major
+
+### 5.3 Push and monitor
+
+```bash
+git push origin main
+gh run list --repo <owner>/<repo> --limit 5
+gh run watch <run-id> --repo <owner>/<repo>
+```
+
+### 5.4 Verify artifacts
+
+```bash
+git fetch --tags origin
+git tag --sort=-v:refname | head
+gh release list --repo <owner>/<repo> --limit 5
+npm view <package-name> version
+```
+
+---
+
+## Release Config Guardrails
+
+### Guardrail 1: Keep version files aligned
+
+If custom prepare scripts update files, ensure `@semantic-release/git` assets include them.
+
+In this repo:
+
+- `scripts/update-version.js` updates `src/utils/constants.util.ts`
+- therefore `src/utils/constants.util.ts` must be in `.releaserc.json` git assets.
+
+### Guardrail 2: Avoid script sprawl
+
+Keep `package.json` scripts minimal and operationally relevant:
+
+- build/lint/test/format
+- core run paths (`cli`, `mcp:stdio`, `mcp:http`, `mcp:inspect`)
+
+Remove duplicate aliases that do not add behavior.
+
+### Guardrail 3: Update active docs only
+
+When behavior changes, update:
+
+- `README.md`
+- `SECURITY.md`
+- active setup docs
+
+Do not rewrite historical/audit snapshots unless they claim current state.
+
+---
+
+## Reusable Execution Checklist
+
+- [ ] Identify release baseline tag and commit window
+- [ ] Review commit history + per-file diff stats
+- [ ] Validate semantic-release + CI workflow config
+- [ ] Modernize streamable HTTP transport to session-safe pattern
+- [ ] Standardize related tool input/output contracts
+- [ ] Remove output parsing hacks (regex/content scraping)
+- [ ] Run lint/build/tests
+- [ ] Run curl protocol flow tests
+- [ ] Run official SDK client tests
+- [ ] Run Inspector CLI + UI tests
+- [ ] Commit with conventional commit type
+- [ ] Push to `main`
+- [ ] Watch semantic-release workflow to completion
+- [ ] Verify git tag, GitHub release, npm version
+- [ ] Sync active docs with final behavior
+
+---
+
+## Appendix: Commands Used in This Repo
+
+```bash
+# History/diff tracing
+git log --oneline --decorate v3.0.0..HEAD
+git diff --name-status v3.0.0..HEAD
+git diff --stat v3.0.0..HEAD
+
+# Semantic-release dry check (local repo URL fallback)
+npx semantic-release --dry-run --no-ci --branches main \
+  --repository-url file:///absolute/path/to/repo \
+  --plugins @semantic-release/commit-analyzer @semantic-release/release-notes-generator
+
+# Inspector CLI against streamable HTTP
+npx @modelcontextprotocol/inspector --cli "http://127.0.0.1:3330/mcp" --transport http --method tools/list
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "3.0.0",
+	"version": "3.2.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",
@@ -14,28 +14,18 @@
 	},
 	"scripts": {
 		"build": "tsc",
+		"clean": "rm -rf dist coverage",
 		"prepare": "npm run build && node scripts/ensure-executable.js",
 		"postinstall": "node scripts/ensure-executable.js",
-		"clean": "rm -rf dist coverage",
+		"lint": "eslint src --ext .ts --config eslint.config.mjs",
+		"format": "prettier --write 'src/**/*.ts' 'scripts/**/*.js'",
 		"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",
-		"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",
+		"cli": "npm run build && node dist/index.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": "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"
+		"mcp:inspect": "TRANSPORT_MODE=http npm run build && (node dist/index.js &) && sleep 2 && npx @modelcontextprotocol/inspector http://localhost:3000/mcp"
 	},
 	"keywords": [
 		"mcp",
@@ -56,42 +46,42 @@
 	"author": "Andi Ashari",
 	"license": "ISC",
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=20.0.0"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.39.1",
+		"@eslint/js": "^10.0.1",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/exec": "^7.1.0",
 		"@semantic-release/git": "^10.0.1",
-		"@semantic-release/github": "^12.0.2",
-		"@semantic-release/npm": "^13.1.2",
+		"@semantic-release/github": "^12.0.6",
+		"@semantic-release/npm": "^13.1.4",
 		"@types/cors": "^2.8.19",
-		"@types/express": "^5.0.5",
+		"@types/express": "^5.0.6",
 		"@types/jest": "^30.0.0",
 		"@types/jmespath": "^0.15.2",
-		"@types/node": "^24.10.10",
-		"@typescript-eslint/eslint-plugin": "^8.48.0",
-		"@typescript-eslint/parser": "^8.48.0",
-		"eslint": "^9.39.1",
+		"@types/node": "^25.2.3",
+		"@typescript-eslint/eslint-plugin": "^8.56.0",
+		"@typescript-eslint/parser": "^8.56.0",
+		"eslint": "^10.0.0",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-filenames": "^1.3.2",
-		"eslint-plugin-prettier": "^5.5.4",
+		"eslint-plugin-prettier": "^5.5.5",
 		"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",
+		"npm-check-updates": "^19.3.2",
+		"prettier": "^3.8.1",
+		"semantic-release": "^25.0.3",
+		"ts-jest": "^29.4.6",
 		"ts-node": "^10.9.2",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.48.0"
+		"typescript-eslint": "^8.56.0"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.25.3",
+		"@modelcontextprotocol/sdk": "^1.26.0",
 		"@toon-format/toon": "^2.1.0",
 		"commander": "^14.0.3",
 		"cors": "^2.8.6",
-		"dotenv": "^17.2.3",
+		"dotenv": "^17.3.1",
 		"express": "^5.2.1",
 		"jmespath": "^0.16.0",
 		"zod": "^4.3.6"

package/package.json.bak

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "2.0.0",
+	"version": "3.1.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",
@@ -14,28 +14,18 @@
 	},
 	"scripts": {
 		"build": "tsc",
+		"clean": "rm -rf dist coverage",
 		"prepare": "npm run build && node scripts/ensure-executable.js",
 		"postinstall": "node scripts/ensure-executable.js",
-		"clean": "rm -rf dist coverage",
+		"lint": "eslint src --ext .ts --config eslint.config.mjs",
+		"format": "prettier --write 'src/**/*.ts' 'scripts/**/*.js'",
 		"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",
-		"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",
+		"cli": "npm run build && node dist/index.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": "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"
+		"mcp:inspect": "TRANSPORT_MODE=http npm run build && (node dist/index.js &) && sleep 2 && npx @modelcontextprotocol/inspector http://localhost:3000/mcp"
 	},
 	"keywords": [
 		"mcp",
@@ -56,42 +46,42 @@
 	"author": "Andi Ashari",
 	"license": "ISC",
 	"engines": {
-		"node": ">=18.0.0"
+		"node": ">=20.0.0"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.39.1",
+		"@eslint/js": "^10.0.1",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/exec": "^7.1.0",
 		"@semantic-release/git": "^10.0.1",
-		"@semantic-release/github": "^12.0.2",
-		"@semantic-release/npm": "^13.1.2",
+		"@semantic-release/github": "^12.0.6",
+		"@semantic-release/npm": "^13.1.4",
 		"@types/cors": "^2.8.19",
-		"@types/express": "^5.0.5",
+		"@types/express": "^5.0.6",
 		"@types/jest": "^30.0.0",
 		"@types/jmespath": "^0.15.2",
-		"@types/node": "^24.10.10",
-		"@typescript-eslint/eslint-plugin": "^8.48.0",
-		"@typescript-eslint/parser": "^8.48.0",
-		"eslint": "^9.39.1",
+		"@types/node": "^25.2.3",
+		"@typescript-eslint/eslint-plugin": "^8.56.0",
+		"@typescript-eslint/parser": "^8.56.0",
+		"eslint": "^10.0.0",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-filenames": "^1.3.2",
-		"eslint-plugin-prettier": "^5.5.4",
+		"eslint-plugin-prettier": "^5.5.5",
 		"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",
+		"npm-check-updates": "^19.3.2",
+		"prettier": "^3.8.1",
+		"semantic-release": "^25.0.3",
+		"ts-jest": "^29.4.6",
 		"ts-node": "^10.9.2",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.48.0"
+		"typescript-eslint": "^8.56.0"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.25.3",
+		"@modelcontextprotocol/sdk": "^1.26.0",
 		"@toon-format/toon": "^2.1.0",
 		"commander": "^14.0.3",
 		"cors": "^2.8.6",
-		"dotenv": "^17.2.3",
+		"dotenv": "^17.3.1",
 		"express": "^5.2.1",
 		"jmespath": "^0.16.0",
 		"zod": "^4.3.6"