knoxmcken/mcp-project-template

MCP Server Project Template

A comprehensive template for developing Model Context Protocol (MCP) servers with best practices, extensive documentation, and modern project management.

🚀 Quick Start

# Clone this template
git clone <your-repo-url>
cd mcp-server-project

# Install dependencies
npm install

# Set up development environment
npm run setup

# Start development server
npm run dev

# Run tests
npm test

💡 New to this template? Check out our detailed for step-by-step instructions!

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Development
• Testing
• Deployment
• Contributing
• Architecture
• API Documentation
• Troubleshooting
• License

🎯 Overview

This project implements a Model Context Protocol (MCP) server that provides [describe your server's functionality here]. The MCP enables AI assistants to securely access external data sources and tools through a standardized protocol.

What is MCP?

The Model Context Protocol is an open protocol that enables secure connections between AI assistants and external data sources. It provides:

• Standardized Communication: Common protocol for AI-data source interactions
• Security: Built-in authentication and authorization mechanisms
• Extensibility: Plugin architecture for custom data sources
• Type Safety: Strong typing for reliable integrations

✨ Features

• 🔌 Plugin Architecture: Extensible design for custom data sources
• 🔒 Security First: Built-in authentication and authorization
• 📊 Comprehensive Logging: Structured logging with multiple levels
• 🧪 Test Coverage: Comprehensive unit and integration tests
• 📖 API Documentation: Auto-generated OpenAPI/Swagger docs
• 🔄 Hot Reload: Development server with automatic reloading
• 📈 Monitoring: Health checks and metrics endpoints
• 🐳 Docker Support: Containerized deployment ready
• 🚀 CI/CD Ready: GitHub Actions workflows included

🔧 Prerequisites

• Node.js: v18.0.0 or higher
• npm: v8.0.0 or higher
• Git: v2.30.0 or higher
• Docker: v20.0.0 or higher (for containerized deployment)

📦 Installation

Development Setup

1. Clone the repository

   git clone <your-repo-url>
   cd mcp-server-project
   

2. Install dependencies

   npm install
   

3. Set up environment

   cp .env.example .env
   # Edit .env with your configuration
   

4. Initialize the project

   npm run setup
   

Production Setup

See for detailed production setup instructions.

⚙️ Configuration

Configuration is managed through environment variables and config files:

• Environment Variables: See
• Config Files: Located in
• Schema Validation: All configurations are validated at startup

Key Configuration Options

See for complete details.

🛠️ Development

Available Scripts

# Development
npm run dev          # Start development server with hot reload
npm run dev:debug    # Start with debugger enabled
npm run dev:watch    # Start with file watching

# Building
npm run build        # Build for production
npm run build:dev    # Build for development

# Testing
npm test             # Run all tests
npm run test:unit    # Run unit tests only
npm run test:integration # Run integration tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage

# Code Quality
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint issues
npm run format       # Format code with Prettier
npm run typecheck    # Run TypeScript type checking

# Documentation
npm run docs:build   # Build documentation
npm run docs:serve   # Serve documentation locally

# Maintenance
npm run clean        # Clean build artifacts
npm run reset        # Reset node_modules and reinstall

Development Workflow

1. Create a feature branch

   git checkout -b feature/your-feature-name
   

2. Make your changes

   • Follow the
   • Write tests for new functionality
   • Update documentation as needed

3. Test your changes

   npm run test
   npm run lint
   npm run typecheck
   

4. Commit your changes

   git add .
   git commit -m "feat: add your feature description"
   

5. Push and create PR

   git push origin feature/your-feature-name
   

🧪 Testing

We maintain comprehensive test coverage across multiple levels:

Test Types

• Unit Tests: Test individual components in isolation
• Integration Tests: Test component interactions
• End-to-End Tests: Test complete workflows
• Performance Tests: Test performance characteristics

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Writing Tests

See for detailed testing guidelines and examples.

🚀 Deployment

Docker Deployment

# Build image
docker build -t mcp-server .

# Run container
docker run -p 3000:3000 mcp-server

Production Deployment

See for:

• Environment setup
• SSL configuration
• Load balancing
• Monitoring setup
• Backup strategies

🤝 Contributing

We welcome contributions! Please see our for details.

Quick Contribution Steps

1. Fork the repository
2. Create your feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Development Standards

• Follow
• Write comprehensive tests
• Document your code
• Follow our

🏗️ Architecture

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Assistant  │    │   MCP Server    │    │  Data Sources   │
│                 │◄──►│                 │◄──►│                 │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Core Components

• Protocol Handler: Manages MCP protocol communication
• Authentication: Handles client authentication and authorization
• Data Adapters: Interfaces with external data sources
• Plugin System: Extensible architecture for custom functionality

See for detailed information.

📚 API Documentation

• Interactive API Docs: Available at /docs when server is running
• OpenAPI Spec: Available at /api/openapi.json
• Protocol Documentation: See

🔍 Troubleshooting

Common Issues

See for more details.

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Model Context Protocol for the protocol specification
• Anthropic for MCP development and support
• All contributors who help improve this template

📞 Support

• Documentation:
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Happy coding! 🎉