ayon-mcp/README.md

# AYON MCP Server

**AI agents publish CGI assets to AYON via Model Context Protocol.**

`ayon-mcp` wraps AYON's REST API into six MCP tools — any MCP-compatible agent
can browse projects, list folders, and publish texture sets or 3D models with
simple tool calls. No raw HTTP, no manual JSON.

Works with **Claude Desktop**, **Cursor**, **Hermes Agent**, and any other
MCP client (stdio or HTTP transport).

## Tools

| Tool | What it does |
|------|-------------|
| `ayon_list_projects` | List all AYON projects |
| `ayon_list_folders` | List folders in a project |
| `ayon_list_products` | List published products in a folder |
| `ayon_get_product` | Get product details + latest version |
| `ayon_publish_texture_set` | Publish multiple texture maps as one product |
| `ayon_publish_model` | Publish a 3D model (ABC, USD, FBX, ...) |

## Quick Start

### 1. Install

```bash
pip install git+https://git.niklashmotion.art/Hermes/ayon-mcp.git
```

### 2. Configure

Two environment variables required:

| Variable | Description |
|----------|-------------|
| `AYON_URL` | AYON server URL (e.g. `https://ayon.niklashmotion.art`) |
| `AYON_KEY` | AYON API key from Settings → API Keys |

Optional:

| Variable | Default | Description |
|----------|---------|-------------|
| `AYON_TRANSPORT` | `stdio` | `stdio` for Claude/Cursor, `http` for Docker |
| `PORT` | `8000` | HTTP port (only when `AYON_TRANSPORT=http`) |

### 3a. Use with Claude Desktop / Cursor (stdio)

Add to `claude_desktop_config.json` or Cursor's MCP config:

```json
{
  "mcpServers": {
    "ayon": {
      "command": "ayon-mcp",
      "env": {
        "AYON_URL": "https://ayon.niklashmotion.art",
        "AYON_KEY": "sk-..."
      }
    }
  }
}
```

### 3b. Use with Hermes Agent (stdio)

Add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  ayon:
    command: "ayon-mcp"
    env:
      AYON_URL: "https://ayon.niklashmotion.art"
      AYON_KEY: "sk-..."
```

### 3c. Docker (HTTP transport)

```bash
docker run -d \
  --name ayon-mcp \
  -e AYON_URL=https://ayon.niklashmotion.art \
  -e AYON_KEY=sk-... \
  -e AYON_TRANSPORT=http \
  -p 8000:8000 \
  ghcr.io/niklas/ayon-mcp:latest
```

Then in Hermes `config.yaml`:

```yaml
mcp_servers:
  ayon:
    url: "http://localhost:8000/mcp"
    timeout: 30
```

### 3d. Docker Compose

```yaml
services:
  ayon-mcp:
    build: .
    container_name: mcp-ayon
    environment:
      - AYON_URL=https://ayon.example.com
      - AYON_KEY=sk-...
      - AYON_TRANSPORT=http
    ports:
      - "127.0.0.1:8001:8000"
    restart: unless-stopped
```

## Example: Agent publishes a texture set

```
User: Publish the chair textures — BaseColor, Roughness, and Normal maps.

Agent calls ayon_publish_texture_set with:
  project: "DemoProject"
  folder_path: "/assets/chair"
  product_name: "texture_chair"
  variant: "wood"
  textures: [
    {"name": "chair_BaseColor.png", "size": 2097152},
    {"name": "chair_Roughness.png", "size": 1048576},
    {"name": "chair_Normal.png", "size": 1572864}
  ]

→ Created product "texture_chair_wood" v1 with 3 texture maps
```

## Architecture

```
AI Agent (Claude Desktop / Cursor / Hermes)
    │
    │  MCP (stdio or HTTP)
    ▼
ayon-mcp server
    │  X-Api-Key header
    ▼
AYON REST API (/api/projects, /api/products, ...)
```

The MCP server is the **only gatekeeper** to AYON. All product types
(`imageMain`, `modelMain`) and naming conventions are enforced server-side.
The AI agent orchestrates the workflow but never touches raw API calls.

### Dual transport: stdio + HTTP

- **stdio** (default): `AYON_TRANSPORT=stdio` or unset. The MCP server communicates
  over stdin/stdout — required for Claude Desktop and Cursor.
- **HTTP**: `AYON_TRANSPORT=http`. Listens on `PORT` (default 8000). Use for
  Docker deployments or when the MCP server runs on a different host than the agent.

The same binary serves both modes — no separate builds needed.

## Compatibility

| Feature | AYON ≥1.15 | Older AYON |
|---------|-----------|------------|
| List projects | ✅ | ✅ |
| List folders | ✅ | ✅ |
| Create product | ✅ | ✅ |
| Create version | ✅ | ✅ |
| Create representation | ✅ | ✅ |
| List products (read-back) | ⚠️ falls back gracefully | ✅ |
| Get last version | ⚠️ falls back gracefully | ✅ |

AYON ≥1.15 removed the REST endpoints for listing products and versions.
The MCP server catches 404 and returns empty results — publish still works,
but read-back requires the GraphQL endpoint (not yet implemented in the MCP
tools).

## Limitations

- **REST-only**: Products are registered as metadata. Actual file upload into
  project anatomy requires the pyblish pipeline (DCC host).
- **No folder creation**: Folders must exist before publishing. Use AYON Web UI
  or Tray Publisher to create them first, or create them via REST API.
- **Representations are metadata**: The `files` array contains names/sizes,
  not uploaded content. Full file publishing needs a host with pyblish.

For DCC-integrated publishing (files into anatomy, loadable in Maya/Houdini),
combine with [ayon-matrix-publish](https://git.niklashmotion.art/Hermes/ayon-matrix-publish)
or run inside a DCC host with pyblish.

## Related

- [ayon-matrix-publish](https://git.niklashmotion.art/Hermes/ayon-matrix-publish) —
  AYON addon that uploads published products to Matrix/Element rooms.
- [AYON REST API Docs](https://docs.ayon.dev/docs/dev_api_rest)
- [Hermes MCP Client](https://hermes-agent.nousresearch.com/docs)