@aashari/boilerplate-mcp-server 1.0.0

package/dist/utils/error.util.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpError = exports.ErrorType = void 0;
+exports.createAuthMissingError = createAuthMissingError;
+exports.createAuthInvalidError = createAuthInvalidError;
+exports.createApiError = createApiError;
+exports.createUnexpectedError = createUnexpectedError;
+exports.ensureMcpError = ensureMcpError;
+exports.formatErrorForMcpTool = formatErrorForMcpTool;
+exports.formatErrorForMcpResource = formatErrorForMcpResource;
+exports.handleCliError = handleCliError;
+const logger_util_js_1 = require("./logger.util.js");
+/**
+ * Error types for classification
+ */
+var ErrorType;
+(function (ErrorType) {
+    ErrorType["AUTH_MISSING"] = "AUTH_MISSING";
+    ErrorType["AUTH_INVALID"] = "AUTH_INVALID";
+    ErrorType["API_ERROR"] = "API_ERROR";
+    ErrorType["UNEXPECTED_ERROR"] = "UNEXPECTED_ERROR";
+})(ErrorType || (exports.ErrorType = ErrorType = {}));
+/**
+ * Custom error class with type classification
+ */
+class McpError extends Error {
+    constructor(message, type, statusCode, originalError) {
+        super(message);
+        this.name = 'McpError';
+        this.type = type;
+        this.statusCode = statusCode;
+        this.originalError = originalError;
+    }
+}
+exports.McpError = McpError;
+/**
+ * Create an authentication missing error
+ */
+function createAuthMissingError(message = 'Authentication credentials are missing') {
+    return new McpError(message, ErrorType.AUTH_MISSING);
+}
+/**
+ * Create an authentication invalid error
+ */
+function createAuthInvalidError(message = 'Authentication credentials are invalid') {
+    return new McpError(message, ErrorType.AUTH_INVALID, 401);
+}
+/**
+ * Create an API error
+ */
+function createApiError(message, statusCode, originalError) {
+    return new McpError(message, ErrorType.API_ERROR, statusCode, originalError);
+}
+/**
+ * Create an unexpected error
+ */
+function createUnexpectedError(message = 'An unexpected error occurred', originalError) {
+    return new McpError(message, ErrorType.UNEXPECTED_ERROR, undefined, originalError);
+}
+/**
+ * Ensure an error is an McpError
+ */
+function ensureMcpError(error) {
+    if (error instanceof McpError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return createUnexpectedError(error.message, error);
+    }
+    return createUnexpectedError(String(error));
+}
+/**
+ * Format error for MCP tool response
+ */
+function formatErrorForMcpTool(error) {
+    const mcpError = ensureMcpError(error);
+    logger_util_js_1.logger.error(`[src/utils/error.util.ts@formatErrorForMcpTool] ${mcpError.type} error`, mcpError);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Error: ${mcpError.message}`,
+            },
+        ],
+    };
+}
+/**
+ * Format error for MCP resource response
+ */
+function formatErrorForMcpResource(error, uri) {
+    const mcpError = ensureMcpError(error);
+    logger_util_js_1.logger.error(`[src/utils/error.util.ts@formatErrorForMcpResource] ${mcpError.type} error`, mcpError);
+    return {
+        contents: [
+            {
+                uri,
+                text: `Error: ${mcpError.message}`,
+                mimeType: 'text/plain',
+                description: `Error: ${mcpError.type}`,
+            },
+        ],
+    };
+}
+/**
+ * Handle error in CLI context
+ */
+function handleCliError(error) {
+    const mcpError = ensureMcpError(error);
+    logger_util_js_1.logger.error(`[src/utils/error.util.ts@handleCliError] ${mcpError.type} error`, mcpError);
+    console.error(`Error: ${mcpError.message}`);
+    process.exit(1);
+}

package/dist/utils/error.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/logger.util.d.ts

@@ -0,0 +1,9 @@
+declare class Logger {
+    _log(level: 'info' | 'warn' | 'error' | 'debug', message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+export declare const logger: Logger;
+export {};

package/dist/utils/logger.util.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/**
+ * Format a timestamp for logging
+ * @returns Formatted timestamp [HH:MM:SS]
+ */
+function getTimestamp() {
+    const now = new Date();
+    return `[${now.toISOString().split('T')[1].split('.')[0]}]`;
+}
+class Logger {
+    _log(level, message, ...args) {
+        // Skip debug messages if DEBUG is not set to true
+        if (level === 'debug' && process.env.DEBUG !== 'true') {
+            return;
+        }
+        const timestamp = getTimestamp();
+        const prefix = `${timestamp} [${level.toUpperCase()}]`;
+        let logMessage = `${prefix} ${message}`;
+        if (args.length > 0) {
+            logMessage += ` ${args.map((arg) => JSON.stringify(arg)).join(' ')}`;
+        }
+        if (process.env.NODE_ENV === 'test') {
+            console[level](logMessage);
+        }
+        else {
+            console.error(logMessage);
+        }
+    }
+    info(message, ...args) {
+        this._log('info', message, ...args);
+    }
+    warn(message, ...args) {
+        this._log('warn', message, ...args);
+    }
+    error(message, ...args) {
+        this._log('error', message, ...args);
+    }
+    debug(message, ...args) {
+        this._log('debug', message, ...args);
+    }
+}
+exports.logger = new Logger();

package/eslint.config.mjs

@@ -0,0 +1,46 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import prettierPlugin from 'eslint-plugin-prettier';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default tseslint.config(
+	{
+		ignores: ['node_modules/**', 'dist/**', 'examples/**'],
+	},
+	eslint.configs.recommended,
+	...tseslint.configs.recommended,
+	{
+		plugins: {
+			prettier: prettierPlugin,
+		},
+		rules: {
+			'prettier/prettier': 'error',
+			indent: ['error', 'tab', { SwitchCase: 1 }],
+			'@typescript-eslint/no-unused-vars': [
+				'error',
+				{ argsIgnorePattern: '^_' },
+			],
+		},
+		languageOptions: {
+			parserOptions: {
+				ecmaVersion: 'latest',
+				sourceType: 'module',
+			},
+			globals: {
+				node: 'readonly',
+				jest: 'readonly',
+			},
+		},
+	},
+	// Special rules for test files
+	{
+		files: ['**/*.test.ts'],
+		rules: {
+			'@typescript-eslint/no-explicit-any': 'off',
+			'@typescript-eslint/no-require-imports': 'off',
+			'@typescript-eslint/no-unsafe-function-type': 'off',
+			'@typescript-eslint/no-unused-vars': 'off',
+		},
+	},
+	eslintConfigPrettier,
+);

package/jest.config.mjs

@@ -0,0 +1,19 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+export default {
+	preset: 'ts-jest',
+	testEnvironment: 'node',
+	testMatch: ['**/src/**/*.test.ts'],
+	transform: {
+		'^.+\\.tsx?$': [
+			'ts-jest',
+			{
+				useESM: true,
+			},
+		],
+	},
+	moduleNameMapper: {
+		'(.*)\\.(js|jsx)$': '$1',
+	},
+	extensionsToTreatAsEsm: ['.ts'],
+	moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+};

package/package.json

@@ -0,0 +1,88 @@
+{
+	"name": "@aashari/boilerplate-mcp-server",
+	"version": "1.0.0",
+	"description": "A TypeScript-based Model Context Protocol (MCP) server boilerplate for building AI-connected tools. Features IP lookup tools, CLI support, MCP Inspector integration, and extensible architecture for connecting Claude/Anthropic AI systems to external data sources.",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"type": "commonjs",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aashari/boilerplate-mcp-server.git"
+	},
+	"bin": {
+		"mcp-server": "./dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"test": "jest",
+		"test:coverage": "jest --coverage",
+		"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",
+		"start": "node dist/index.js",
+		"dev": "nodemon --watch src --ext ts --exec 'npm run build && npm start'",
+		"inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+		"inspect:debug": "npx @modelcontextprotocol/inspector -e DEBUG=true node dist/index.js"
+	},
+	"keywords": [
+		"mcp",
+		"typescript",
+		"claude",
+		"anthropic",
+		"ai",
+		"boilerplate",
+		"server",
+		"model-context-protocol",
+		"tools",
+		"resources",
+		"tooling",
+		"ai-integration",
+		"mcp-server",
+		"llm",
+		"ai-connector",
+		"external-tools",
+		"cli",
+		"mcp-inspector"
+	],
+	"author": "",
+	"license": "ISC",
+	"devDependencies": {
+		"@eslint/js": "^9.23.0",
+		"@semantic-release/changelog": "^6.0.3",
+		"@semantic-release/exec": "^7.0.3",
+		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^11.0.1",
+		"@semantic-release/npm": "^12.0.1",
+		"@types/jest": "^29.5.14",
+		"@types/node": "^22.13.11",
+		"@typescript-eslint/eslint-plugin": "^8.27.0",
+		"@typescript-eslint/parser": "^8.27.0",
+		"eslint": "^9.23.0",
+		"eslint-config-prettier": "^10.1.1",
+		"eslint-plugin-prettier": "^5.2.3",
+		"jest": "^29.7.0",
+		"nodemon": "^3.1.9",
+		"npm-check-updates": "^17.1.16",
+		"prettier": "^3.5.3",
+		"semantic-release": "^24.2.3",
+		"ts-jest": "^29.2.6",
+		"typescript": "^5.8.2",
+		"typescript-eslint": "^8.27.0"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/",
+		"access": "public"
+	},
+	"dependencies": {
+		"commander": "^13.1.0",
+		"@modelcontextprotocol/sdk": "^1.7.0",
+		"dotenv": "^16.4.7",
+		"zod": "^3.24.2"
+	},
+	"directories": {
+		"example": "examples"
+	}
+}

package/package.json.bak

@@ -0,0 +1,88 @@
+{
+	"name": "@aashari/boilerplate-mcp-server",
+	"version": "1.1.0",
+	"description": "A TypeScript-based Model Context Protocol (MCP) server boilerplate for building AI-connected tools. Features IP lookup tools, CLI support, MCP Inspector integration, and extensible architecture for connecting Claude/Anthropic AI systems to external data sources.",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"type": "commonjs",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aashari/boilerplate-mcp-server.git"
+	},
+	"bin": {
+		"mcp-server": "./dist/index.js"
+	},
+	"scripts": {
+		"build": "tsc",
+		"test": "jest",
+		"test:coverage": "jest --coverage",
+		"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",
+		"start": "node dist/index.js",
+		"dev": "nodemon --watch src --ext ts --exec 'npm run build && npm start'",
+		"inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+		"inspect:debug": "npx @modelcontextprotocol/inspector -e DEBUG=true node dist/index.js"
+	},
+	"keywords": [
+		"mcp",
+		"typescript",
+		"claude",
+		"anthropic",
+		"ai",
+		"boilerplate",
+		"server",
+		"model-context-protocol",
+		"tools",
+		"resources",
+		"tooling",
+		"ai-integration",
+		"mcp-server",
+		"llm",
+		"ai-connector",
+		"external-tools",
+		"cli",
+		"mcp-inspector"
+	],
+	"author": "",
+	"license": "ISC",
+	"devDependencies": {
+		"@eslint/js": "^9.23.0",
+		"@semantic-release/changelog": "^6.0.3",
+		"@semantic-release/exec": "^7.0.3",
+		"@semantic-release/git": "^10.0.1",
+		"@semantic-release/github": "^11.0.1",
+		"@semantic-release/npm": "^12.0.1",
+		"@types/jest": "^29.5.14",
+		"@types/node": "^22.13.11",
+		"@typescript-eslint/eslint-plugin": "^8.27.0",
+		"@typescript-eslint/parser": "^8.27.0",
+		"eslint": "^9.23.0",
+		"eslint-config-prettier": "^10.1.1",
+		"eslint-plugin-prettier": "^5.2.3",
+		"jest": "^29.7.0",
+		"nodemon": "^3.1.9",
+		"npm-check-updates": "^17.1.16",
+		"prettier": "^3.5.3",
+		"semantic-release": "^24.2.3",
+		"ts-jest": "^29.2.6",
+		"typescript": "^5.8.2",
+		"typescript-eslint": "^8.27.0"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/",
+		"access": "public"
+	},
+	"dependencies": {
+		"commander": "^13.1.0",
+		"@modelcontextprotocol/sdk": "^1.7.0",
+		"dotenv": "^16.4.7",
+		"zod": "^3.24.2"
+	},
+	"directories": {
+		"example": "examples"
+	}
+}

package/scripts/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+} 

package/scripts/update-version.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+
+/**
+ * Script to update version numbers across the project
+ * Usage: node scripts/update-version.js [version] [options]
+ * Options:
+ *   --dry-run   Show what changes would be made without applying them
+ *   --verbose   Show detailed logging information
+ *
+ * If no version is provided, it will use the version from package.json
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Get the directory name of the current module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '..');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const options = {
+	dryRun: args.includes('--dry-run'),
+	verbose: args.includes('--verbose'),
+};
+
+// Get the version (first non-flag argument)
+let newVersion = args.find((arg) => !arg.startsWith('--'));
+
+// Log helper function
+const log = (message, verbose = false) => {
+	if (!verbose || options.verbose) {
+		console.log(message);
+	}
+};
+
+// File paths that may contain version information
+const versionFiles = [
+	{
+		path: path.join(rootDir, 'package.json'),
+		pattern: /"version": "([^"]*)"/,
+		replacement: (match, currentVersion) =>
+			match.replace(currentVersion, newVersion),
+	},
+	{
+		path: path.join(rootDir, 'src', 'cli', 'index.ts'),
+		pattern: /const VERSION = ['"]([^'"]*)['"]/,
+		replacement: (match, currentVersion) =>
+			match.replace(currentVersion, newVersion),
+	},
+	{
+		path: path.join(rootDir, 'src', 'index.ts'),
+		pattern: /version: ['"]([^'"]*)['"]/,
+		replacement: (match, currentVersion) =>
+			match.replace(currentVersion, newVersion),
+	},
+	// Also update the compiled JavaScript files if they exist
+	{
+		path: path.join(rootDir, 'dist', 'cli', 'index.js'),
+		pattern: /const VERSION = ['"]([^'"]*)['"]/,
+		replacement: (match, currentVersion) =>
+			match.replace(currentVersion, newVersion),
+	},
+	{
+		path: path.join(rootDir, 'dist', 'index.js'),
+		pattern: /version: ['"]([^'"]*)['"]/,
+		replacement: (match, currentVersion) =>
+			match.replace(currentVersion, newVersion),
+	},
+	// Additional files can be added here with their patterns and replacement logic
+];
+
+/**
+ * Read the version from package.json
+ * @returns {string} The version from package.json
+ */
+function getPackageVersion() {
+	try {
+		const packageJsonPath = path.join(rootDir, 'package.json');
+		log(`Reading version from ${packageJsonPath}`, true);
+
+		const packageJson = JSON.parse(
+			fs.readFileSync(packageJsonPath, 'utf8'),
+		);
+
+		if (!packageJson.version) {
+			throw new Error('No version field found in package.json');
+		}
+
+		return packageJson.version;
+	} catch (error) {
+		console.error(`Error reading package.json: ${error.message}`);
+		process.exit(1);
+	}
+}
+
+/**
+ * Validate the semantic version format
+ * @param {string} version - The version to validate
+ * @returns {boolean} True if valid, throws error if invalid
+ */
+function validateVersion(version) {
+	// More comprehensive semver regex
+	const semverRegex =
+		/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+	if (!semverRegex.test(version)) {
+		throw new Error(
+			`Invalid version format: ${version}\nPlease use semantic versioning format (e.g., 1.2.3, 1.2.3-beta.1, etc.)`,
+		);
+	}
+
+	return true;
+}
+
+/**
+ * Update version in a specific file
+ * @param {Object} fileConfig - Configuration for the file to update
+ */
+function updateFileVersion(fileConfig) {
+	const { path: filePath, pattern, replacement } = fileConfig;
+
+	try {
+		log(`Checking ${filePath}...`, true);
+
+		if (!fs.existsSync(filePath)) {
+			console.warn(`Warning: File not found: ${filePath}`);
+			return;
+		}
+
+		// Read file content
+		const fileContent = fs.readFileSync(filePath, 'utf8');
+		const match = fileContent.match(pattern);
+
+		if (!match) {
+			console.warn(`Warning: Version pattern not found in ${filePath}`);
+			return;
+		}
+
+		const currentVersion = match[1];
+		if (currentVersion === newVersion) {
+			log(
+				`Version in ${path.basename(filePath)} is already ${newVersion}`,
+				true,
+			);
+			return;
+		}
+
+		// Create new content with the updated version
+		const updatedContent = fileContent.replace(pattern, replacement);
+
+		// Write the changes or log them in dry run mode
+		if (options.dryRun) {
+			log(
+				`Would update version in ${filePath} from ${currentVersion} to ${newVersion}`,
+			);
+		} else {
+			// Create a backup of the original file
+			fs.writeFileSync(`${filePath}.bak`, fileContent);
+			log(`Backup created: ${filePath}.bak`, true);
+
+			// Write the updated content
+			fs.writeFileSync(filePath, updatedContent);
+			log(
+				`Updated version in ${path.basename(filePath)} from ${currentVersion} to ${newVersion}`,
+			);
+		}
+	} catch (error) {
+		console.error(`Error updating ${filePath}: ${error.message}`);
+		process.exit(1);
+	}
+}
+
+// Main execution
+try {
+	// If no version specified, get from package.json
+	if (!newVersion) {
+		newVersion = getPackageVersion();
+		log(
+			`No version specified, using version from package.json: ${newVersion}`,
+		);
+	}
+
+	// Validate the version format
+	validateVersion(newVersion);
+
+	// Update all configured files
+	for (const fileConfig of versionFiles) {
+		updateFileVersion(fileConfig);
+	}
+
+	if (options.dryRun) {
+		log(`\nDry run completed. No files were modified.`);
+	} else {
+		log(`\nVersion successfully updated to ${newVersion}`);
+	}
+} catch (error) {
+	console.error(`\nVersion update failed: ${error.message}`);
+	process.exit(1);
+}