npm package: @haleyio/create-mcp-server
Description: Template generator for creating MCP servers with best practices and comprehensive tooling
Author: John Haley
Latest version: 1.1.0

# @haleyio/create-mcp-server

[![npm version](https://badge.fury.io/js/@haleyio%2Fcreate-mcp-server.svg)](https://badge.fury.io/js/@haleyio%2Fcreate-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

```bash
# 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

```bash
# 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](CONTRIBUTING.md) for guidelines.

## License

MIT © John Haley