What is Generic Mcp Template

The generic-mcp-template is a modular and extensible Model Context Protocol (MCP) server template designed for easy customization and extension, providing a structured approach to building MCP servers.

Use cases

Use cases include building custom MCP servers for specific applications, integrating new tools and services into existing systems, and developing prototypes for testing and validation of MCP functionalities.

How to use

To use the generic-mcp-template, clone the repository, install the necessary dependencies, configure your environment variables in a .env file, and then build and run the project using Node.js.

Key features

Key features include a modular architecture for clear separation of concerns, small and focused files for better maintainability, easy extension points for adding new tools and services, comprehensive error handling, and full TypeScript support for type safety.

Where to use

The generic-mcp-template can be used in various fields that require a structured approach to developing APIs and services, particularly in software development and integration projects.

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

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