Generic MCP Server Template

A modular, extensible Model Context Protocol (MCP) server template designed for easy customization and extension.

Features

• Modular Architecture: Clear separation of concerns with a well-defined structure

• Small, Focused Files: Better maintainability and easier for AI to ingest

• Easy Extension Points: Simple patterns for adding new tools and services

• Comprehensive Error Handling: Robust error management throughout the codebase

• Type Safety: Full TypeScript support with proper typing

Project Structure

Getting Started

Prerequisites

• Node.js 18 or higher

• npm or yarn

Installation

1. Clone this repository:

   git clone https://github.com/v4lheru/generic-mcp-template.git cd generic-mcp-template

2. Install dependencies:

   npm install

3. Create a .env file based on .env.example:

   cp .env.example .env

4. Edit the .env file with your API keys and configuration.

Building and Running

1. Build the project:

   npm run build

2. Run the server:

   npm start

Extending the Template

Adding a New Service

1. Create a new service file in src/services/:

   // src/services/my-service.ts import { BaseService } from './base-service.js'; import config from '../config.js'; export class MyService extends BaseService { // Implement your service... }

2. Add any necessary types in src/types/.

Adding New Tools

1. Define your tools in a new file or extend the existing one in src/tools/:

   // src/tools/my-tools.ts export const myTools = [ { name: "my_tool", description: "Description of my tool", inputSchema: { // JSON Schema for the tool's input } } ];

2. Implement handlers for your tools:

   // src/tools/my-tool-handlers.ts import { MyService } from '../services/my-service.js'; export function createMyToolHandlers(myService: MyService) { return { my_tool: async (args: any) => { // Implement your tool handler } }; }

3. Register your tools and handlers in src/index.ts.

Configuration

The template uses a centralized configuration system in src/config.ts. Configuration can be provided through:

• Environment variables

• Command line arguments (with --env KEY=VALUE)

• Default values in the code

Error Handling

The template includes comprehensive error handling:

• Service-level error handling with rate limiting support

• Tool-level error handling with proper error messages

• MCP protocol error handling

License

MIT