{"id":"6c7c5384-4c1c-4220-9cca-b2be819a3999","slug":"flame-mcp","kind":"mcp","name":"flame-mcp","summary":"MCP server for Autodesk Flame — clip control, timelines, and effects with RAG search, anti-hallucination safety, and self-learning","owner":"abrahamADSK","repoUrl":"https://github.com/abrahamADSK/flame-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":7,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-04T12:15:54.000Z","addedAt":"2026-10-21T04:16:59.333Z","logoUrl":"https://avatars.githubusercontent.com/u/119292131?u=2cf854c41120b85038494bfbaf503a470029a0a6&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","cloud-infra","data-analytics"],"tags":["autodesk-flame","chromadb","claude","compositing","llm-tools","python","rag","vfx"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T04:17:12.796Z","sample":false,"url":"https://conduits.dev/tools/flame-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"flame-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# flame-mcp\n\n> Control Autodesk Flame with natural language using Claude and the Model Context Protocol (MCP).\n\n> [!WARNING]\n> **Experimental project — use at your own risk.**\n> This is an independent, unofficial experiment created with [Claude Code](https://claude.com/claude-code). It is **not** affiliated with, endorsed by, or officially supported by Autodesk in any way. The Flame name and trademarks belong to Autodesk, Inc.\n>\n> Executing AI-generated code inside a live Flame session carries real risks: **unexpected crashes, loss of unsaved work, unintended modifications to projects, sequences, or media.** Always work on a duplicate or test project. Never run this on production material without a full backup. The author(s) accept no responsibility for data loss, corruption, or any other damage resulting from its use.\n\n## 📊 Code knowledge graph\n\nInteractive, auto-published map of this codebase — modules, functions, call/import edges and community clusters — rebuilt by [graphify](https://github.com/safishamsi/graphify) and deployed to GitHub Pages on every push to `src/`:\n\n**[abrahamadsk.github.io/flame-mcp](https://abrahamadsk.github.io/flame-mcp/)** · part of the [MCP ecosystem graph hub](https://abrahamadsk.github.io/mcp-graphs/).\n\n`flame-mcp` connects [Claude](https://claude.ai) to [Autodesk Flame](https://www.autodesk.com/products/flame) via a lightweight Python bridge. Type what you want to do in plain language — Claude translates it into Flame API calls and executes them live.\n\n```\nYou: \"Delete all reels named TEST from Default Library\"\nClaude → MCP Server → Unix socket → Flame Python API → Result back to Claude\n```\n\n---\n\n## Features\n\nThe system has two components:\n\n**`hooks/flame_mcp_bridge.py`** — A Flame Python hook that starts a local **UNIX domain socket** server when Flame launches, restricted to its owner (`0600` socket file — inside a `0700` `run/` directory in a dev tree, in `/tmp` for the installed hook) and additionally checking the connecting process's UID. It receives Python code, executes it inside Flame's Python interpreter with full access to the `flame` module, and returns the result. **There is no TCP transport**: what arrives here is executed, so the socket's file permissions *are* the access control, and a loopback TCP socket has no owner the kernel could check.\n\n**`src/flame_mcp/server.py`** — An MCP server that Claude launches. It exposes tools that Claude can call by name, translates natural language into Python code, and communicates with the bridge over the socket.\n\n```\n┌──────────────────┐    MCP (stdio)    ┌──────────────────────┐  Unix socket   ┌─────────────────┐\n│  Claude Code /   │ ◄──────────────── │  flame_mcp/server    │ ◄────────────  │  Autodesk Flame │\n│  Claude Desktop  │ ─────────────────►│   (Python, macOS)    │ ─────────────► │  Python bridge  │\n└──────────────────┘                   └──────────────────────┘  (TCP fallback) └─────────────────┘\n```\n\nCompatible with **Claude Code** (terminal), **Claude Desktop**, and **Cowork** — all three contexts use the same MCP server and behave identically.\n\n---\n\n## Requirements\n\n- macOS\n- [Autodesk Flame](https://www.autodesk.com/products/flame) 2025 or later\n- Python 3.13 or higher (`python3 --version`)\n- [Node.js](https://nodejs.org) v22 or higher (required by Claude Code)\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) 2.x (`npm install -g @anthropic-ai/claude-code`)\n- A Claude account ([claude.ai](https://claude.ai)) — Pro, Max, or API key\n\n**Optional — local / free inference with Ollama:**\n- [Ollama](https://ollama.com) >= 0.17.6 installed on your Mac, a Linux GPU server, or both\n  - macOS: `brew install ollama && brew services start ollama`\n  - Linux: see https://ollama.com/download/linux (systemd)\n  - Verify: `ollama --version`\n- Create the `qwen3.5-mcp` tag (required — `AVAILABLE_MODELS` in\n  `hooks/flame_mcp_bridge.py` expects this exact name):\n  ```bash\n  ollama pull qwen3.5:9b\n  ollama cp qwen3.5:9b qwen3.5-mcp\n  ```\n  The bridge forces `num_ctx=24576` at runtime via a pre-flight POST to\n  Ollama's native `/api/generate` endpoint, so a custom Modelfile with\n  `PARAMETER num_ctx` is **not needed** — the Anthropic-compat endpoint\n  ignores Modelfile settings anyway. If you want different defaults on\n  `num_ctx` for some reason, see the advanced Ollama setup below.\n- See [Ollama setup](#ollama-setup-optional) below for backend options\n\n> **Note on Python versions:** The MCP server runs on your system Python (3.13+). Code executed *inside* Flame uses Flame's bundled Python interpreter (Flame 2026 ships Python 3.11.5; Flame 2027 ships Python 3.13.3).\n\n---\n\n## Installation\n\n### Automatic (recommended)\n\n```bash\ngit clone https://github.com/abrahamADSK/flame-mcp.git  # replace with your fork URL if applicable\ncd flame-mcp\nchmod +x install.sh\n./install.sh\n```\n\nThe installer will:\n1. Create a Python virtual environment\n2. Install dependencies (`mcp`, `chromadb`, `sentence-transformers`)\n3. Copy the Flame hook to `/opt/Autodesk/shared/python/` (requires `sudo`)\n4. Register the MCP server with Claude Code\n5. Build the RAG documentation index\n6. Generate `.claude/settings.local.json` with the non-destructive MCP tools pre-approved (39 tools total; destructive tools such as `execute_python`, the `create_*`/`timeline_*` writers and `undo_last_operation` are left for an interactive permission prompt)\n\n### Verify installation\n\nAfter installing, run the health check to confirm everything is in place:\n\n```bash\n./install.sh --doctor\n```\n\nThis runs a 5-check sweep (MCP registration, bridge symlink, optional `.env` file, venv importability, RAG index) and prints PASS/FAIL/WARN/SKIP with remediation hints for each check. The bridge-symlink check now sha256-compares the deployed hook against `hooks/flame_mcp_bridge.py` and FAILs on a stale regular-file copy. Recommended before first use.\n\n### Manual\n\n```bash\n# 1. Clone and set up\ngit clone https://github.com/abrahamADSK/flame-mcp.git  # replace with your fork URL if applicable\ncd flame-mcp\n\n# 2. Virtual environment + dependencies\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt --no-user\n\n# 3. Build the RAG index\npython -m flame_mcp.rag.build_index\n\n# 4. Install the Flame hook\nsudo cp hooks/flame_mcp_bridge.py /opt/Autodesk/shared/python/\n\n# 5. Register with Claude Code\nclaude mcp add flame -- \"$(pwd)/.venv/bin/python\" -m flame_mcp.server\n\n# 6. (Optional) Claude Desktop\n#    Copy claude_desktop_config.json to ~/Library/Application Support/Claude/\n```\n\n---\n\n## Usage\n\n### 1. Flame menu — MCP Bridge\n\nWhen Flame starts, the hook registers an **MCP Bridge** submenu in Flame's main menu bar:\n\n```\nMCP Bridge  [● Active]\n├── Status: ● Active — unix socket  → shows current bridge status\n├── Start bridge                   → start Unix socket listener (TCP fallback)\n├── Stop bridge                    → stop the listener\n├── Restart bridge                 → stop + start\n├── Claude Chat  (embedded)        → open Qt chat window inside Flame\n├── Launch Claude (terminal)...    → open Claude Code in Terminal.app\n├── Reload hook                    → hot-reload the bridge without restarting Flame\n├── Connection test                → test the bridge socket round-trip, shows latency\n└── View log...                    → open the bridge log file in TextEdit\n```\n\nThe status indicator updates every time you open the menu:\n- `● Active` — bridge is listening, ready to receive commands\n- `○ Inactive` — bridge is stopped\n\n### 2. Embedded Claude Chat\n\n**Claude Chat (embedded)** opens a native Qt window directly inside Flame — no terminal required. Type natural language requests and Claude responds, controlling Flame in real time.\n\n- Runs the `claude` CLI with your Claude Code session; `CLAUDE_PATH` (environment or `~/flame-mcp/.env`) optionally overrides its location\n- Executes Flame code via the Unix socket bridge (thread-safe, non-blocking)\n- Uses the local RAG index to look up API patterns before every call\n- Requires PySide6 (bundled with Flame 2026+)\n\n#### Chat commands\n\nIn addition to natural language, the chat input accepts these special commands:\n\n| Command | Description |\n|---------|-------------|\n| `/undo` | Undo the last Flame action. Triggers `flame.execute_shortcut(\"Undo\")` directly — bypasses Claude, instant. |\n| `/undo N` | Undo the last **N** Flame actions (e.g. `/undo 3`). After each Claude response the chat shows how many actions were performed, so you know the right N. |\n| `/wrong` | Tell Claude the last response was incorrect. Injects a correction message into the conversation so Claude re-analyses and tries again without learning the wrong pattern. |\n| `/wrong <reason>` | Same as `/wrong` but with context (e.g. `/wrong me diste el desktop en vez de la librería`). Claude uses the reason to understand exactly what to correct. |\n\n> **Tip:** `/undo` and `/wrong` can be combined. If Claude deleted something it shouldn't have, type `/undo N` first to reverse the Flame action, then `/wrong <reason>` so it doesn't repeat the mistake.\n\n**Model selector dropdown** — backends defined in `hooks/flame_mcp_bridge.py :: AVAILABLE_MODELS`, switch without leaving Flame:\n\n<!-- concept:llm_backend_table start -->\n| Backend | Models available (model IDs in backticks) | Requires | Works offline? |\n|---------|-------------------------------------------|----------|----------------|\n| anthropic | Claude Opus 5.5 (`claude-opus-5-5`, default), Claude Fable 5.1 (`claude-fable-5-1`), Claude Sonnet 5.5 (`claude-sonnet-5-5`) | Anthropic API key | ✗ |\n| ollama | Qwen3.5 9B (`qwen3.5-mcp`), GLM-4.7 Flash (`glm-4.7-flash`) ⚠ not recommended — tool-calling broken in Ollama as of June 2026 (issues #13820/#13840) | gpu-server on LAN + GPU, LAN reachable at `config.json → ollama_url` | ✗ |\n| ollama_mac 🍎 | Qwen3.5 9B (`qwen3.5-mcp`), Qwen3.5 4B (`qwen3.5:4b`) | Ollama on Mac (`brew install ollama`), models pulled locally | ✓ |\n<!-- concept:llm_backend_table end -->\n\nSelection is persisted to `~/flame-mcp/config.json` between sessions. The combo label shows the server hostname for `ollama`, or `localhost` for `ollama_mac`. Anthropic model IDs are reviewed every 14 days against the [Anthropic model catalogue](https://docs.anthropic.com/claude/docs/models-overview) via `~/Projects/.external_versions.yml` (enforced by `verify_concepts.py`).\n\n#### Configuration precedence (env-var vs config.json)\n\nTwo different policies apply depending on what you are configuring:\n\n- **Socket transport** (`FLAME_BRIDGE_SOCKET`) — env var wins over any `config.json` default. Useful for overriding the bridge path in a dev sandbox without touching the committed config.\n- **Model + backend + `ollama_url`** — `config.json` wins; there is no env var override. The Flame panel writes the user's choice back to `config.json` so selection is sticky across restarts.\n- **`claude` binary path** (`CLAUDE_PATH`) — env var / `.env`, not `config.json`. Optional: without it the bridge searches the usual install locations.\n\nThe full precedence table (including fallback chains, defaults, and the\nasymmetry between transport and model settings) lives in\n[`docs/ARCHITECTURE.md` §9](docs/ARCHITECTURE.md) and §11.\n\n### 3. Claude Code (terminal)\n\n```bash\ncd ~/flame-mcp\nsource .venv/bin/activate\nclaude\n```\n\nThen talk naturally:\n\n```\n> List all libraries and reels\n> Create a new reel called \"MASTER\" in Default Library\n> Delete all reels named TEST, TEST2 from Default Library\n> What's the current project frame rate?\n```\n\n---\n\n<!-- concept:mcp_tool_count start -->\n## MCP Tools (39)\n<!-- concept:mcp_tool_count end -->\n\n<!-- concept:mcp_tool_table start -->\n| Tool | Description |\n|------|-------------|\n| `execute_python` | Execute arbitrary Python code inside Flame with full API access |\n| `execute_plan` | Run a structured JSON plan against Flame (F5b — preferred over execute_python for covered ops) |\n| `get_project_info` | Return name, frame rate, resolution, bit depth of the active project |\n| `list_libraries` | List all libraries in the project with reel counts |\n| `list_reels` | List reels in a library, or across all libraries |\n| `list_clips` | List clips and sequences (with durations) in a library/reel, or across all libraries |\n| `list_desktop_reels` | List the full desktop structure: reel groups, reels, and clip names |\n| `list_batch_groups` | List all batch groups in the active desktop with their reel counts |\n| `list_all_projects` | List all Flame projects available on this workstation |\n| `get_clip_metadata` | Get detailed metadata for a specific clip (resolution, frame rate, duration, etc.) |\n| `get_selected_clips` | Return the clips currently selected in the Flame media panel or desktop |\n| `get_source_path` | Get the filesystem source path of a clip, reel, or library |\n| `collect_media_paths` | Collect filesystem paths for all clips in a library or reel |\n| `get_write_node_settings` | Get the Write File node settings from the current Batch setup |\n| `flame_wiretap_tree` | Inspect the Wiretap IFFFS node tree at a given path |\n| `get_flame_version` | Return the running Flame version string |\n| `ping` | Check whether the bridge to Autodesk Flame is reachable |\n| `search_flame_docs` | Semantic RAG search over Flame API documentation — call before execute_python |\n| `resolve_concept` | Fast static lookup: map a user concept to the correct API path and tool |\n| `learn_pattern` | Add a new working pattern to FLAME_API.md and rebuild the index |\n| `session_stats` | Show token usage and RAG savings for the current session |\n| `reset_session_stats` | Zero the session stats counters immediately (idle auto-reset fires after 30 min inactivity) |\n| `list_flame_logs` | List all log files available in /opt/Autodesk/logs |\n| `read_flame_log` | Read a Flame log file with optional tail/grep filtering |\n| `create_sequence` | Create a new empty sequence in a Flame library/reel (optional duration in frames) |\n| `render_batch` | Render the open Batch Group — or any group by exact name (batch_group argument), without switching the open one (measured Chat 109). Background Reactor by default (`Foreground` where the workstation has no Reactor); scheduled via idle event |\n| `export_clip` | Export a clip to disk via a Flame export preset (PyExporter, scheduled via idle event — never deadlocks Flame) |\n| `create_library` | Create a new library in the active project workspace |\n| `create_reel` | Create a new reel inside a library |\n| `create_folder` | Create a new folder inside a library |\n| `create_reel_group` | Create a new reel group inside a library |\n| `create_batch_group` | Create a new empty Batch Group on the desktop |\n| `import_clips` | Import media from disk into a library (or a reel within it) |\n| `timeline_insert` | Ripple-insert a source clip into a sequence's timeline |\n| `timeline_overwrite` | Overwrite part of a sequence's timeline with a source clip |\n| `rename_segments` | Rename a clip (all its segments) in a Flame library/reel |\n| `fpt_link` | Report the native Flame↔FPT project link (shotgun_project_name attribute). READ-ONLY — set/break were removed in Chat 98 after both in-vivo writes triggered Flame's error report; links are created and broken from Flame's own FPT menu |\n| `operation_history` | Show the last N execute_python operations recorded this session |\n| `undo_last_operation` | Undo the last undoable execute_python operation |\n<!-- concept:mcp_tool_table end -->\n\n**Visible progress on long operations** — the five long-running tools\n(`execute_python`, `flame_wiretap_tree`, `render_batch`, `export_clip`,\n`import_clips`) stream an MCP `ctx.info` heartbeat every 10 s while the\noperation blocks inside Flame, instead of staying silent until done. Fast\noperations emit nothing. Internally each of these tools is an async wrapper\nover a sync `_<name>_impl` body — the `execute_plan` op registry and the test\nsuite call the sync bodies directly.\n\n### Tool workflow\n\nEvery Claude response to a Flame request follows this sequence:\n\n```\nsearch_flame_docs(query)          ← look up correct API patterns\n  └─ if score < 60%: warn         ← pattern may not be documented\nexecute_python(code)              ← run the code in Flame\n  └─ if score was < 60% and ok:\n       learn_pattern(desc, code)  ← teach the system (self-improvement)\nsession_stats()                   ← show token summary\n```\n\n---\n\n## Skills (2)\n\nTools are what the server can *do*. Skills are the **recipe** — which tools, in\nwhat order, and what fails silently. They live in [`docs/skills/`](docs/skills/),\nversion controlled with the code they describe, and load only when the request\nmatches their trigger, so they cost almost nothing until they are relevant.\n\n| Skill | Fires on |\n|---|---|\n| `flame-batch-authoring` | Any `flame.batch` call, **reads included**: the main-thread idle-event contract, the active group that cannot be switched from Python, node-name scoping |\n| `flame-delivery` | Render → export → review Version → open clip: export deadlocks, a start frame that moves with the current version, presets that apply no colour |\n\nActivate them on a fresh clone by symlinking into your user skills directory:\n\n```bash\nfor s in flame-batch-authoring flame-delivery; do\n  ln -s \"$PWD/docs/skills/$s\" ~/.claude/skills/\"$s\"\ndone\n```\n\n`flame-delivery` keeps **Flame truth**, **tk-flame Toolkit behaviour** and **this\nfacility only** in separate sections, so a local configuration accident is never\nread as product behaviour. See [`docs/skills/README.md`](docs/skills/README.md)\nfor the four-layer split (tool / skill / RAG / memory).\n\n## Self-improving RAG\n\nThe system maintains a local semantic search index (`rag/index/`) built from all documents in the `docs/` folder plus `FLAME_API.md`. Before every `execute_python` call, Claude searches this index to find the correct API pattern — avoiding guesswork and saving tokens.\n\n### Knowledge base (≈800 chunks across 14 documents)\n\n<!-- concept:rag_corpus_docs start -->\n| File | Chunks | Content |\n|---|---|---|\n| `FLAME_API.md` | ~295 | Core Flame Python API — PyClip, PyReel, PyBatch, PyLibrary, connectors, markers, PyTime, import/export code samples. Auto-extended by `learn_pattern`. |\n| `flame_advanced_api.md` | ~78 | Action node (PyActionNode, output types, FBX import), Color Management (CDL/LUT/CTF), Exporter (safe schedule_idle_event pattern), MediaHub, Conform/AAF workflow, Timeline FX/BFX, Python hooks reference. |\n| `flame_segment_timeline_api.md` | ~61 | Full PySegment API (trim, slip, create_effect, connected_segments), corrected PyClip.render() signature, PyBatch.create_batch_group(), PySequence methods, post-conform batch group creation patterns. |\n| `flame_code_samples.md` | ~46 | Extracted Autodesk official zip samples — clip ops, render, Timeline FX wiring, Action compass nodes. |\n| `flame_youtube_patterns.md` | ~60 | Patterns extracted from Logik-TV / YouTube tutorials (OCR + transcript mining). |\n| `flame_community_workflows.md` | ~23 | Logik Forum operator terminology → API mapping. Conform jargon, batch compositing terms, render/delivery slang. |\n| `flame_cookbook_official.md` | ~22 | Official Autodesk Python API code samples. |\n| `flame_reference_guide.md` | ~30 | Troubleshooting + env-setup reference. |\n| `flame_ocr_patterns.md` | ~15 | OCR-extracted patterns (v1 pipeline). |\n| `flame_ocr_patterns_v2.md` | ~23 | OCR-extracted patterns (v2 pipeline). |\n| `flame_openclip_patterns.md` | ~8 | OpenCLIP pattern extractor outputs. |\n| `flame_vocabulary.md` | ~8 | Flame-specific terminology glossary — operators vs. the Python API names. |\n| `wiretap_sdk_python_reference.md` | ~76 | Wiretap Python SDK — low-level bridge from `flame` module to the Wiretap server. |\n| `wiretap_cli_reference.md` | ~38 | Wiretap command-line reference — `wiretap_print_tree`, `wiretap_duplicate_node`, etc. |\n<!-- concept:rag_corpus_docs end -->\n\n### How it learns (3-level system)\n\n1. `search_flame_docs` returns the **max relevance score** of the best match\n2. If **score < 60%**, the pattern is not well-documented — Claude is warned\n3. After a **successful** `execute_python`, Claude calls `learn_pattern(description, code)`\n4. Outcome depends on the active model's trust level:\n   - **Write-trusted model** (Opus / Fable) → appended to `FLAME_API.md`, index rebuilt in background\n   - **Sonnet** (the default cloud model) is **not** write-trusted → its proposals are staged to `rag/candidates.json` for human review, same as the read-only local models\n   - **Read-only model** (Qwen, Llama…) → staged in `rag/candidates.json` for human review\n5. On **failed** execution with low RAG score → logged to `rag/failed.json` as a knowledge gap\n6. Next session, verified patterns return >70% relevance instantly\n\n### Manually rebuild the index\n\n```bash\ncd ~/flame-mcp\nsource .venv/bin/activate\npython -m flame_mcp.rag.build_index\n```\n\n### RAG log\n\nEvery search query, its results, and relevance scores are logged to:\n```\nlogs/flame_rag.log\n```\n\n---\n\n## Token tracking\n\nEvery tool call appends a compact stats footer:\n\n```\n─────────────────────────────\n🔍 RAG · max relevance 72% · ~210 tokens · ~1290 avoided vs full doc\n📊 Session · 3 exec · 2 RAG\n   Tokens used             : ~640  🟢 low\n   Avoided by RAG/tools    : ~2580  (80% of context)\n```\n\nRatings:\n- 🟢 low — under 100 tokens for the call\n- 🟡 medium — 100–400 tokens\n- 🔴 high — over 400 tokens\n\n`session_stats()` gives the full session breakdown including how many patterns were auto-learned (`🧠 self-improved!`).\n\n> **Note:** Token cost warnings (🟡 🔴) are only shown when using Anthropic cloud models. For Ollama backends (local or cloud) they are suppressed — there are no rate limits or token costs involved.\n\n---\n\n## Project structure\n\n```\nflame-mcp/\n├── src/flame_mcp/server.py     # MCP server — runs on macOS, talks to Claude\n├── hooks/\n│   └── flame_mcp_bridge.py    # Flame hook — Unix socket bridge + Qt chat widget\n├── src/flame_mcp/rag/\n│   ├── build_index.py         # Build / rebuild the ChromaDB index\n│   └── search.py              # Semantic search, returns (text, max_score)\n├── rag/\n│   ├── corpus.json            # Chunked corpus (BM25 source, git-tracked)\n│   └── index/                 # ChromaDB vector store (git-ignored)\n├── docs/skills/               # Claude Code skills (symlinked into ~/.claude/skills/)\n│   ├── flame-batch-authoring/ # Batch/BFX graph authoring contract\n│   └── flame-delivery/        # Render → export → review Version → open clip\n├── FLAME_API.md               # Flame Python API reference + patterns (RAG source)\n├── CLAUDE.md                  # Instructions for Claude Code terminal context\n├── claude_desktop_config.json # Claude Desktop MCP config (copy to ~/Library/...)\n├── requirements.txt\n├── install.sh\n├── LICENSE\n├── logs/\n│   ├── flame_mcp_bridge.log   # bridge activity log\n│   └── flame_rag.log          # RAG query log with relevance scores\n└── docs/\n    ├── flame-mcp-reference.pdf      # Full reference guide\n    ├── FLAME_API.md                 # (root) Core API + self-learned patterns\n    ├── flame_advanced_api.md        # Action, Color Mgmt, Exporter, Conform, TL FX\n    ├── flame_segment_timeline_api.md# PySegment, PyClip.render, PyBatch.create_batch_group\n    ├── flame_community_workflows.md # Logik Forum operator jargon → API\n    ├── flame_cookbook_official.md   # Official Autodesk Python code samples\n    └── flame_vocabulary.md          # Operator terminology glossary\n```\n\n---\n\n## Ollama setup (optional)\n\nThree Ollama-based backends are available, covering every scenario:\n\n```\n┌─────────────────┬──────────────────────┬────────────────────────────────────┐\n│ Backend         │ Physical path        │ Use case                           │\n├─────────────────┼──────────────────────┼────────────────────────────────────┤\n│ ollama          │ Mac → gpu-server LAN │ Best quality, big GPU model        │\n│ ollama_cloud ☁  │ Mac localhost → ☁    │ Anywhere with internet, no GPU     │\n│ ollama_mac  🍎  │ Mac localhost        │ Offline emergency, no internet     │\n└─────────────────┴──────────────────────┴────────────────────────────────────┘\n```\n\n`ollama_cloud` and `ollama_mac` both require **Ollama installed on the Mac** — a lightweight daemon (~50 MB, no models bundled) that listens at `localhost:11434` and implements the Anthropic Messages API. For cloud models it acts as a transparent proxy to ollama.com; for local models it runs them directly using Mac CPU/GPU.\n\n> Ollama was **not** previously required on the Mac — it only ran on gpu-server. This is a new requirement for the two Mac-based backends.\n\n### Option 1 — Self-hosted GPU (ollama backend)\n\nBest quality. Runs on the Linux workstation (gpu-server) with a dedicated GPU.\n\n**On the Linux machine (gpu-server):**\n\n```bash\n# Install Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# Allow remote connections and keep models warm\nsudo systemctl edit ollama --force --full\n# Add under [Service]:\n#   Environment=\"OLLAMA_HOST=0.0.0.0:11434\"\n#   Environment=\"OLLAMA_KEEP_ALIVE=10m\"\n#   Environment=\"OLLAMA_NEW_ENGINE=true\"\nsudo systemctl restart ollama\n\n# Pull the models defined in AVAILABLE_MODELS (hooks/flame_mcp_bridge.py)\nollama pull qwen3.5:9b\nollama cp qwen3.5:9b qwen3.5-mcp          # matches the `qwen3.5-mcp` tag\n# NOTE: glm-4.7-flash is NOT recommended — tool-calling broken in Ollama\n# (upstream issues #13820/#13840, as of June 2026; real download size ~19 GB q4).\n# The model remains in AVAILABLE_MODELS for existing users. Prefer qwen3.5-mcp.\nollama pull glm-4.7-flash                  # matches the `glm-4.7-flash` tag\n```\n\n**In the Flame widget:**\n1. Select **Qwen3.5 9B 🖥** from the model dropdown (GLM-4.7 Flash is not recommended — see note above)\n2. Enter the server URL (e.g. `http://192.168.1.50:11434`) and press Enter\n3. The combo label updates to show `· gpu-server` confirming the server is saved\n\n> **GPU requirements:** Qwen3.5 9B (~6.6 GB Q4_K_M) needs ~8+ GB VRAM with `num_ctx=24576` set at runtime by the bridge. The bridge pre-flight overrides Modelfile `num_ctx` on every session (Ollama's Anthropic-compat endpoint ignores it otherwise). GLM-4.7 Flash (~19 GB q4) requires at least ~20 GB VRAM and is NOT recommended due to tool-calling bugs in Ollama (issues #13820/#13840).\n\n### Option 2 — Ollama cloud proxy (ollama_cloud backend)\n\nFree 480B parameter model running on ollama.com's infrastructure. Works anywhere with internet, no GPU required. Requires Ollama on the Mac.\n\n**On the Mac (one-time setup):**\n\n```bash\nbrew install ollama\n# Start the daemon (add to login items if you want it always running)\nollama serve\n```\n\n**In the Flame widget:**\n1. Select **qwen3-coder 480B ☁** from the model dropdown\n2. The combo shows `· localhost → ☁` — no further configuration needed\n3. On first use the model tag `qwen3-coder:480b-cloud` is downloaded automatically\n\nThe Mac daemon forwards the request to ollama.com's servers. Authentication with ollama.com is handled by the daemon using your logged-in account — no API key needed in the widget.\n\n> To log in to ollama.com from the Mac: `ollama login` in Terminal.\n\n### Option 3 — Mac offline fallback (ollama_mac backend)\n\nSmall model stored locally on the Mac. Works with no internet and no gpu-server — useful when working remotely on a laptop.\n\n**On the Mac (one-time setup, ~3 GB download):**\n\n```bash\nbrew install ollama\nollama serve\nollama pull qwen3.5:4b\n```\n\n**In the Flame widget:**\n1. Select **Qwen3.5 4B 🍎** from the model dropdown\n2. The combo shows `· localhost` — ready to use offline\n\n> The 4B tag (`qwen3.5:4b`) is pulled directly — no `ollama cp` alias needed. The larger **Qwen3.5 9B 🍎** option (`qwen3.5-mcp`) requires `ollama pull qwen3.5:9b && ollama cp qwen3.5:9b qwen3.5-mcp` first. Both IDs are the offline (`ollama_mac`) entries in the bridge's `AVAILABLE_MODELS`.\n\nQuality is significantly lower than the 30B or 480B models. Runs on Mac CPU (no GPU required); response time is slower than GPU backends.\n\n> ⚠️ **Tool use limitation:** small (4B–9B) models often fail to invoke MCP tools correctly — they may print raw JSON instead of executing the tool call. This backend is best suited for text queries (API questions, code explanations) rather than live Flame control. For actual Flame operations use `anthropic`, `ollama`, or `ollama_cloud`.\n\n### How the backends work internally\n\nOllama implements the [Anthropic Messages API](https://ollama.com/blog/claude) natively (v0.14+). The bridge sets `ANTHROPIC_BASE_URL` before launching the `claude` CLI subprocess:\n\n- `ollama` → `http://<ollama_url>` (gpu-server LAN address)\n- `ollama_cloud` → `http://localhost:11434` (Mac daemon → cloud proxy)\n- `ollama_mac` → `http://localhost:11434` (Mac daemon → local model)\n\nFor the `ollama` (LAN GPU) backend only, the bridge also sends a pre-flight request to Ollama's native `/api/generate` endpoint to force-load the model with the correct context window. This is necessary because Ollama's Anthropic-compatible endpoint ignores the `num_ctx` set in a Modelfile.\n\n---\n\n## Flame hook locations\n\nFlame loads Python hooks at startup from these paths (in order of priority):\n\n| Path | Scope |\n|------|-------|\n| `$DL_PYTHON_HOOK_PATH` | Custom environment variable |\n| `/opt/Autodesk/shared/python/` | All installed Flame versions |\n| `/opt/Autodesk/<version>/python/` | Specific Flame version |\n| `/opt/Autodesk/user/<username>/python/` | Specific system user |\n\nThis project uses `/opt/Autodesk/shared/python/` so the bridge works across all Flame versions.\n\n---\n\n## Troubleshooting\n\n**Claude can't connect to Flame**\n- Make sure Flame is open\n- Check `MCP Bridge → Status` in the Flame menu\n- Verify `flame_mcp_bridge.py` is in `/opt/Autodesk/shared/python/`\n- Check the Unix socket exists: `ls -la ~/flame-mcp/run/flame_mcp.sock` — should be `srw-------`\n- If the socket is absent the bridge is not running: there is no TCP fallback. Check Flame's console for the `[FlameMCPBridge] Active on …` line\n\n**Low RAG relevance scores on common operations**\n- If a pattern scores < 60%, Claude will auto-learn it after a successful run\n- You can also manually rebuild the index: `python -m flame_mcp.rag.build_index`\n\n**Claude Chat (embedded) doesn't open**\n- Check `logs/flame_mcp_bridge.log` for error details\n- Ensure the `claude` CLI is installed and signed in; if it is not found, set `CLAUDE_PATH` in your environment or in `~/flame-mcp/.env`\n- Flame 2026+ uses PySide6; older versions use PySide2 (both supported)\n\n**Ollama model runs on CPU instead of GPU**\n- Check `journalctl -u ollama -n 50` for `library=cpu` or `offloaded 0/N layers`\n- Ensure CUDA is initialised: `python3 -c \"import ctypes; print(ctypes.CDLL('libcuda.so.1').cuInit(0))\"`  — should return `0`; if `999`, reboot the Linux machine\n- Add Ollama's CUDA libs to ldconfig: create `/etc/ld.so.conf.d/ollama-cuda.conf` with `/usr/local/lib/ollama/cuda_v12` and run `sudo ldconfig`\n- Set `OLLAMA_NEW_ENGINE=true` in the systemd override\n\n**Ollama model truncates context (`truncating input prompt: limit=4096`)**\n- The Anthropic-compatible endpoint ignores Modelfile `num_ctx` — this is expected\n- The bridge fixes it automatically via a pre-flight `/api/generate` request; check the bridge log for `Ollama pre-load OK`\n- If the issue persists, verify the Modelfile has `PARAMETER num_ctx 24576` and the model was created with `ollama create`\n\n**Ollama cloud / mac-local: \"Ollama not found on this Mac\"**\n- Install and start the Mac daemon: `brew install ollama && ollama serve`\n- Verify it's running: `curl http://localhost:11434/api/version`\n- For `ollama_mac` only, also pull the model: `ollama pull qwen2.5-coder:7b`\n- For `ollama_cloud`, log in so the daemon can authenticate: `ollama login`\n\n**Ollama cloud model not responding**\n- The 480B model may take 2–5 minutes on first inference — the widget has a 5-minute watchdog\n- Check daemon logs: `journalctl --user -u ollama` (Linux) or `ollama serve` output (Mac)\n\n**The bridge will not start**\nThe bridge binds a UNIX domain socket and has **no fallback transport** — if the\nbind fails it says so on Flame's console and stops, rather than degrading to a\ntransport with no access control. Override the path with\n`FLAME_BRIDGE_SOCKET=/path/to/custom.sock`; keep it short, since `sun_path` is\ncapped near 104 bytes.\n\n**`pip install` fails with `--user` conflict**\nAdd `--no-user` to pip commands. Happens when `install.user = true` is set globally.\n\n---\n\n## Compatibility\n\n| Flame version | Internal Python | Qt       | Status |\n|---------------|----------------|----------|--------|\n| 2023          | 3.9.7          | PySide2  | ✓ Compatible |\n| 2024          | 3.9.x          | PySide2  | ✓ Compatible |\n| 2025          | 3.11.x         | PySide2  | ✓ Compatible |\n| 2026          | 3.11.5         | PySide6  | ✓ Tested |\n| 2027          | 3.13.3         | PySide6  | ✓ Tested |\n\n---\n\n## Ecosystem\n\n`flame-mcp` is part of a four-component VFX pipeline. Each component has a defined role:\n\n| Repo | Role |\n|------|------|\n| [flame-mcp](https://github.com/abrahamADSK/flame-mcp) | Controls Autodesk Flame for compositing, conform, and finishing |\n| [maya-mcp](https://github.com/abrahamADSK/maya-mcp) | Controls Autodesk Maya for 3D modeling, animation, and rendering |\n| [fpt-mcp](https://github.com/abrahamADSK/fpt-mcp) | Connects to Autodesk Flow Production Tracking (ShotGrid) for production tracking, asset management, and publishes |\n| [vision3d](https://github.com/abrahamADSK/vision3d) | GPU inference server for AI-powered 3D generation — the remote backend for maya-mcp's image-to-3D and text-to-3D tools |\n\n`flame-mcp` operates at the finishing stage of the pipeline. When both `fpt-mcp` and `flame-mcp` are active, Claude can query ShotGrid for shot status, resolve the correct media path, and execute Flame operations against it in a single conversation. `maya-mcp` can hand off rendered outputs that `flame-mcp` then picks up for conform and grade. `vision3d` is not directly consumed by `flame-mcp`.\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}