@aashari/boilerplate-mcp-server 1.17.0 → 3.0.0

package/CHANGELOG.md

@@ -1,3 +1,166 @@
+# [3.0.0](https://github.com/aashari/boilerplate-mcp-server/compare/v2.0.0...v3.0.0) (2026-02-04)
+
+
+### Features
+
+* migrate to OIDC trusted publishing for npm (long-term solution) ([b7c36e3](https://github.com/aashari/boilerplate-mcp-server/commit/b7c36e31688e68a38cfd21977c938dc48d1bb380))
+
+
+### BREAKING CHANGES
+
+* Requires one-time OIDC configuration on npmjs.com
+See docs/OIDC-TRUSTED-PUBLISHING-SETUP.md for complete migration guide
+
+# [2.0.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.17.0...v2.0.0) (2026-02-04)
+
+
+### Bug Fixes
+
+* disable npm publishing in semantic-release ([7bef842](https://github.com/aashari/boilerplate-mcp-server/commit/7bef84256a953919a711a1ee132be3b2397d8aa4))
+
+
+### Features
+
+* add security hardening, prompts support, and ResourceLink pattern ([02a89c2](https://github.com/aashari/boilerplate-mcp-server/commit/02a89c2aa55db3ce52fbcb5ccb693b833f1e5e9d))
+
+
+### BREAKING CHANGES
+
+* none
+Security: DNS rebinding protection, localhost binding
+Testing: 47 unit tests + 15 integration tests passing (100%)
+
+# [1.19.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.18.0...v1.19.0) (2026-02-04)
+
+### Security 🔒
+
+* **security:** implement DNS rebinding protection with Origin header validation ([src/index.ts](src/index.ts))
+  - Validates Origin header on all HTTP requests
+  - Prevents malicious websites from accessing localhost MCP server
+  - Allows localhost/127.0.0.1 origins only
+  - Returns 403 Forbidden for invalid origins
+
+* **security:** add explicit localhost-only binding ([src/index.ts](src/index.ts))
+  - Server explicitly binds to 127.0.0.1 (not 0.0.0.0)
+  - Prevents network exposure and remote attacks
+  - Ensures server only accepts local connections
+
+* **security:** add comprehensive security documentation ([SECURITY.md](SECURITY.md))
+  - Complete threat model and mitigation strategies
+  - Authentication implementation guides (Bearer, API Key, OAuth, mTLS)
+  - Security checklists for dev/staging/production
+  - Best practices for input validation, rate limiting, logging
+
+* **security:** publish security audit report ([docs/AUDIT-2025-01-13.md](docs/AUDIT-2025-01-13.md))
+  - Independent audit against MCP best practices
+  - 70% compliance rating with clear improvement roadmap
+  - All critical security gaps addressed in this release
+
+### Features ✨
+
+* **mcp:** add `isError: true` field to tool error responses ([src/utils/error.util.ts](src/utils/error.util.ts))
+  - Follows MCP best practices for error signaling
+  - Enables clients to reliably detect error states
+  - Maintains backward compatibility with metadata
+
+* **mcp:** add ResourceLink pattern example ([src/tools/ipaddress-link.tool.ts](src/tools/ipaddress-link.tool.ts))
+  - New `ip_get_details_link` tool demonstrates ResourceLink pattern
+  - Returns resource references instead of inline content
+  - Reduces token usage for large responses
+  - Shows pattern for cacheable, reusable data
+
+* **mcp:** add prompt registration support ([src/prompts/analysis.prompt.ts](src/prompts/analysis.prompt.ts))
+  - New `ip-analysis` prompt generates structured IP analysis requests
+  - Supports multiple focus modes (security, geolocation, network, comprehensive)
+  - Demonstrates all three MCP primitives (tools, resources, prompts)
+  - Provides template for AI-driven analysis workflows
+
+* **architecture:** add prompts layer to 7-layer architecture
+  - Clean separation of prompt templates from tools/resources
+  - Type-safe prompt argument schemas with Zod
+  - Registered in index.ts alongside tools and resources
+
+### Documentation 📖
+
+* **readme:** update README with security section and new features
+  - Add security badges and protection summary
+  - Document ResourceLink pattern and prompt examples
+  - Update architecture overview to 7 layers
+  - Add references to SECURITY.md and audit report
+
+* **docs:** update project structure in README
+  - Add prompts/ directory
+  - Add ipaddress-link.tool.ts
+  - Update layer descriptions
+
+### Testing ✅
+
+All tests passing after security and feature additions:
+- ✅ 6 test suites, 47 tests passed
+- ✅ Build successful with TypeScript compilation
+- ✅ DNS rebinding protection tested
+- ✅ Localhost binding verified
+- ✅ New tools and prompts functional
+
+### Breaking Changes
+
+**None** - All changes are backward compatible additions.
+
+---
+
+# [1.18.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.17.0...v1.18.0) (2026-02-04)
+
+### Features
+
+* **deps:** modernize all dependencies to latest stable versions ([#TBD](https://github.com/aashari/boilerplate-mcp-server/issues/TBD))
+  - Update MCP SDK from 1.23.0 to 1.25.3 (stability improvements)
+  - Update Zod from 4.1.13 to 4.3.6 (major feature release)
+  - Update @toon-format/toon from 2.0.1 to 2.1.0
+  - Update Express from 5.1.0 to 5.2.1
+  - Update Commander from 14.0.2 to 14.0.3
+  - Update CORS from 2.8.5 to 2.8.6
+  - Update @types/node from 24.10.1 to 24.10.10
+
+### Documentation
+
+* **modernization:** add comprehensive modernization guide ([MODERNIZATION.md](MODERNIZATION.md))
+  - Document new Zod 4.3 features (z.fromJSONSchema, z.xor, z.looseRecord, .exactOptional)
+  - Add MCP SDK v2 preparation guide
+  - Include migration timeline and recommendations
+  - Provide code examples for new features
+
+* **readme:** update README with latest versions and v2 preparation notes
+
+### Zod 4.3 New Features Available
+
+While maintaining backward compatibility, the following new Zod features are now available:
+
+- `z.fromJSONSchema()` - Convert JSON Schema to Zod schemas
+- `z.xor()` - Exclusive union validation (exactly one must match)
+- `z.looseRecord()` - Partial record validation
+- `.exactOptional()` - Strict optional properties
+- `.apply()` - Schema composition helper
+- `.with()` - Readable alias for `.check()`
+- Type predicates on `.refine()`
+- `z.slugify()` - URL-friendly slug transformation
+
+### MCP SDK v2 Preparation
+
+- Confirmed compatibility with v2 patterns (no code changes needed)
+- Added v2 migration guide and timeline
+- Project already uses modern v1.x APIs (registerTool, ResourceTemplate, etc.)
+
+### Testing
+
+All tests pass with updated dependencies:
+- ✅ 6 test suites, 47 tests passed
+- ✅ CLI functionality verified
+- ✅ HTTPS to HTTP fallback working correctly
+
+### Breaking Changes
+
+**None** - This is a drop-in update maintaining full backward compatibility.
+
 # [1.17.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.16.1...v1.17.0) (2025-12-03)
 
 

package/README.md

@@ -5,18 +5,25 @@ 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.
+
 ## Features
 
+- **Security First**: DNS rebinding protection, localhost-only binding, secure error handling
 - **Dual Transport Support**: STDIO and Streamable HTTP transports with automatic fallback
-- **5-Layer Architecture**: Clean separation between CLI, tools, controllers, services, and utilities
-- **Type Safety**: Full TypeScript implementation with Zod v4 schema validation
+- **Layered Architecture**: Clean separation between CLI, tools, resources, prompts, controllers, services, and utilities
+- **Type Safety**: Full TypeScript implementation with Zod v4.3.6 schema validation
+- **All MCP Primitives**: Tools, resources, and prompts (with examples)
+- **ResourceLink Pattern**: Token-efficient resource references for large responses
 - **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
-- **Modern SDK**: Uses MCP SDK v1.23.0 with `registerTool` API pattern
-- **Complete IP Address Example**: Tools, resources, and CLI commands for IP geolocation
-- **Comprehensive Testing**: Unit and integration tests with coverage reporting
+- **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)
+- **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
-- **Error Handling**: Structured error handling with contextual logging
+- **Error Handling**: Structured error handling with `isError` field and contextual logging
+- **Security Documentation**: Complete [SECURITY.md](SECURITY.md) with authentication implementation guides
 
 ## What is MCP?
 
@@ -44,10 +51,10 @@ npm run build
 
 # 1. CLI Mode - Execute commands directly
 npm run cli -- get-ip-details 8.8.8.8
-npm run cli -- get-ip-details              # Get your current IP
-npm run cli -- get-ip-details 1.1.1.1 --include-extended-data
-npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}"  # JQ filter
-npm run cli -- get-ip-details 8.8.8.8 --output-format json                   # JSON output
+npm run cli -- get-ip-details                                            # Get your current IP
+npm run cli -- get-ip-details 1.1.1.1 -e                                 # With extended data
+npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}"  # JMESPath filter
+npm run cli -- get-ip-details 8.8.8.8 -o json                            # JSON output
 
 # 2. STDIO Transport - For AI assistant integration (Claude Desktop, Cursor)
 npm run mcp:stdio
@@ -74,6 +81,26 @@ npm run mcp:inspect                         # Auto-opens browser with debugging
 - Health Check: `http://localhost:3000/` → Returns server version
 - Run with: `TRANSPORT_MODE=http node dist/index.js`
 
+## Security 🔒
+
+**This boilerplate implements production-ready security measures:**
+
+### ✅ Built-In Protection
+
+1. **DNS Rebinding Protection**: Origin header validation prevents malicious websites from accessing your localhost server
+2. **Localhost-Only Binding**: Server explicitly binds to `127.0.0.1` (not accessible from network)
+3. **Secure Error Handling**: Error responses include `isError: true` flag and don't leak sensitive information
+
+### 🔐 Security Best Practices
+
+- **Local Development**: No authentication required (localhost-only + DNS rebinding protection)
+- **Network Deployment**: Authentication REQUIRED - see [SECURITY.md](SECURITY.md) for implementation guides
+- **Production**: Use mTLS, OAuth 2.0, or bearer tokens (detailed in [SECURITY.md](SECURITY.md))
+
+**📖 Complete security documentation:** [SECURITY.md](SECURITY.md)
+
+**🔍 Security audit report:** [docs/AUDIT-2025-01-13.md](docs/AUDIT-2025-01-13.md)
+
 ## Output Formats
 
 ### TOON Format (Default)
@@ -137,10 +164,13 @@ src/
 │   ├── vendor.ip-api.com.service.ts  # ip-api.com service
 │   └── vendor.ip-api.com.types.ts    # Service type definitions
 ├── tools/                  # MCP tool definitions (AI interface)
-│   ├── ipaddress.tool.ts   # IP lookup tool for AI assistants
+│   ├── ipaddress.tool.ts   # IP lookup tool (inline content)
+│   ├── ipaddress-link.tool.ts  # IP lookup with ResourceLink pattern
 │   └── ipaddress.types.ts  # Tool argument schemas
 ├── resources/              # MCP resource definitions
 │   └── ipaddress.resource.ts # IP lookup resource (URI: ip://address)
+├── prompts/                # MCP prompt definitions
+│   └── analysis.prompt.ts  # IP analysis prompt templates
 ├── types/                  # Global type definitions
 │   └── common.types.ts     # Shared interfaces (ControllerResponse, etc.)
 ├── utils/                  # Shared utilities
@@ -149,18 +179,19 @@ src/
 │   ├── error-handler.util.ts # Error handling utilities
 │   ├── config.util.ts      # Environment configuration
 │   ├── constants.util.ts   # Version and package constants
-│   ├── formatter.util.ts   # Markdown formatting
+│   ├── formatter.util.ts   # Markdown formatting and response truncation
 │   ├── toon.util.ts        # TOON format encoding
 │   ├── jq.util.ts          # JMESPath filtering
+│   ├── response.util.ts    # Raw API response logging
 │   └── transport.util.ts   # HTTP transport utilities
 └── index.ts                # Server entry point (dual transport)
 ```
 
 </details>
 
-## 5-Layer Architecture
+## Layered Architecture
 
-The boilerplate follows a clean, layered architecture that promotes maintainability and clear separation of concerns:
+The boilerplate follows a clean, layered architecture with 6 distinct layers that promotes maintainability and clear separation of concerns:
 
 ### 1. CLI Layer (`src/cli/`)
 
@@ -203,10 +234,14 @@ The boilerplate follows a clean, layered architecture that promotes maintainabil
 - **Key Components**:
   - `logger.util.ts`: Contextual logging (file:method context)
   - `error.util.ts`: MCP-specific error formatting
+  - `error-handler.util.ts`: Error handling and context building
   - `transport.util.ts`: HTTP/API utilities with retry logic
   - `config.util.ts`: Environment configuration management
+  - `constants.util.ts`: Version and package constants
+  - `formatter.util.ts`: Markdown formatting and response truncation
   - `toon.util.ts`: TOON format encoding (token-efficient output)
   - `jq.util.ts`: JMESPath filtering for response transformation
+  - `response.util.ts`: Raw API response logging to `/tmp/mcp/<project>/`
 
 ## Developer Guide
 
@@ -246,21 +281,23 @@ npm run update:deps         # Update dependencies
 ### Environment Variables
 
 #### Core Configuration
-- `TRANSPORT_MODE`: Transport mode (`stdio` | `http`, default: `stdio`)  
+- `TRANSPORT_MODE`: Transport mode (`stdio` | `http`, default: `stdio`)
 - `PORT`: HTTP server port (default: `3000`)
 - `DEBUG`: Enable debug logging (`true` | `false`, default: `false`)
+- `NODE_ENV`: Node environment (`development` | `production`, default: `development`)
 
-#### IP API Configuration  
+#### IP API Configuration
 - `IPAPI_API_TOKEN`: API token for ip-api.com extended data (optional, free tier available)
 
 #### Example `.env` File
 ```bash
-# Basic configuration
+# Core configuration
 TRANSPORT_MODE=http
-PORT=3001
+PORT=3000
 DEBUG=true
+NODE_ENV=development
 
-# Extended data (requires ip-api.com account)
+# External API Keys
 IPAPI_API_TOKEN=your_token_here
 ```
 
@@ -273,6 +310,12 @@ IPAPI_API_TOKEN=your_token_here
 
 - **Debug Logging**: Enable with `DEBUG=true` environment variable
 
+- **Raw Response Logging**: Large API responses (>40,000 characters) are automatically logged
+  - Responses saved to `/tmp/mcp/<project-name>/` directory
+  - Filename format: `<timestamp>-<random>.txt`
+  - Includes request details, response data, and performance metrics
+  - Truncated responses include guidance on accessing the full raw file
+
 <details>
 <summary><b>Configuration (Click to expand)</b></summary>
 
@@ -451,7 +494,7 @@ async function handleGetData(args: Record<string, unknown>) {
 	}
 }
 
-// Registration function using the modern registerTool API (SDK v1.22.0+)
+// Registration function using the modern registerTool API (SDK v1.23.0)
 function registerTools(server: McpServer) {
 	const registerLogger = logger.forMethod('registerTools');
 	registerLogger.debug('Registering example tools...');
@@ -560,7 +603,7 @@ function registerResources(server: McpServer) {
 	const registerLogger = logger.forMethod('registerResources');
 	registerLogger.debug('Registering example resources...');
 
-	// Use registerResource with ResourceTemplate for parameterized URIs (SDK v1.22.0+)
+	// Use registerResource with ResourceTemplate for parameterized URIs (SDK v1.23.0)
 	server.registerResource(
 		'example-data',
 		new ResourceTemplate('example://{param}', { list: undefined }),
@@ -610,21 +653,29 @@ The boilerplate includes a complete IP address geolocation example demonstrating
 
 **CLI Commands:**
 ```bash
-npm run cli -- get-ip-details                           # Get current public IP (TOON format)
-npm run cli -- get-ip-details 8.8.8.8                   # Get details for specific IP
-npm run cli -- get-ip-details 1.1.1.1 --include-extended-data   # With extended data
-npm run cli -- get-ip-details 8.8.8.8 --no-use-https    # Force HTTP (for free tier)
-npm run cli -- get-ip-details 8.8.8.8 --output-format json      # JSON output
-npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}"  # Filtered output
+npm run cli -- get-ip-details                                            # Get current public IP (TOON format)
+npm run cli -- get-ip-details 8.8.8.8                                    # Get details for specific IP
+npm run cli -- get-ip-details 1.1.1.1 -e                                 # Short form with extended data
+npm run cli -- get-ip-details 1.1.1.1 --include-extended-data           # Long form with extended data
+npm run cli -- get-ip-details 8.8.8.8 --no-use-https                    # Force HTTP (for free tier)
+npm run cli -- get-ip-details 8.8.8.8 -o json                            # JSON output (short form)
+npm run cli -- get-ip-details 8.8.8.8 --output-format json              # JSON output (long form)
+npm run cli -- get-ip-details 8.8.8.8 --jq "{ip: query, country: country}"  # JMESPath filtered output
 ```
 
 **MCP Tools:**
 - `ip_get_details` - IP geolocation lookup for AI assistants
-  - Supports `outputFormat`: "toon" (default) or "json"
-  - Supports `jq`: JMESPath expression for filtering
+  - 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"
 
 **MCP Resources:**
-- `ip://{ipAddress}` - IP details resource template (e.g., `ip://8.8.8.8`)
+- `ip://{ipAddress}` - IP details resource template (e.g., `ip://8.8.8.8`, `ip://1.1.1.1`)
+  - Returns IP geolocation data in Markdown format
+  - Uses TOON format by default for token efficiency
 
 ### Features Demonstrated
 
@@ -709,11 +760,22 @@ npm run test:cli           # CLI-specific tests only
 
 [ISC License](https://opensource.org/licenses/ISC)
 
+## MCP SDK v2 Preparation
+
+⚠️ **Note**: MCP SDK v2 is in development (expected stable Q1 2026). This boilerplate is ready for migration with minimal changes needed.
+
+**Key v2 Changes**:
+- Package split: `@modelcontextprotocol/server` and `@modelcontextprotocol/client`
+- Optional middleware packages for Express, Hono, Node.js HTTP
+- Same core API patterns (this boilerplate already uses modern APIs)
+
+See [MODERNIZATION.md](MODERNIZATION.md) for detailed migration guide and timeline.
+
 ## Resources & Documentation
 
 ### MCP Protocol Resources
 - [MCP Specification](https://modelcontextprotocol.io/specification) - Latest protocol specification
-- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk) - TypeScript SDK v1.23.0+
+- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk) - TypeScript SDK v1.23.0
 - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - Visual debugging tool
 - [MCP Concepts](https://modelcontextprotocol.io/docs/concepts) - Tools, resources, transports