# AYON MCP Server

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

MCP server that wraps AYON's REST API — agents use simple tool calls like
`ayon_publish_texture_set` or `ayon_publish_model` instead of raw HTTP.

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

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

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

Restart Hermes Agent — tools appear as `mcp_ayon_ayon_list_projects` etc.

### 3. Use with any MCP client

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

## 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 (Hermes / Claude / Cursor)
    │
    │  MCP (stdio)
    ▼
ayon-mcp server
    │  X-Api-Key header
    ▼
AYON REST API (/api/projects, /api/products, ...)
```

## 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.
- **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)