Generic MCP Server Template

🚀 Generic MCP Server Template

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

✨ Features

• Modular Architecture: Clear separation of concerns and a well - defined structure.
• Small, Focused Files: Better maintainability and easier for AI to consume.
• Simple Extension Points: A straightforward pattern for adding new tools and services.
• Comprehensive Error Handling: Robust error management throughout the codebase.
• Type Safety: Full TypeScript support with appropriate types.

📁 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 implementation
│   ├── 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

🚀 Quick Start

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 own API keys and configuration.

Build and Run

1. Build the project:

   npm run build
   

2. Start the server:

   npm start
   

💻 Usage Examples

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 a New Tool

1. Define your tool in src/tools/ or extend an existing file:

   // src/tools/my-tools.ts
   export const myTools = [
       {
           name: "my_tool",
           description: "My tool description",
           inputSchema: {
               // JSON schema for tool input
           }
       }
   ];
   

2. Implement the tool handler:

   // 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 tool and handler in src/index.ts.

🛠️ Configuration

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

• Environment variables
• Command - line arguments (with --env KEY=VALUE)
• Default values in the code

🔧 Technical Details

The template includes comprehensive error handling:

• Service - level error handling with rate - limit support.
• Tool - level error handling with proper error messages.
• MCP protocol error handling.

📄 License

MIT