General MCP Server Template

A reusable template and framework for building Model Context Protocol (MCP) servers with TypeScript, MongoDB, and Typesense integration.

Features

• 🚀 Quick Setup: Create new MCP servers in seconds
• 📦 Production Ready: Includes logging, error handling, and graceful shutdown
• 🔧 TypeScript: Full TypeScript support with proper type definitions
• 🗄️ Database Integration: MongoDB and Typesense support out of the box
• 🛠️ Tool Framework: Easy-to-use tool creation and management
• 📝 Resource Management: Built-in resource listing and reading capabilities
• 🤖 Prompt System: Template-based prompt management
• 🔒 Environment Configuration: Secure environment variable handling

Installation

Global Installation (Recommended)

npm install -g general-mcp-server-template

Local Installation

npm install general-mcp-server-template

Usage

Create a New MCP Server

# Using global installation
create-mcp-server my-new-server

# Using npx
npx general-mcp-server-template my-new-server

Available Options

create-mcp-server <project-name> [options]

Options:
  -t, --template <template>  Template type (default: basic)
  -y, --yes                  Skip prompts and use defaults
  -h, --help                 Display help information
  -V, --version              Display version information

Project Structure

my-new-server/
├── src/
│   ├── tools/           # MCP tools implementation
│   ├── utils/           # Utility functions
│   ├── resources/       # Resource definitions
│   ├── prompts/         # Prompt templates
│   └── index.ts         # Main server entry point
├── dist/                # Compiled JavaScript (generated)
├── logs/                # Application logs (generated)
├── data/                # Data files (generated)
├── package.json         # Project dependencies
├── tsconfig.json        # TypeScript configuration
├── .env                 # Environment variables (create this)
└── README.md           # Project documentation

Development

Prerequisites

• Node.js >= 18.0.0
• MongoDB (for data storage)
• Typesense (for search functionality)

Environment Setup

Create a .env file in your project root:

# Server Configuration
NODE_ENV=development
PORT=3000

# MongoDB Configuration
MONGO_URI=mongodb://localhost:27017/your_database

# Typesense Configuration
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=your_api_key

# Company Configuration
COMPANY_NAME=Your Company Name

Available Scripts

# Development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Install dependencies and setup
npm install

Creating Custom Tools

1. Define Tool Schema

Create a new file in src/tools/:

// src/tools/myTool.ts
import { Tool } from '../types/index.js';

export const myToolSchema: Tool = {
  name: 'my_tool',
  description: 'Description of what this tool does',
  inputSchema: {
    type: 'object',
    properties: {
      parameter1: {
        type: 'string',
        description: 'Description of parameter1'
      }
    },
    required: ['parameter1']
  }
};

2. Implement Tool Handler

// src/tools/myToolHandler.ts
import { logger } from '../index.js';

export async function handleMyTool(args: any) {
  try {
    logger.info('Executing my tool with args:', args);
    
    // Your tool logic here
    const result = await processMyTool(args.parameter1);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result)
        }
      ]
    };
  } catch (error) {
    logger.error('Error in my tool:', error);
    throw error;
  }
}

3. Register Tool

Add to src/tools/index.ts:

import { myToolSchema } from './myTool.js';
import { handleMyTool } from './myToolHandler.js';

export const toolDefinitions = [
  // ... other tools
  myToolSchema
];

export const toolHandlers = {
  // ... other handlers
  my_tool: handleMyTool
};

Creating Resources

1. Define Resource Schema

// src/resources/myResource.ts
export const myResourceSchema = {
  uri: 'my-resource://data',
  name: 'My Resource',
  description: 'Description of the resource',
  mimeType: 'application/json'
};

2. Implement Resource Handler

// src/resources/myResourceHandler.ts
export async function readMyResource(uri: string) {
  // Fetch or generate resource data
  const data = await fetchResourceData(uri);
  
  return {
    contents: [
      {
        uri,
        mimeType: 'application/json',
        text: JSON.stringify(data)
      }
    ]
  };
}

Creating Prompts

1. Define Prompt Template

// src/prompts/myPrompt.ts
export const myPromptTemplate = {
  name: 'my_prompt',
  description: 'Description of the prompt',
  arguments: {
    type: 'object',
    properties: {
      variable1: {
        type: 'string',
        description: 'Description of variable1'
      }
    },
    required: ['variable1']
  },
  prompt: 'This is a prompt template with {{variable1}} placeholder.'
};

Publishing Your MCP Server

1. Build the Project

npm run build

2. Test Your Server

# Test with MCP Inspector
DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector node dist/index.js

3. Publish to npm

npm publish

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• GitHub Issues: Report bugs or request features
• Documentation: Full documentation

Changelog

v1.0.0

• Initial release
• Basic MCP server template
• MongoDB and Typesense integration
• Tool and resource framework
• TypeScript support