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

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

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

📋 Commands

Create New Project

# 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

# 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

# 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

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:

# 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

🛠️ 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

# 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
• Python Workers Examples
• MCP SDK
• FastMCP

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ by HighspringLabs

A sustainable approach to MCP server template generation