hatchdx 0.1.0

The DX-first platform for hatching AI

HatchDX

The DX-first platform for hatching AI.

HatchDX (hdx) is a CLI tool and developer platform for scaffolding, testing, validating, and deploying MCP servers and the AI agents that use them. Go from zero to a working, testable MCP server or agent in under 2 minutes.

hdx init          →  hdx server create  →  hdx server test  →  hdx server dev
  workspace          scaffold server       test locally        dev + REPL

hdx agent create  →  hdx agent chat     →  hdx agent eval
  scaffold agent     interactive chat      quality evals

Why?

Building MCP servers and agents today means reading scattered docs, copying boilerplate, no standardized project structure, and no way to test tools locally without a full LLM client. HatchDX fixes all of that.

• Workspace management — hdx init scaffolds a workspace for servers and agents
• No boilerplate — hdx server create generates a complete project with best practices baked in
• Test without Claude — hdx server test runs your tools locally using YAML fixtures
• Fast feedback loop — hdx server dev gives you hot reload and an interactive REPL
• Protocol compliance — hdx server validate catches MCP violations before shipping
• Quality checks — hdx server eval tests tool effectiveness with assertions and golden files
• Sandboxed execution — hdx server sandbox runs tools in containers with security policies
• Agent scaffolding — hdx agent create generates agent configs wired to your servers
• Agent chat — hdx agent chat runs interactive sessions with tool-calling agents

Install

# Option 1: Install as a global CLI tool (recommended)
uv tool install hatchdx

# Option 2: Run without installing
uvx hatchdx --help

# Option 3: pip
pip install hatchdx

Requires Python 3.13+ and uv (recommended) or pip.

Quick Start

# 1. Create a workspace
hdx init my-project
cd my-project

# 2. Create an MCP server
hdx server create --name weather-mcp --language python --transport stdio --template minimal

# 3. Install and test it
cd servers/weather-mcp
pip install -e .
hdx server test

# 4. Start the dev server with interactive REPL
hdx server dev

Or run hdx server create without flags for an interactive experience.

Commands

hdx init

Scaffold a new HatchDX workspace with servers/ and agents/ directories.

hdx init my-project

hdx server create

Create a new MCP server project.

# Interactive mode
hdx server create

# Non-interactive mode
hdx server create \
  --name weather-mcp \
  --language python \
  --transport stdio \
  --template api-wrapper \
  --description "Weather data via OpenWeather API"

hdx server test

Run YAML test fixtures against your MCP server. No LLM client needed.

hdx server test                    # Run all fixtures
hdx server test -v                 # Verbose
hdx server test -f "hello*"        # Filter by test name

hdx server dev

Start your server with hot reload and an interactive REPL.

hdx server dev                     # Hot reload + REPL
hdx server dev --no-repl           # Watch and restart only

hdx server validate

Run protocol compliance checks against your MCP server.

hdx server validate                        # Run all checks
hdx server validate --json-output          # Machine-readable JSON
hdx server validate --severity error       # Only errors

hdx server eval

Test tool effectiveness with assertions and golden files.

hdx server eval                            # Run all suites
hdx server eval --suite "core quality"     # Filter by suite
hdx server eval --compare                  # Regression detection

hdx server sandbox

Run MCP tools inside containers with configurable security policies.

hdx server sandbox run get_weather '{"city": "London"}'
hdx server sandbox shell
hdx server sandbox build

hdx agent create

Create a new AI agent project.

hdx agent create --name assistant --template single-agent --provider anthropic

hdx agent chat

Start an interactive chat session with an agent.

hdx agent chat assistant
hdx agent chat assistant -m "What's the weather?"  # Single message

hdx agent eval

Run eval suites against an agent.

hdx agent eval assistant --suite basic

hdx dashboard

Start the web dashboard for eval results and analytics.

hdx dashboard

Configuration

HatchDX reads config from pyproject.toml or hdx.toml (generated automatically by hdx server create).

pyproject.toml (Python projects):

[tool.hdx]
server_command = "python -m weather_mcp.server"
fixtures_dir = "tests/fixtures"

hdx.toml (TypeScript/other projects):

[server]
name = "weather-mcp"
command = "node dist/server.js"

[testing]
fixtures_dir = "tests/fixtures"

Development

# Clone and install
git clone https://github.com/ceasarb/hatchdx.git
cd hatchdx
uv sync

# Run tests
pytest tests/ -v

# Lint
ruff check src/
ruff format src/

License

MIT