@aashari/boilerplate-mcp-server 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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)
 
 

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
@@ -660,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`)
@@ -713,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/index.js

@@ -24,6 +24,7 @@ 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({
@@ -92,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) {
@@ -106,8 +109,8 @@ 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}`);
         // Handle MCP POST requests (initialize + normal RPC calls)
@@ -127,6 +130,7 @@ async function startServer(mode = 'stdio') {
                         });
                         return;
                     }
+                    session.lastActivity = Date.now();
                     await session.transport.handleRequest(req, res, req.body);
                     return;
                 }
@@ -151,6 +155,7 @@ async function startServer(mode = 'stdio') {
                         httpSessions.set(newSessionId, {
                             server: sessionServer,
                             transport: sessionTransport,
+                            lastActivity: Date.now(),
                         });
                         serverLogger.info(`Initialized HTTP MCP session ${newSessionId}`);
                     },
@@ -245,13 +250,33 @@ 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();
+        // HTTP mode uses per-session servers (managed in httpSessions map).
+        // Return a reference server for API compatibility; not connected to any transport.
         return createMcpServer();
     }
 }
@@ -296,7 +321,11 @@ 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) {
@@ -317,6 +346,11 @@ function setupGracefulShutdown() {
                 }
             }
             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

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

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.1.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",

package/package.json.bak

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "3.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",