# HatchDX

> The DX-first platform for agentic engineering.

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
- **Agent evals** — `hdx agent eval` tests agent behavior with assertions, cost tracking, and regression detection
- **Web dashboard** — `hdx dashboard` gives you visual observability for servers and agents (eval history, config, analytics)

## Install

```bash
# 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](https://docs.astral.sh/uv/) (recommended) or pip.

### Agent extras

Agent features (chat, eval) require a model provider SDK. Install the extra for your provider:

```bash
# Global CLI install with agent support (recommended)
uv tool install "hatchdx[anthropic]"       # Anthropic (Claude)
uv tool install "hatchdx[openai]"          # OpenAI (GPT, o-series)
uv tool install "hatchdx[agent]"           # Both providers

# Or with uvx (no install, quotes required)
uvx --from "hatchdx[anthropic]" hdx agent chat my-agent

# Or with pip
pip install "hatchdx[anthropic]"
```

> **Note**: Quotes around `"hatchdx[...]"` are required — zsh interprets bare `[]` as glob patterns.

Server-only users don't need extras — `hdx` stays lightweight by default.

## Quick Start

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

```bash
hdx init my-project
```

### `hdx server create`

Create a new MCP server project.

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

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

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

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

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

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

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

### `hdx agent chat`

Start an interactive chat session with an agent.

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

### `hdx agent eval`

Run eval suites against an agent.

```bash
hdx agent eval assistant --suite basic
```

### `hdx dashboard`

Start the web dashboard for observability across servers and agents.

```bash
hdx dashboard                          # Start and open browser (default: http://localhost:4320)
hdx dashboard --port 8080              # Custom port
hdx dashboard --no-open                # Don't auto-open the browser
```

The dashboard includes:
- **Overview** — project summary, server health, recent eval runs
- **Agents** — browse all agents, view config (model, servers, tool filters, system prompt), eval history with pass rates/cost/tokens
- **Eval Dashboard** — unified eval runs for both servers and agents, with source filter toggle (All / Servers / Agents)
- **Tool Playground** — invoke tools from the browser via auto-generated forms
- **Analytics** — invocation counts, latency percentiles, error rates
- **Compliance** — protocol validation results with fix suggestions

## Configuration

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

**pyproject.toml** (Python projects):

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

**hdx.toml** (TypeScript/other projects):

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

[testing]
fixtures_dir = "tests/fixtures"
```

## Development

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