npm package: @highspringlabs/mcp-hydrate
Description: HighspringLabs MCP Server Template Hydration Tool
Author: HighspringLabs
Latest version: 2.1.1

# HighspringLabs MCP Server Hydration Tool

A CLI tool for generating production-ready MCP (Model Context Protocol) servers based on official Cloudflare Workers templates with HighspringLabs branding and MCP framework integration.

## 🎯 Purpose

This tool replaces the previous approach of maintaining full template codebases with a more sustainable fork-based system that:
- Leverages official Cloudflare Workers templates as the base
- Applies HighspringLabs branding and MCP framework integration
- Maintains upstream compatibility for easier updates
- Reduces maintenance burden while ensuring quality

## 🚀 Installation

```bash
# Install globally
npm install -g @highspringlabs/mcp-hydrate

# Or use via npx
npx @highspringlabs/mcp-hydrate --help
```

## 📋 Commands

### Create New Project

```bash
# Interactive mode
hsl-mcp-hydrate create my-mcp-server

# Non-interactive mode
hsl-mcp-hydrate create my-mcp-server --language python --template basic --yes

# With custom options
hsl-mcp-hydrate create my-api-server \
  --language typescript \
  --template advanced \
  --directory ./my-custom-dir \
  --no-install \
  --no-git
```

### Initialize in Current Directory

```bash
# Interactive mode (default)
hsl-mcp-hydrate init

# Non-interactive mode with defaults
hsl-mcp-hydrate init --yes --force

# With specific options (non-interactive)
hsl-mcp-hydrate init --language typescript --template basic --force --yes

# With specific options (interactive)
hsl-mcp-hydrate init --language python --template basic --force
```

### Update Existing Project

```bash
# Update all aspects
hsl-mcp-hydrate update --sync-upstream --apply-branding --update-mcp

# Sync only with upstream templates
hsl-mcp-hydrate update --sync-upstream

# Apply latest branding only
hsl-mcp-hydrate update --apply-branding
```

### List Available Templates

```bash
hsl-mcp-hydrate templates
```

## 🏗️ Architecture

### Directory Structure

```
hsl-mcp-templates/
├── base/                          # Minimal forks of official templates
│   ├── python/                    # Python Workers base template
│   └── typescript/                # TypeScript Workers base template
├── mcp-additions/                 # MCP-specific framework code
│   ├── python/                    # FastMCP integration
│   └── typescript/                # MCP SDK integration
├── branding/                      # HighspringLabs branding templates
│   ├── config-templates/          # Configuration file templates
│   ├── package-templates/         # Package.json/pyproject.toml templates
│   └── readme-templates/          # README templates
└── hydration-tool/                # This CLI tool
    ├── src/
    │   ├── cli.js                 # Command-line interface
    │   ├── commands.js            # Command implementations
    │   └── utils.js               # Utility functions
    └── package.json
```

### Hydration Process

1. **Copy Base Template**: Start with official Cloudflare Workers template
2. **Add MCP Framework**: Integrate FastMCP (Python) or MCP SDK (TypeScript)
3. **Apply Branding**: Add HighspringLabs metadata and documentation
4. **Generate Config**: Create wrangler.jsonc, .env.example, etc.
5. **Setup Development**: Initialize git repository and install dependencies

## 🔧 Configuration

### Language Support

- **Python**: Uses FastMCP framework with Python 3.11+
- **TypeScript**: Uses MCP SDK with Node.js 18+

### Template Types

- **Basic**: Simple MCP server with example tools and resources
- **Advanced**: Full-featured server with comprehensive examples

### Generated Files

All projects include:
- `wrangler.jsonc` - Cloudflare Workers configuration
- `.env.example` - Environment variable template
- `.gitignore` - Git ignore patterns
- `README.md` - HighspringLabs branded documentation

Language-specific files:
- **Python**: `pyproject.toml`, `requirements.txt`
- **TypeScript**: `package.json`, `tsconfig.json`

## 🎨 Branding

All generated projects include:
- HighspringLabs branding and metadata
- Professional documentation templates
- Consistent project structure
- Standard development workflows

## 🔄 Updates

The hydration tool supports updating existing projects:

- **Sync Upstream**: Pull latest changes from official Cloudflare templates
- **Apply Branding**: Update to latest HighspringLabs branding
- **Update MCP**: Upgrade MCP framework versions

## 📦 Version Management & Publishing

### Automated Release System

The hydration tool uses automated version management with integrated git tagging and npm publishing:

```bash
# Release types (choose based on changes)
npm run release:patch  # Bug fixes, typos, small improvements (1.0.0 → 1.0.1)
npm run release:minor  # New features, templates, CLI options (1.0.0 → 1.1.0)
npm run release:major  # Breaking changes, major restructuring (1.0.0 → 2.0.0)

# Default release (patch)
npm run release
```

### What Happens During Release

1. **Pre-version checks**: Runs `npm test` to ensure code quality
2. **Version bump**: Updates package.json version number
3. **Git commit**: Creates commit with version message (e.g., "v1.0.1")
4. **Git tag**: Creates annotated tag for the release
5. **Git push**: Pushes commit and tags to remote repository
6. **NPM publish**: Publishes new version to npm registry

### Version Guidelines

- **Patch (1.0.x)**: 
  - Bug fixes and corrections
  - Performance improvements
  - Documentation updates
  - Typo fixes

- **Minor (1.x.0)**:
  - New templates or template options
  - New CLI commands or flags
  - New features (backward compatible)
  - Dependency updates

- **Major (x.0.0)**:
  - Breaking CLI changes
  - Major template restructuring
  - Node.js version requirement changes
  - Incompatible API changes

### Development Workflow

1. Make changes to the codebase
2. Test thoroughly: `npm test`
3. Choose appropriate release type
4. Run release command: `npm run release:minor`
5. Verify publication on [npmjs.com](https://www.npmjs.com/package/@highspringlabs/mcp-hydrate)

## 🛠️ Development

### Adding New Languages

1. Create base template in `base/{language}/`
2. Add MCP integration in `mcp-additions/{language}/`
3. Create branding templates in `branding/`
4. Update utility functions in `src/utils.js`

### Adding New Templates

1. Extend `getTemplateConfig()` in `src/utils.js`
2. Add template-specific logic in `src/commands.js`
3. Create corresponding branding templates

### Testing

```bash
# Run tests
npm test

# Test CLI locally
npm link
hsl-mcp-hydrate create test-project --language python --yes
```

## 📚 Benefits Over Previous Approach

### Maintenance
- **Before**: Maintain full template codebases
- **Now**: Maintain minimal forks + branding layer

### Quality
- **Before**: Custom implementations may miss best practices
- **Now**: Inherit battle-tested official templates

### Updates
- **Before**: Manually track and apply upstream changes
- **Now**: Automated upstream sync with conflict resolution

### Efficiency
- **Before**: High token usage for template creation
- **Now**: Focus tokens on value-add features

## 🔗 Related Projects

- [Cloudflare Workers SDK](https://github.com/cloudflare/workers-sdk)
- [Python Workers Examples](https://github.com/cloudflare/python-workers-examples)
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [FastMCP](https://github.com/pydantic/fastapi)

## 📄 License

MIT License - see LICENSE file for details.

---

**Built with ❤️ by HighspringLabs**

*A sustainable approach to MCP server template generation*