@aashari/boilerplate-mcp-server 1.10.0 → 1.10.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.10.2](https://github.com/aashari/boilerplate-mcp-server/compare/v1.10.1...v1.10.2) (2025-05-21)
+
+
+### Bug Fixes
+
+* update dependencies ([1340085](https://github.com/aashari/boilerplate-mcp-server/commit/1340085d8476f92e72e7afe248a86f50e0b4ff84))
+
+## [1.10.1](https://github.com/aashari/boilerplate-mcp-server/compare/v1.10.0...v1.10.1) (2025-05-20)
+
+
+### Bug Fixes
+
+* update dependencies ([88fa27c](https://github.com/aashari/boilerplate-mcp-server/commit/88fa27c0e67d97a83d780f0aa99255979e139bb7))
+
 # [1.10.0](https://github.com/aashari/boilerplate-mcp-server/compare/v1.9.0...v1.10.0) (2025-05-19)
 
 

package/README.md

@@ -1,41 +1,30 @@
 # Boilerplate MCP Server
 
-This project serves as a foundation for developing custom Model Context Protocol (MCP) servers that connect AI assistants to external data sources or APIs. It provides a complete architecture pattern, a working example tool, and development infrastructure ready for extension.
+A foundation for developing custom Model Context Protocol (MCP) servers in TypeScript. Provides a complete layered architecture pattern, working example tools, and developer infrastructure to connect AI assistants with external APIs and data sources.
 
----
-
-# Overview
-
-## What is MCP?
-
-Model Context Protocol (MCP) is an open standard that allows AI systems to securely and contextually connect with external tools and data sources.
-
-This boilerplate implements the MCP specification with a clean, layered architecture that can be extended to build custom MCP servers for any API or data source.
+[![NPM Version](https://img.shields.io/npm/v/@aashari/boilerplate-mcp-server)](https://www.npmjs.com/package/@aashari/boilerplate-mcp-server)
+[![Build Status](https://img.shields.io/github/workflow/status/aashari/boilerplate-mcp-server/CI)](https://github.com/aashari/boilerplate-mcp-server/actions)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
 
 ## Why Use This Boilerplate?
 
-- **Production-Ready Architecture**: Follows the same pattern used in published MCP servers, with clear separation between CLI, tools, controllers, and services.
-
-- **Type Safety**: Built with TypeScript for improved developer experience, code quality, and maintainability.
-
-- **Working Example**: Includes a fully implemented IP lookup tool demonstrating the complete pattern from CLI to API integration.
+- **Production-Ready Architecture**: Follows the same pattern used in published MCP servers, with clean separation between CLI, tools, controllers, and services
+- **Type Safety**: Built with TypeScript for improved developer experience, code quality, and maintainability
+- **Working Example**: Includes fully implemented tools demonstrating the complete pattern from CLI to API integration
+- **Testing Framework**: Ready-to-use testing infrastructure for unit and CLI integration tests, with coverage reporting
+- **Complete Developer Tooling**: Pre-configured ESLint, Prettier, TypeScript, and CI/CD workflows
 
-- **Testing Framework**: Comes with testing infrastructure for both unit and CLI integration tests, including coverage reporting.
-
-- **Development Tooling**: Includes ESLint, Prettier, TypeScript, and other quality tools preconfigured for MCP server development.
-
----
+## What is MCP?
 
-# Getting Started
+Model Context Protocol (MCP) is an open standard for securely connecting AI systems to external tools and data sources. This boilerplate implements the MCP specification with a clean, layered architecture that can be extended to build custom MCP servers for any API or data source.
 
 ## Prerequisites
 
 - **Node.js** (>=18.x): [Download](https://nodejs.org/)
 - **Git**: For version control
 
----
-
-## Step 1: Clone and Install
+## Quick Start
 
 ```bash
 # Clone the repository
@@ -44,143 +33,139 @@ cd boilerplate-mcp-server
 
 # Install dependencies
 npm install
-```
-
----
 
-## Step 2: Run Development Server
-
-Start the server in development mode:
-
-```bash
+# Start development server
 npm run dev:server
-```
-
-This starts the MCP server with hot-reloading and enables the MCP Inspector at http://localhost:5173.
-
----
-
-## Step 3: Test the Example Tool
 
-Run the example IP lookup tool from the CLI:
-
-```bash
-# Using CLI in development mode
-npm run dev:cli -- get-ip-details
-
-# Or with a specific IP
+# Try the example tool
 npm run dev:cli -- get-ip-details 8.8.8.8
 ```
 
----
+## Architecture Overview
 
-# Architecture
-
-This boilerplate follows a clean, layered architecture pattern that separates concerns and promotes maintainability.
-
-## Project Structure
+<details>
+<summary><b>Project Structure (Click to expand)</b></summary>
 
 ```
 src/
 ├── cli/              # Command-line interfaces
+│   ├── index.ts      # CLI entry point
+│   └── *.cli.ts      # Feature-specific CLI modules
 ├── controllers/      # Business logic
+│   └── *.controller.ts  # Feature controllers
 ├── services/         # External API interactions
+│   └── *.service.ts  # Service modules
 ├── tools/            # MCP tool definitions
+│   ├── *.tool.ts     # Tool implementations
+│   └── *.types.ts    # Tool argument schemas
 ├── types/            # Type definitions
+│   └── common.types.ts # Shared type definitions
 ├── utils/            # Shared utilities
-└── index.ts          # Entry point
+│   ├── logger.util.ts  # Structured logging
+│   ├── error.util.ts   # Error handling
+│   └── ...           # Other utility modules
+└── index.ts          # Server entry point
 ```
 
-## Layers and Responsibilities
+</details>
+
+## Layered Architecture
 
-### CLI Layer (`src/cli/*.cli.ts`)
+The boilerplate follows a clean, layered architecture that promotes maintainability and clear separation of concerns:
 
-- **Purpose**: Define command-line interfaces that parse arguments and call controllers
-- **Naming**: Files should be named `<feature>.cli.ts`
-- **Testing**: CLI integration tests in `<feature>.cli.test.ts`
+### 1. CLI Layer (`src/cli/*.cli.ts`)
 
-### Tools Layer (`src/tools/*.tool.ts`)
+- **Purpose**: Command-line interfaces that parse arguments and call controllers
+- **Pattern**: Use `commander` for argument parsing, call controllers, handle errors with `handleCliError`
+- **Naming**: `<feature>.cli.ts` 
 
-- **Purpose**: Define MCP tools with schemas and descriptions for AI assistants
-- **Naming**: Files should be named `<feature>.tool.ts` with types in `<feature>.types.ts`
-- **Pattern**: Each tool should use zod for argument validation
+### 2. Tools Layer (`src/tools/*.tool.ts`)
 
-### Controllers Layer (`src/controllers/*.controller.ts`)
+- **Purpose**: MCP tool definitions exposed to AI assistants
+- **Pattern**: Use `zod` for schema validation, call controllers, format responses for MCP
+- **Naming**: `<feature>.tool.ts` with types in `<feature>.types.ts`
 
-- **Purpose**: Implement business logic, handle errors, and format responses
-- **Naming**: Files should be named `<feature>.controller.ts`
-- **Pattern**: Should return standardized `ControllerResponse` objects
+### 3. Controllers Layer (`src/controllers/*.controller.ts`)
 
-### Services Layer (`src/services/*.service.ts`)
+- **Purpose**: Business logic orchestration, error handling, response formatting
+- **Pattern**: Return standardized `ControllerResponse` objects, throw errors with context
+- **Naming**: `<feature>.controller.ts` with optional `<feature>.formatter.ts`
 
-- **Purpose**: Interact with external APIs or data sources
-- **Naming**: Files should be named `<feature>.service.ts`
-- **Pattern**: Pure API interactions with minimal logic
+### 4. Services Layer (`src/services/*.service.ts`)
 
-### Utils Layer (`src/utils/*.util.ts`)
+- **Purpose**: External API interactions and data handling
+- **Pattern**: Pure API calls with minimal logic, return raw data
+- **Naming**: `<feature>.service.ts` or `vendor.<vendor>.<feature>.service.ts`
 
-- **Purpose**: Provide shared functionality across the application
-- **Key Utils**:
-    - `logger.util.ts`: Structured logging
-    - `error.util.ts`: Error handling and standardization
-    - `formatter.util.ts`: Markdown formatting helpers
+### 5. Utils Layer (`src/utils/*.util.ts`)
 
----
+- **Purpose**: Shared functionality across the application
+- **Key Utils**: Logging, error handling, formatting, configuration
 
-# Development Guide
+## Developer Guide
 
-## Development Scripts
+### Development Scripts
 
 ```bash
-# Start server in development mode (hot-reload & inspector)
+# Start server in dev mode with hot-reload & inspector
 npm run dev:server
 
-# Run CLI in development mode
+# Run CLI commands in development
 npm run dev:cli -- [command] [args]
 
 # Build the project
 npm run build
 
-# Start server in production mode
+# Production server
+npm start
 npm run start:server
 
-# Run CLI in production mode
+# Production CLI
 npm run start:cli -- [command] [args]
-```
 
-## Testing
+# Testing
+npm test                    # Run all tests
+npm test -- src/path/to/test.ts  # Run specific tests
+npm run test:coverage       # Generate coverage report
 
-```bash
-# Run all tests
-npm test
+# Code Quality
+npm run lint                # Run ESLint
+npm run format              # Format with Prettier
+npm run typecheck           # Check TypeScript types
+```
 
-# Run specific tests
-npm test -- src/path/to/test.ts
+### Debugging Tools
 
-# Generate test coverage report
-npm run test:coverage
-```
+- **MCP Inspector**: Visual tool for testing your MCP tools
+  - Run server with `npm run dev:server`
+  - Open http://localhost:5173 in your browser
 
-## Code Quality
+- **Server Logs**: Enable with `DEBUG=true npm run dev:server` or in config
 
-```bash
-# Lint code
-npm run lint
+<details>
+<summary><b>Configuration (Click to expand)</b></summary>
 
-# Format code with Prettier
-npm run format
+Create `~/.mcp/configs.json`:
 
-# Check types
-npm run typecheck
+```json
+{
+  "boilerplate": {
+    "environments": {
+      "DEBUG": "true",
+      "ANY_OTHER_CONFIG": "value"
+    }
+  }
+}
 ```
 
----
+</details>
 
-# Building Custom Tools
+## Building Custom Tools
 
-Follow these steps to add your own tools to the server:
+<details>
+<summary><b>Step-by-Step Tool Implementation Guide (Click to expand)</b></summary>
 
-## 1. Define Service Layer
+### 1. Define Service Layer
 
 Create a new service in `src/services/` to interact with your external API:
 
@@ -197,7 +182,7 @@ export async function getData(param: string): Promise<any> {
 }
 ```
 
-## 2. Create Controller
+### 2. Create Controller
 
 Add a controller in `src/controllers/` to handle business logic:
 
@@ -236,7 +221,7 @@ export async function getData(
 }
 ```
 
-## 3. Implement MCP Tool
+### 3. Implement MCP Tool
 
 Create a tool definition in `src/tools/`:
 
@@ -284,7 +269,7 @@ Use this to fetch example data. Returns formatted data as Markdown.`,
 }
 ```
 
-## 4. Add CLI Support
+### 4. Add CLI Support
 
 Create a CLI command in `src/cli/`:
 
@@ -316,7 +301,7 @@ program
 	});
 ```
 
-## 5. Register Components
+### 5. Register Components
 
 Update the entry points to register your new components:
 
@@ -330,56 +315,39 @@ import exampleTool from './tools/example.tool.js';
 exampleTool.register(server);
 ```
 
----
-
-# Debugging Tools
-
-## MCP Inspector
-
-Access the visual MCP Inspector to test your tools and view request/response details:
-
-1. Run `npm run dev:server`
-2. Open http://localhost:5173 in your browser
-3. Test your tools and view logs directly in the UI
-
-## Server Logs
-
-Enable debug logs for development:
-
-```bash
-# Set environment variable
-DEBUG=true npm run dev:server
-
-# Or configure in ~/.mcp/configs.json
-```
-
----
+</details>
 
-# Publishing Your MCP Server
+## Publishing Your MCP Server
 
-When ready to publish your custom MCP server:
+1. Update package.json with your details:
+   ```json
+   {
+     "name": "your-mcp-server-name",
+     "version": "1.0.0",
+     "description": "Your custom MCP server",
+     "author": "Your Name",
+     // Other fields...
+   }
+   ```
 
-1. Update package.json with your details
 2. Update README.md with your tool documentation
-3. Build the project: `npm run build`
-4. Test the production build: `npm run start:server`
-5. Publish to npm: `npm publish`
+3. Build: `npm run build`
+4. Test: `npm run start:server`
+5. Publish: `npm publish`
+
+## Testing Best Practices
 
----
+- **Unit Tests**: Test utils and pure functions in isolation
+- **Controller Tests**: Test business logic with mocked service calls
+- **Integration Tests**: Test CLI with real dependencies
+- **Coverage Goal**: Aim for >80% test coverage
 
-# License
+## License
 
 [ISC License](https://opensource.org/licenses/ISC)
 
-```json
-{
-	"boilerplate": {
-		"environments": {
-			"DEBUG": "true",
-			"ANY_OTHER_CONFIG": "value"
-		}
-	}
-}
-```
+## Resources
 
-**Note:** For backward compatibility, the server will also recognize configurations under the full package name (`@aashari/boilerplate-mcp-server`) or the unscoped package name (`boilerplate-mcp-server`) if the `boilerplate` key is not found. However, using the short `boilerplate` key is recommended for new configurations.
+- [MCP Specification](https://github.com/modelcontextprotocol/mcp-spec)
+- [Official MCP Documentation](https://www.modelcontextprotocol.ai/)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.10.0",
+	"version": "1.10.2",
 	"description": "TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -60,7 +60,7 @@
 		"@semantic-release/github": "^11.0.2",
 		"@semantic-release/npm": "^12.0.1",
 		"@types/jest": "^29.5.14",
-		"@types/node": "^22.15.19",
+		"@types/node": "^22.15.21",
 		"@typescript-eslint/eslint-plugin": "^8.32.1",
 		"@typescript-eslint/parser": "^8.32.1",
 		"eslint": "^9.27.0",
@@ -84,7 +84,7 @@
 		"@modelcontextprotocol/sdk": "^1.11.4",
 		"commander": "^14.0.0",
 		"dotenv": "^16.5.0",
-		"zod": "^3.24.4"
+		"zod": "^3.25.13"
 	},
 	"directories": {
 		"example": "examples"

package/package.json.bak

@@ -1,6 +1,6 @@
 {
 	"name": "@aashari/boilerplate-mcp-server",
-	"version": "1.9.0",
+	"version": "1.10.1",
 	"description": "TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -60,7 +60,7 @@
 		"@semantic-release/github": "^11.0.2",
 		"@semantic-release/npm": "^12.0.1",
 		"@types/jest": "^29.5.14",
-		"@types/node": "^22.15.19",
+		"@types/node": "^22.15.21",
 		"@typescript-eslint/eslint-plugin": "^8.32.1",
 		"@typescript-eslint/parser": "^8.32.1",
 		"eslint": "^9.27.0",
@@ -84,7 +84,7 @@
 		"@modelcontextprotocol/sdk": "^1.11.4",
 		"commander": "^14.0.0",
 		"dotenv": "^16.5.0",
-		"zod": "^3.24.4"
+		"zod": "^3.25.13"
 	},
 	"directories": {
 		"example": "examples"