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

generic-mcp-template/
├── src/
│   ├── services/       # Service classes for API interactions
│   │   ├── base-service.ts        # Abstract base service with common functionality
│   │   └── example-service.ts     # Example service implementation
│   ├── tools/          # MCP tool definitions and handlers
│   │   ├── example-tools.ts       # Tool definitions (name, description, schema)
│   │   └── example-tool-handlers.ts # Tool handler implementations
│   ├── types/          # TypeScript type definitions
│   │   └── example-types.ts       # Example type definitions
│   ├── config.ts       # Configuration management
│   └── index.ts        # Main entry point
├── .env.example        # Example environment variables
├── package.json        # Project dependencies and scripts
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation

Getting Started

Prerequisites

Node.js 18 or higher
npm or yarn

Installation

Clone this repository:
git clone https://github.com/v4lheru/generic-mcp-template.git cd generic-mcp-template
Install dependencies:
npm install
Create a .env file based on .env.example:
cp .env.example .env
Edit the .env file with your API keys and configuration.

Building and Running

Build the project:
npm run build
Run the server:
npm start

Extending the Template

Adding a New Service

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... }
Add any necessary types in src/types/.

Adding New Tools

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 } } ];
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 } }; }
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

generic-mcp-server

Integrations