Boilerplate MCP Server: Seamless Integration for AI Applications

Overview: What is Boilerplate MCP Server?

Boilerplate MCP Server serves as a foundational framework for developers looking to integrate Model Context Protocol (MCP) into their AI applications, facilitating secure and seamless connections between AI assistants and external data sources or APIs. Built on a clean, layered architecture pattern, this server not only adheres to the MCP standard but also offers a comprehensive set of tools and infrastructure designed for extensibility.

🔧 Core Features & MCP Capabilities

The Boilerplate MCP Server excels in providing robust and production-ready architecture that adheres closely to the same design used in published MCP servers. Key features include:

• Production-Ready Architecture: The server follows a structured and layered design, ensuring clear separation between CLI, tools, controllers, and services.
• Type Safety & Maintainability: Developed with TypeScript for improved code quality, maintainability, and an enhanced developer experience.
• Comprehensive Documentation & Example Tools: Comes with detailed documentation and a fully implemented IP lookup tool that demonstrates the complete pattern from CLI to API integration.
• Testing Infrastructure: Offers both unit and CLI integration tests, with full coverage reporting to ensure robustness.
• Development Tooling: Includes essential tools such as ESLint, Prettier, TypeScript for setting up a development environment conducive to MCP server development.

⚙️ MCP Architecture & Protocol Implementation

The Boilerplate MCP Server is built around a clean, layered architecture that ensures maintainability and ease of extension. Key layers include:

