155 lines
4.7 KiB
Markdown
155 lines
4.7 KiB
Markdown
# HartOMat MCP Server
|
|
|
|
An MCP (Model Context Protocol) server that gives Claude Code direct access to the HartOMat render pipeline, product library, and database.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
|
|
- Docker services running (`docker compose up -d`)
|
|
- Claude Code installed
|
|
|
|
### Setup (automatic)
|
|
|
|
The project includes `.mcp.json` which automatically registers the MCP server when you open the project in Claude Code. No manual setup needed — just restart Claude Code.
|
|
|
|
### Setup (manual)
|
|
|
|
```bash
|
|
claude mcp add hartomat -- uv run \
|
|
--with "mcp[cli]" --with psycopg2-binary --with httpx \
|
|
python hartomat_mcp_server.py
|
|
```
|
|
|
|
### Verify
|
|
|
|
Inside Claude Code, run:
|
|
```
|
|
/mcp
|
|
```
|
|
|
|
You should see `hartomat` listed with status "connected".
|
|
|
|
## Available Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| **Orders** | |
|
|
| `list_orders` | List recent orders with render progress |
|
|
| `get_order_detail` | Get full order detail with all lines |
|
|
| `dispatch_renders` | Dispatch/retry renders for an order |
|
|
| `set_material_override` | Set material override on all order lines |
|
|
| **Products & Renders** | |
|
|
| `search_products` | Search products by name, PIM-ID, category |
|
|
| `get_product_detail` | Full product detail: metadata, parts, materials, render history, media assets |
|
|
| `get_render_detail` | Full render metadata for a specific order line: timing, engine, log |
|
|
| `get_completed_renders` | List completed renders with timing, file paths, filterable by product/order/output type |
|
|
| `get_failed_renders` | List recently failed renders with error messages |
|
|
| `get_media_assets` | List media assets (renders, thumbnails, GLBs, USDs) with metadata |
|
|
| **Materials** | |
|
|
| `check_materials` | Find unmapped materials in an order |
|
|
| `list_materials` | List all library materials (with optional aliases) |
|
|
| **System** | |
|
|
| `list_output_types` | List all output types with settings |
|
|
| `get_worker_activity` | Recent STEP processing and render tasks |
|
|
| `get_render_stats` | Dashboard stats: throughput, coverage, counts |
|
|
| `get_queue_status` | Live render queue depth and worker status |
|
|
| `query_database` | Run read-only SQL against PostgreSQL (SELECT only) |
|
|
|
|
## Available Resources
|
|
|
|
| Resource URI | Description |
|
|
|---|---|
|
|
| `hartomat://schema` | Full database schema (tables + columns) |
|
|
| `hartomat://output-types` | All configured output types |
|
|
|
|
## Usage Examples
|
|
|
|
Once connected, you can ask Claude naturally:
|
|
|
|
```
|
|
Show me all failed renders from today
|
|
```
|
|
|
|
```
|
|
How many products don't have STEP files?
|
|
```
|
|
|
|
```
|
|
Check if order SA-2026-00158 has unmapped materials
|
|
```
|
|
|
|
```
|
|
Dispatch renders for order 6493140c-...
|
|
```
|
|
|
|
```
|
|
What's the average render time this week?
|
|
```
|
|
|
|
```
|
|
Run: SELECT name, material_override FROM output_types WHERE material_override IS NOT NULL
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The server connects to your local Docker services by default. Override via environment variables:
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `DATABASE_URL` | `postgresql://hartomat:hartomat@localhost:5432/hartomat` | PostgreSQL connection string |
|
|
| `API_URL` | `http://localhost:8888` | Backend API base URL |
|
|
| `API_EMAIL` | `admin@hartomat.com` | API login email |
|
|
| `API_PASSWORD` | `Admin1234!` | API login password |
|
|
|
|
### Custom configuration
|
|
|
|
Edit `.mcp.json` in the project root to change defaults, or use `claude mcp add` with `--env` flags:
|
|
|
|
```bash
|
|
claude mcp add hartomat \
|
|
--env DATABASE_URL=postgresql://user:pass@host/db \
|
|
--env API_URL=https://staging.example.com \
|
|
-- uv run --with "mcp[cli]" --with psycopg2-binary --with httpx \
|
|
python hartomat_mcp_server.py
|
|
```
|
|
|
|
## Security Notes
|
|
|
|
- **Read-only SQL**: The `query_database` tool blocks INSERT/UPDATE/DELETE/DROP statements
|
|
- **API auth**: Uses the configured admin credentials to authenticate against the backend API
|
|
- **Local only**: The MCP server runs locally via stdio transport — no network exposure
|
|
- **Tool approval**: Claude Code prompts for user approval before executing each tool call
|
|
|
|
## Troubleshooting
|
|
|
|
### Server not connecting
|
|
|
|
1. Check Docker services are running: `docker compose ps`
|
|
2. Check PostgreSQL is accessible: `psql postgresql://hartomat:hartomat@localhost:5432/hartomat -c "SELECT 1"`
|
|
3. Check backend API is up: `curl http://localhost:8888/api/auth/login`
|
|
|
|
### Dependencies missing
|
|
|
|
```bash
|
|
uv pip install "mcp[cli]" psycopg2-binary httpx
|
|
```
|
|
|
|
### Check server logs
|
|
|
|
```bash
|
|
# Run manually to see errors
|
|
uv run --with "mcp[cli]" --with psycopg2-binary --with httpx \
|
|
python hartomat_mcp_server.py
|
|
```
|
|
|
|
### Reset MCP connection
|
|
|
|
```bash
|
|
claude mcp remove hartomat
|
|
claude mcp add hartomat -- uv run \
|
|
--with "mcp[cli]" --with psycopg2-binary --with httpx \
|
|
python hartomat_mcp_server.py
|
|
```
|