# Deadline MCP Server

AI access to a **Thinkbox Deadline 10 render farm** via its Web Service REST API, exposed as [Model Context Protocol](https://modelcontextprotocol.io) tools. Works with Hermes, Claude, and any MCP-compatible client.

- **18 tools** — 9 read + 9 write (see [Tools](#tools))
- **Self-contained** — own venv, no host dependencies beyond Python 3.10+
- **Env-configured** — no secrets in the repo

---

## Requirements

| Requirement | Detail |
|---|---|
| Python | 3.10+ |
| Deadline Web Service | `deadlinewebservice` running, default port `8081` |
| Network | The target machine must reach the Web Service (same host, LAN, or tailnet) |
| Credentials | A Deadline **user account** (username + password — not email) |

---

## Install

```bash
git clone https://github.com/officefiction/deadline-mcp-server.git
cd deadline-mcp-server
./install.sh
```

`install.sh` creates a `venv/`, installs `mcp` + `httpx`, and self-tests the tool registry. Expected output ends with:

```
tools (18): deadline_complete_job, deadline_delete_job, ...
```

> **Version pin:** the server targets the MCP 1.x Python SDK (`mcp>=1.28,<2`). MCP 2.x moved `FastMCP` — do not upgrade past 2.x without testing.

---

## Configure

```bash
cp .env.example .env
# edit .env:
#   DEADLINE_WS_URL=http://localhost:8081   (or your host)
#   DEADLINE_WS_USER=<deadline username>
#   DEADLINE_WS_PASS=<deadline password>
chmod 600 .env
```

| Variable | Required | Default | Description |
|---|---|---|---|
| `DEADLINE_WS_URL` | no | `http://localhost:8081` | Base URL of the Deadline Web Service |
| `DEADLINE_WS_USER` | **yes** | — | Deadline user account (not email) |
| `DEADLINE_WS_PASS` | **yes** | — | Deadline account password |
| `DEADLINE_MCP_READONLY` | no | `false` | `true` = read-only tools only (no job mutations) |

---

## Register in Hermes

Add this block to `~/.hermes/config.yaml` (path must match where you cloned):

```yaml
mcp_servers:
  deadline:
    command: "/opt/deadline-mcp-server/venv/bin/python"
    args: ["/opt/deadline-mcp-server/server.py"]
    env:
      DEADLINE_WS_URL: "${DEADLINE_WS_URL}"
      DEADLINE_WS_USER: "${DEADLINE_WS_USER}"
      DEADLINE_WS_PASS: "${DEADLINE_WS_PASS}"
    enabled: true
    timeout: 120
    connect_timeout: 60
```

Then put the three `DEADLINE_WS_*` values in the profile's `.env` (chmod 600), restart the gateway, and verify:

```bash
hermes mcp test deadline   # expect 18 tools discovered
```

### Register in other MCP clients

Point any MCP client at the stdio server:

```json
{
  "command": "/opt/deadline-mcp-server/venv/bin/python",
  "args": ["/opt/deadline-mcp-server/server.py"],
  "env": {
    "DEADLINE_WS_URL": "http://localhost:8081",
    "DEADLINE_WS_USER": "...",
    "DEADLINE_WS_PASS": "..."
  }
}
```

---

## Tools

### Read (always available)

| Tool | Description |
|---|---|
| `deadline_farm_status` | Overall farm snapshot: workers, jobs by state, groups, pools |
| `deadline_list_jobs` | List jobs, filter by state / user |
| `deadline_get_job` | One job by ID |
| `deadline_job_tasks` | Tasks (chunks) of a job, per-task status |
| `deadline_job_reports` | Job reports / render logs |
| `deadline_list_workers` | Farm workers (slaves) with status + heartbeat |
| `deadline_list_users` | Repository users |
| `deadline_list_groups` | Worker groups |
| `deadline_list_pools` | Job pools |

### Write (disabled with `DEADLINE_MCP_READONLY=true`)

| Tool | Description |
|---|---|
| `deadline_suspend_job` | Stop new tasks from starting |
| `deadline_resume_job` | Resume a suspended job |
| `deadline_requeue_job` | Re-run a job's tasks |
| `deadline_complete_job` | Mark a job completed |
| `deadline_fail_job` | Mark a job failed |
| `deadline_pend_job` | Hold a job until released |
| `deadline_release_pending_job` | Release a pended job to the queue |
| `deadline_set_job_priority` | Change a job's priority |
| `deadline_delete_job` | Delete a job |

### Job states

| State | Meaning |
|---|---|
| 0 | Unknown |
| 1 | Active |
| 2 | Suspended |
| 3 | Completed |
| 4 | Failed |
| 5 | Deleted |
| 6 | Pending |

---

## Architecture

```
MCP client (Hermes / Claude / ...)
        │  stdio (JSON-RPC)
        ▼
server.py  (FastMCP, mcp<2)
        │  HTTP Basic auth
        ▼
Deadline Web Service  (deadlinewebservice, :8081)
        │  REST
        ▼
Deadline repository  (render farm)
```

Key API facts (this server handles them automatically):

- Workers are served under **`/api/slaves`** (not `/api/workers`)
- Job state lives in the top-level **`Stat`** field
- Auth is a Deadline user account — the Web Service returns `401` without it

---

## Development

```bash
# Regenerate/refresh docs against the live tool registry
python3 scripts/deadline_mcp_docs.py --outline   # (internal tooling, not in this repo)
```

---

## License

Internal tooling for the Office Fiction project. MIT.