• CLI Layer: Defined in src/cli/*.cli.ts, responsible for command-line interfaces that parse arguments and call controllers.
• Tools Layer: Located in src/tools/*.tool.ts, defines MCP tools with schemas and descriptions, leveraging zod for argument validation.
• Controllers Layer: In src/controllers/*.controller.ts, implements business logic, handles errors, and formats responses using standardized ControllerResponse objects.
• Services Layer: Found in src/services/*.service.ts, interacts with external APIs or data sources while maintaining minimalistic API interactions.
• Utils Layer: Provides shared functionality across the application through files like logger.util.ts, error.util.ts, and formatter.util.ts.

🚀 Getting Started with Installation

To start using the Boilerplate MCP Server, follow these steps:

Prerequisites

• Node.js (≥18.x): Download from nodejs.org
• Git: For version control.

Step 1: Clone and Install

# Clone the repository
git clone https://github.com/aashari/boilerplate-mcp-server.git
cd boilerplate-mcp-server

# Install dependencies
npm install

Step 2: Run Development Server

Start the server in development mode:

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:

# Using CLI in development mode
npm run dev:cli -- get-ip-details

# Or with a specific IP
npm run dev:cli -- get-ip-details 8.8.8.8

💡 Key Use Cases in AI Workflows

Use Case 1: Real-Time Weather Data for Personal Assistant

In this scenario, the Boilerplate MCP Server is used to fetch real-time weather data from an external API and provide it as a tool within Claude Desktop. The server handles authentication, query parsing, API interaction, and response formatting.

Technical Implementation:

• Service Layer: Interaction with the OpenWeatherMap API.
• Controller Layer: Business logic for fetching and processing weather data.
• Tool Layer: Defines the MCP tool schema and descriptions.

// src/services/weather.service.ts
import { Logger } from '../utils/logger.util.js';

const logger = Logger.forContext('services/weather.service.ts');

export async function retrieveWeatherData(zipCode: string): Promise<any> {
	logger.debug(`Retrieving weather data for ${zipCode}`);
	// API interaction code here
	return { data: 'example weather data' };
}

// src/controllers/weather.controller.ts
import { Logger } from '../utils/logger.util.js';
import * as weatherService from '../services/weather.service.js';
import { z } from 'zod';
import { ControllerResponse } from '../types/common.types.js';

const logger = Logger.forContext('controllers/weather.controller.ts');

export type WeatherDataOptions = {
	zipCode: string;
};

async function getWeatherData(options: WeatherDataOptions): Promise<ControllerResponse> {
	try {
		logger.debug(`Getting weather data for ${options.zipCode}`);
		const weatherData = await weatherService.retrieveWeatherData(options.zipCode);
		return { content: [weatherData] };
	} catch (error) {
		logger.error(error);
		return {
			success: false,
			message: 'Failed to fetch weather data',
		};
	}
}

// src/tools/weather.tool.ts
import { z } from 'zod';

export const getWeatherDataTool = z.object({
	zipCode: z.string(),
});

Use Case 2: Custom Task Automation for Project Management

This use case involves integrating custom tasks such as email notifications and task reminders within an AI system like Continue. The server handles the automation workflow, interacting with external tools and systems.

Technical Implementation:

• Service Layer: Interaction with email services (e.g., SendGrid) and reminder tools.
• Controller Layer: Business logic for scheduling and executing tasks.
• Tool Layer: Defines the MCP tool schema and descriptions.

// src/services/task.service.ts
import { Logger } from '../utils/logger.util.js';

const logger = Logger.forContext('services/task.service.ts');

export async function sendEmailNotification(to: string, subject: string, body: string): Promise<any> {
	logger.debug(`Sending email to ${to}`);
	// API interaction code here
}

// src/controllers/task.controller.ts
import { Logger } from '../utils/logger.util.js';
import * as taskService from '../services/weather.service.js';
import { z } from 'zod';
import { ControllerResponse } from '../types/common.types.js';

const logger = Logger.forContext('controllers/task.controller.ts');

export type NotificationOptions = {
	to: string;
	subject: string;
	body: string;
};

async function triggerNotification(options: NotificationOptions): Promise<ControllerResponse> {
	try {
		logger.debug(`Triggering notification to ${options.to}`);
		await taskService.sendEmailNotification(options.to, options.subject, options.body);
		return { success: true };
	} catch (error) {
		logger.error(error);
		return { success: false, message: 'Failed to send email' };
	}
}

// src/tools/notification.tool.ts
import { z } from 'zod';

export const sendNotificationTool = z.object({
	to: z.string(),
	subject: z.string(),
	body: z.string(),
});

🔌 Integration with MCP Clients

The Boilerplate MCP Server is compatible with several popular MCP clients, including:

• Claude Desktop: Full support for AI tool integration.
• Continue: Compatible with most tools and prompt functionalities.
• Cursor: Tool integration supported but limited in functionalities.

MCP Client	Resources	Tools	Prompts	Status
Claude Desktop	✅	✅	✅	Full Support
Continue	✅	✅	❌	Limited Tool Integration
Cursor	❌	✅	❌	No Prompt or Resource Support

📊 Performance & Compatibility Matrix

The Boilerplate MCP Server is designed for efficiency and reliability, ensuring seamless performance across a wide range of AI applications.

Compatibility:

• AI Application: Claude Desktop, Continue, Cursor
• Tool Support: Fully integrated with most tools.
• Prompt Integration: Limited support in some clients but robust in others.

🛠️ Advanced Configuration & Security

To configure the Boilerplate MCP Server, use the following steps:

1. Set Environment Variables:

   DEBUG=true npm run dev:server
   

2. Configure in ~/.mcp/configs.json:

{
  "mcpServers": {
    "[server-name]": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-[name]"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

❓ Frequently Asked Questions (FAQ)

Q1: How does the Boilerplate MCP Server ensure data security?

The Boilerplate MCP Server leverages environment variables and secure authentication mechanisms to protect sensitive information, ensuring that only authorized clients can interact with the server.

Q2: Can I use this server for multiple AI applications simultaneously?

Yes, by configuring multiple instances of the server in ~/.mcp/configs.json, you can manage connections for different AI applications seamlessly.

Q3: Are there any known compatibility issues with specific MCP clients?

While the Boilerplate MCP Server is generally compatible with most clients, some have limited support due to the nature of their APIs and functionalities.

Q4: How do I test my custom tools within the server?

You can test your custom tools using the MCP Inspector available at http://localhost:5173. This allows you to view logs and debug interactions directly in the user interface.

Q5: Can I run the development environment on Kubernetes?

Yes, you can deploy the Boilerplate MCP Server on Kubernetes by creating a Docker image and configuring the necessary Kubernetes resources like Deployment and Service configurations.

👨‍💻 Development & Contribution Guidelines

Contributions are welcome from developers aiming to expand MCP server capabilities. To contribute:

1. Fork the repository.
2. Run npm install to set up dependencies.
3. Make your changes and ensure all tests pass.
4. Commit and push changes back to GitHub.
5. Create a pull request for review.

🌐 MCP Ecosystem & Resources

For more information on Model Context Protocol and its ecosystem, refer to the official documentation:

• Official Documentation: ModelContextProtocol.org
• Community Forum: Join the community discussions and collaborate with other developers.
• GitHub Repository: For source code and issues: https://github.com/aashari/boilerplate-mcp-server

By using this server, developers can significantly enhance the capabilities of their AI applications through standardized MCP integration.