HartOMat/docs/mcp-server.md

# Schaeffler Automat MCP Server

An MCP (Model Context Protocol) server that gives Claude Code direct access to the Schaeffler Automat 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 schaeffler -- uv run \
  --with "mcp[cli]" --with psycopg2-binary --with httpx \
  python schaeffler_mcp_server.py
```

### Verify

Inside Claude Code, run:
```
/mcp
```

You should see `schaeffler` 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 |
|---|---|
| `schaeffler://schema` | Full database schema (tables + columns) |
| `schaeffler://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://schaeffler:schaeffler@localhost:5432/schaeffler` | PostgreSQL connection string |
| `API_URL` | `http://localhost:8888` | Backend API base URL |
| `API_EMAIL` | `admin@schaeffler.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 schaeffler \
  --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 schaeffler_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://schaeffler:schaeffler@localhost:5432/schaeffler -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 schaeffler_mcp_server.py
```

### Reset MCP connection

```bash
claude mcp remove schaeffler
claude mcp add schaeffler -- uv run \
  --with "mcp[cli]" --with psycopg2-binary --with httpx \
  python schaeffler_mcp_server.py
```