Skip to content

Latest commit

 

History

History
314 lines (207 loc) · 9.18 KB

GettingStarted.md

File metadata and controls

314 lines (207 loc) · 9.18 KB

Getting Started with Hatch

Welcome to Hatch! This guide will help you understand what Hatch is, when to use it, and how to get started quickly.

This article is about:

  • Understanding Hatch's purpose and capabilities
  • System requirements and installation prerequisites
  • Quick setup for immediate productivity
  • Next steps for learning and exploration

What is Hatch?

Hatch is a sophisticated package manager specifically designed for Model Context Protocol (MCP) servers. It solves the complexity of installing, managing, and deploying MCP servers by handling their diverse dependencies automatically.

Key Capabilities

Environment Isolation: Create separate workspaces for different projects, similar to Python virtual environments but broader in scope.

Multi-Type Dependencies: Handle system packages (apt), Python packages (pip), other Hatch packages, and Docker containers in a single, coordinated installation.

Intelligent Dependency Resolution: Build dependency graphs, detect conflicts, and present clear installation plans before making changes.

Development-Focused Design: Optimized for rapid development, testing, and demonstration of MCP server ecosystems.

When to Use Hatch

Ideal for:

  • Developing and testing MCP servers
  • Setting up demonstration environments
  • Managing collections of related MCP servers
  • Rapid prototyping with complex dependencies
  • Educational scenarios and tutorials

Current limitations make it less suitable for:

  • Production deployments (security enhancements needed)
  • Multi-tenant systems (isolation improvements needed)
  • High-security environments (integrity verification needed)

See Security and Trust for detailed guidance on deployment scenarios.

System Requirements

Required Components

Python 3.12 or higher: Hatch requires modern Python for reliable operation.

Git: For cloning repositories and accessing package sources.

Network access: For package registry access and validation services.

Recommended Components

Conda or Mamba: For Python environment isolation within Hatch environments. Hatch will automatically detect and use these tools if available.

Docker: For packages that include Docker-based dependencies.

Platform package manager:

  • Linux: apt (Ubuntu/Debian)
  • macOS: None supported (planed)
  • Windows: None supported (planed)

Detection Behavior

Python Environment Detection: Hatch looks for conda/mamba in standard locations:

  • Linux/macOS: ~/miniconda3/bin/conda, /opt/conda/bin/conda
  • Windows: %USERPROFILE%\miniconda3\Scripts\conda.exe

If you have custom installations, Python environment features may be unavailable unless tools are in your PATH.

Quick Installation

Step 1: Install Prerequisites

Ensure you have Python 3.12+ and Git installed:

python --version  # Should show 3.12 or higher
git --version     # Should show Git version

For Python environment support, install conda or mamba:

# Install Miniforge (includes conda and mamba)
# Download from: https://conda-forge.org/download/

Step 2: Install Hatch

Clone and install Hatch from source:

git clone https://github.com/CrackingShells/Hatch.git
cd Hatch
pip install -e .

Step 3: Verify Installation

Test that Hatch is working:

hatch --version

You should see the installed version (e.g., hatch 0.6.1). You can also view available commands:

hatch --help

First Steps

Explore existing commands

You can suffix --help to any command to get more information about it. For example:

hatch env --help
hatch package --help

Create Your First Environment

# Create a new environment for your project
# By default this will also initialize a Python environment with the latest Python version
hatch env create my-project

# Switch to the new environment
hatch env use my-project

# Verify you're in the correct environment
hatch env current

Add Your First Package

# Add a package (from local directory or registry)
hatch package add example-mcp-server

# List installed packages
hatch package list

For more in-depth information, please refer to the tutorials section.

Quick Reference: Viewing Commands

Hatch provides multiple commands for viewing your environments, packages, and host configurations:

Environment Views

  • hatch env list: List all environments with package counts
  • hatch env show <name>: Detailed view of specific environment
  • hatch env list hosts: View environment deployments by host
  • hatch env list servers: View environment deployments by server

MCP Host Views

  • hatch mcp list hosts: Table view of hosts and servers
  • hatch mcp list servers: Table view of servers and hosts
  • hatch mcp show hosts: Detailed view of all host configurations
  • hatch mcp show servers: Detailed view of all server configurations

Discovery

  • hatch mcp discover hosts: Detect available MCP host platforms

Filtering: All list and show commands support regex filtering:

# Filter by server name
hatch mcp list hosts --server "weather.*"

# Filter by host name
hatch mcp show servers --host "claude.*"

# Filter by environment
hatch env list hosts --env "my-project"

Understanding Hatch Concepts

Environments

Hatch Environments are isolated workspaces that can contain:

  • MCP servers and their configurations
  • Python environments (via conda/mamba)
  • Package installations and dependencies
  • Environment-specific settings

Think of them as project-specific containers that keep different work separated.

Dependencies

Hatch handles four types of dependencies:

  1. System Dependencies: OS packages like curl, git, installed via package managers
  2. Python Dependencies: Python packages installed via pip
  3. Hatch Dependencies: Other MCP servers and Hatch packages
  4. Docker Dependencies: Container images for service dependencies

Installation Process

When you install a package, Hatch:

  1. Analyzes the package metadata and builds a dependency graph
  2. Presents an installation plan showing what will be installed
  3. Requests approval unless you use --auto-approve
  4. Installs dependencies in order: System → Python → Hatch → Docker
  5. Updates environment state with the results

Common Workflows

Development Workflow

# Set up project environment
hatch env create my-mcp-project
hatch env use my-mcp-project

# Add development tools
hatch package add development-tools

# Work on your project...

# Test with different configurations
hatch env create test-env
hatch env use test-env
hatch package add ./my-project  # Add local package for testing

Package Authoring Workflow

# Create package template
hatch create my-new-server

# Edit package metadata
cd my-new-server
# Edit hatch_metadata.json

# Validate package structure
hatch validate .

# Test local installation
hatch package add .

Automation Workflow

# Validate before adding
hatch validate .

# Add package (for automation, ensure non-interactive environment)
hatch package add .

Learning Path

Now that you have Hatch installed and understand the basics:

Next Steps

  1. Complete the tutorial series:

  2. Explore reference documentation:

  3. Understand limitations:

Diagnostics: Use these commands to gather information when seeking help:

hatch --help
hatch env list
hatch package list
python --version
which conda || echo "conda not found"

Important Notes

Current Status

Hatch v0.4.2 is optimized for development and trusted network environments. Key considerations:

  • Package integrity: Downloads are not cryptographically verified
  • Concurrent usage: Multiple Hatch instances may conflict
  • System packages: Version constraints are simplified for system dependencies
  • Network dependencies: Registry access and validation require internet connectivity

Best Practices

  • Use one Hatch instance per workspace to avoid concurrent access issues
  • Test complex installations in isolated environments before production use
  • Use --dry-run to preview installations before making changes
  • Keep cache sizes manageable by periodically cleaning old data
  • Use exact version pins for critical dependencies where precision matters

Welcome to Hatch! The tool is designed to make MCP server management straightforward while being transparent about its current capabilities and limitations. Start with simple scenarios and gradually explore more complex features as you become comfortable with the system.