v0.2.0: Plug-and-play — dual transport (stdio+HTTP), AYON 1.15.4 compat, Dockerfile

- client.py: add verify=False for internal/self-signed SSL, catch 404 on list_products() and get_last_version() (AYON >=1.15 compat) - server.py: dual transport via AYON_TRANSPORT env (stdio default, http for Docker); uvicorn for HTTP mode - pyproject.toml: bump to 0.2.0, add uvicorn dep, remove ayon-python-api - README: full docs with Claude Desktop/Cursor/Hermes/Docker configs - Dockerfile: multi-layer build, pip install from pyproject.toml - .dockerignore: exclude venv, cache, dist
2026-06-28 11:30:02 +00:00
parent 7a6e237c78
commit 3b0f64648b
6 changed files with 167 additions and 40 deletions
@@ -1,9 +1,13 @@
 # AYON MCP Server

-**AI agents can publish CGI assets to AYON via Model Context Protocol.**
+**AI agents 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.
+`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

@@ -24,7 +28,41 @@ MCP server that wraps AYON's REST API — agents use simple tool calls like
 pip install git+https://git.niklashmotion.art/Hermes/ayon-mcp.git
 ```

-### 2. Configure Hermes Agent
+### 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`:

@@ -33,26 +71,45 @@ mcp_servers:
  ayon:
    command: "ayon-mcp"
    env:
-      AYON_SERVER_URL: "https://ayon.niklashmotion.art"
-      AYON_API_KEY: "sk-..."
+      AYON_URL: "https://ayon.niklashmotion.art"
+      AYON_KEY: "sk-..."
 ```

-Restart Hermes Agent — tools appear as `mcp_ayon_ayon_list_projects` etc.
+### 3c. Docker (HTTP transport)

-### 3. Use with any MCP client
+```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
+```

-```json
-{
-  "mcpServers": {
-    "ayon": {
-      "command": "ayon-mcp",
-      "env": {
-        "AYON_SERVER_URL": "https://ayon.niklashmotion.art",
-        "AYON_API_KEY": "sk-..."
-      }
-    }
-  }
-}
+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
@@ -77,9 +134,9 @@ Agent calls ayon_publish_texture_set with:
 ## Architecture

 ```
-AI Agent (Hermes / Claude / Cursor)
+AI Agent (Claude Desktop / Cursor / Hermes)
    │
-    │  MCP (stdio)
+    │  MCP (stdio or HTTP)
    ▼
 ayon-mcp server
    │  X-Api-Key header
@@ -87,12 +144,42 @@ ayon-mcp server
 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 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.