@haleyio/create-mcp-server

A comprehensive template generator for creating Model Context Protocol (MCP) servers with best practices, comprehensive testing, CI/CD, and Claude Code integration.

Features

✨ Comprehensive Template: Full project structure with TypeScript, testing, and CI/CD 🏗️ Best Practices: Clean architecture, error handling, and security patterns
🧪 Testing Ready: Vitest setup with coverage enforcement and utilities 🚀 CI/CD Pipeline: GitLab CI with validation, testing, and NPM publishing 📝 Documentation: Complete README, CLAUDE.md, and troubleshooting guides 🔧 Claude Integration: Pre-configured for Claude Code with setup instructions ⚡ Development Tools: Scripts, validation, and development environment setup

Quick Start

# Create a new MCP server
npx @haleyio/create-mcp-server my-mcp-server

# Or install globally
npm install -g @haleyio/create-mcp-server
create-mcp-server my-mcp-server

Usage

The generator will prompt you for:

• Server Name: The name of your MCP server
• Description: Brief description of functionality
• Author Info: Name and email for package.json
• Service Integration: Which service/API your server will integrate with
• Repository URL: Where your server will be hosted
• License: Choose from common open source licenses

Generated Structure

my-mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # Main MCP server setup  
│   ├── core.ts               # Shared utilities
│   ├── schemas.ts            # Zod schema definitions
│   └── example-module.ts     # Example domain module
├── tests/
│   ├── setup.ts              # Test configuration
│   ├── global-setup.ts       # Global test setup
│   └── example.test.ts       # Example tests
├── scripts/
│   └── validate-installation.sh
├── .gitlab-ci.yml            # Complete CI/CD pipeline
├── tsconfig.json             # TypeScript configuration
├── vitest.config.ts          # Test configuration
├── package.json              # Project configuration
├── CLAUDE.md                 # Claude Code instructions
├── README.md                 # Project documentation
└── CONTRIBUTING.md           # Development guide

What's Included

🏗️ Architecture

• Modular TypeScript structure
• Clean separation of concerns
• Comprehensive error handling
• Zod schema validation

🧪 Testing

• Vitest test framework
• Coverage enforcement (30% minimum, 80% target)
• Test utilities and helpers
• Integration test patterns

🚀 CI/CD

• Complete GitLab CI pipeline
• Security validation
• Code formatting checks
• Automated NPM publishing
• Multi-environment testing

📖 Documentation

• Comprehensive README
• Claude Code integration guide
• API documentation templates
• Troubleshooting guides

🔧 Development

• TypeScript configuration
• Prettier code formatting
• Development scripts
• Health check validation

Template Customization

After generation, you can customize:

1. Domain Modules: Add your service-specific logic in src/
2. Schemas: Define your tool schemas in src/schemas.ts
3. Tests: Add comprehensive tests for your functionality
4. Documentation: Update README with your server's specific details

Examples

The template includes example implementations for:

• Tool registration and handling
• Schema validation
• Error handling patterns
• Testing approaches
• CI/CD configurations

Requirements

• Node.js 18+
• npm or yarn
• Git (for repository initialization)

Development

# Clone the template generator
git clone https://git.haley.io/john/create-mcp-server.git
cd create-mcp-server

# Install dependencies
npm install

# Build the generator
npm run build

# Test locally
npm link
create-mcp-server test-server

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © John Haley