Metadata-Version: 2.4
Name: hatchdx
Version: 0.2.0
Summary: The DX-first platform for agentic engineering
Keywords: mcp,model-context-protocol,hatchdx,ai-agents,cli,scaffold,testing,developer-tools
Author: nyteshift
Author-email: nyteshift <nyteshifttech@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Code Generators
Requires-Dist: click>=8.3.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.3.2
Requires-Dist: watchdog>=6.0.0
Requires-Dist: jsonpath-ng>=1.6.0
Requires-Dist: aiohttp>=3.11.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: anthropic>=0.42.0 ; extra == 'agent'
Requires-Dist: openai>=1.0.0 ; extra == 'agent'
Requires-Dist: huggingface-hub>=0.20.0 ; extra == 'agent'
Requires-Dist: anthropic>=0.42.0 ; extra == 'anthropic'
Requires-Dist: huggingface-hub>=0.20.0 ; extra == 'huggingface'
Requires-Dist: openai>=1.0.0 ; extra == 'openai'
Requires-Python: >=3.13
Project-URL: Issues, https://github.com/ceasarb/hatchdx/issues
Project-URL: Repository, https://github.com/ceasarb/hatchdx
Provides-Extra: agent
Provides-Extra: anthropic
Provides-Extra: huggingface
Provides-Extra: openai
Description-Content-Type: text/markdown

# 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 add-server  →  hdx agent chat  →  hdx agent eval
  scaffold agent     wire MCP servers        interactive chat    quality evals

hdx model pull    →  hdx model list
  HF → Ollama        manage local models
```

## 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
- **Server wiring** — `hdx agent add-server` connects MCP servers to agents with tool filtering
- **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
- **Local models** — `hdx model pull` brings Hugging Face models to local Ollama for offline agent development
- **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[huggingface]"     # Hugging Face (local models via Ollama)
uv tool install "hatchdx[agent]"           # All 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.

### Agent Quick Start

```bash
# 1. Create an agent (from workspace root)
hdx agent create --name assistant --provider anthropic

# 2. Wire your MCP server to it
hdx agent add-server assistant --server servers/weather-mcp

# 3. Chat with the agent
hdx agent chat assistant
```

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

List all MCP servers in the workspace.

```bash
hdx server list                    # Table output
hdx server list --json             # JSON output
```

### `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
# Interactive mode
hdx agent create

# Non-interactive mode
hdx agent create --name assistant --template single-agent --provider anthropic
```

Templates: `single-agent`, `researcher`, `custom`
Providers: `anthropic`, `openai`, `local`, `huggingface`

### `hdx agent add-server`

Wire an MCP server to an agent with optional tool filtering.

```bash
# Local server (auto-detects name and command)
hdx agent add-server assistant --server ../servers/weather-mcp

# Remote HTTP server
hdx agent add-server assistant --url https://api.example.com/mcp

# Direct command
hdx agent add-server assistant --command "python -m weather_mcp.server"

# With tool filtering
hdx agent add-server assistant --server ../servers/weather-mcp \
  --include-tools get_weather --include-tools get_forecast

# With environment variables
hdx agent add-server assistant --server ../servers/weather-mcp \
  --env API_KEY=abc123 --env BASE_URL=https://api.example.com
```

### `hdx agent list`

List all agents in the project.

```bash
hdx agent list                     # Table output
hdx agent list --json              # JSON output
```

### `hdx agent inspect`

Show detailed information about an agent (config, servers, system prompt).

```bash
hdx agent inspect assistant        # Full details
hdx agent inspect assistant --tools  # Only show tools
hdx agent inspect assistant --json   # JSON output
```

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

### `hdx model pull`

Pull a Hugging Face model to local Ollama for offline agent development.

```bash
hdx model pull mistralai/Mistral-7B-Instruct-v0.3
hdx model pull mistralai/Mistral-7B-Instruct-v0.3 --alias mistral-7b
```

### `hdx model list`

List locally pulled models.

```bash
hdx model list                     # Table output
hdx model list --json              # JSON output
```

### `hdx model remove`

Remove a locally pulled model.

```bash
hdx model remove mistral-7b
hdx model remove mistral-7b --yes  # Skip confirmation
```

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