{"id":48654712,"url":"https://github.com/abrahamadsk/flame-mcp","last_synced_at":"2026-04-20T09:05:49.030Z","repository":{"id":342035635,"uuid":"1172530067","full_name":"abrahamADSK/flame-mcp","owner":"abrahamADSK","description":"MCP server for Autodesk Flame — clip control, timelines, and effects with RAG search, anti-hallucination safety, and self-learning","archived":false,"fork":false,"pushed_at":"2026-04-05T11:21:01.000Z","size":38037,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-05T13:11:44.615Z","etag":null,"topics":["autodesk-flame","chromadb","claude","compositing","flame-python","llm-tools","mcp","mcp-server","python","rag","vfx","vfx-pipeline"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abrahamADSK.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T12:15:54.000Z","updated_at":"2026-04-05T11:21:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abrahamADSK/flame-mcp","commit_stats":null,"previous_names":["abrahamadsk/flame-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/abrahamADSK/flame-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abrahamADSK%2Fflame-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abrahamADSK%2Fflame-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abrahamADSK%2Fflame-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abrahamADSK%2Fflame-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abrahamADSK","download_url":"https://codeload.github.com/abrahamADSK/flame-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abrahamADSK%2Fflame-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31635969,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autodesk-flame","chromadb","claude","compositing","flame-python","llm-tools","mcp","mcp-server","python","rag","vfx","vfx-pipeline"],"created_at":"2026-04-10T09:01:00.199Z","updated_at":"2026-04-17T21:02:13.393Z","avatar_url":"https://github.com/abrahamADSK.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# flame-mcp\n\n\u003e Control Autodesk Flame with natural language using Claude and the Model Context Protocol (MCP).\n\n\u003e [!WARNING]\n\u003e **Experimental project — use at your own risk.**\n\u003e 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\u003e\n\u003e 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`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 (falls back to TCP port 4444 if AF_UNIX is unavailable). It receives Python code, executes it inside Flame's Python interpreter with full access to the `flame` module, and returns the result.\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.11 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) \u003e= 0.17.6 installed on your Mac, a Linux GPU server, or both\n  - macOS: `brew install ollama \u0026\u0026 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\u003e **Note on Python versions:** The MCP server runs on your system Python (3.11+). Code executed *inside* Flame uses Flame's bundled Python interpreter (Flame 2026 ships Python 3.11.5).\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 all 18 MCP tools allowed\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 (venv, dependencies, hook, Claude registration, RAG index) and prints PASS/FAIL/WARN/SKIP with remediation hints for each check. 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 TCP 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- Reads `ANTHROPIC_API_KEY` from environment or `~/flame-mcp/.env`\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 \u003creason\u003e` | 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\u003e **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 \u003creason\u003e` 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\u003c!-- concept:llm_backend_table start --\u003e\n| Backend | Models available (model IDs in backticks) | Requires | Works offline? |\n|---------|-------------------------------------------|----------|----------------|\n| anthropic | Claude Sonnet 4.6 (`claude-sonnet-4-6`), Claude Opus 4.7 (`claude-opus-4-7`) | Anthropic API key | ✗ |\n| ollama | Qwen3.5 9B (`qwen3.5-mcp`), GLM-4.7 Flash (`glm-4.7-flash`) | 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\u003c!-- concept:llm_backend_table end --\u003e\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### 3. Claude Code (terminal)\n\n```bash\ncd ~/flame-mcp\nsource .venv/bin/activate\nclaude\n```\n\nThen talk naturally:\n\n```\n\u003e List all libraries and reels\n\u003e Create a new reel called \"MASTER\" in Default Library\n\u003e Delete all reels named TEST, TEST2 from Default Library\n\u003e What's the current project frame rate?\n```\n\n---\n\n\u003c!-- concept:mcp_tool_count start --\u003e\n## MCP Tools (26)\n\u003c!-- concept:mcp_tool_count end --\u003e\n\n\u003c!-- concept:mcp_tool_table start --\u003e\n| Tool | Description |\n|------|-------------|\n| `execute_python` | Execute arbitrary Python code inside Flame with full API access |\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 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| `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 |\n| `rename_segments` | Rename a clip (all its segments) in a Flame library/reel |\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\u003c!-- concept:mcp_tool_table end --\u003e\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 \u003c 60%: warn         ← pattern may not be documented\nexecute_python(code)              ← run the code in Flame\n  └─ if score was \u003c 60% and ok:\n       learn_pattern(desc, code)  ← teach the system (self-improvement)\nsession_stats()                   ← show token summary\n```\n\n---\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\u003c!-- concept:rag_corpus_docs start --\u003e\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\u003c!-- concept:rag_corpus_docs end --\u003e\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 \u003c 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   - **Trusted model** (Sonnet / Opus) → appended to `FLAME_API.md`, index rebuilt in background\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 \u003e70% 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\u003e **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├── rag/\n│   ├── build_index.py         # Build / rebuild the ChromaDB index\n│   ├── search.py              # Semantic search, returns (text, max_score)\n│   └── index/                 # ChromaDB vector store (git-ignored)\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_api_full.md            # Extended API — sequences, tracks, projects\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\u003e 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 two 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\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 🖥** (or **GLM-4.7 Flash 🖥**) from the model dropdown\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\u003e **GPU requirements:** Qwen3.5 9B (~6.6 GB Q4_K_M) and GLM-4.7 Flash fit comfortably in a 24 GB GPU (RTX 3090) 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).\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\u003e 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, ~4 GB download):**\n\n```bash\nbrew install ollama\nollama serve\nollama pull qwen2.5-coder:7b\n```\n\n**In the Flame widget:**\n1. Select **qwen2.5-coder 7B 🍎** from the model dropdown\n2. The combo shows `· localhost` — ready to use offline\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\u003e ⚠️ **Tool use limitation:** 7B 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://\u003collama_url\u003e` (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/\u003cversion\u003e/python/` | Specific Flame version |\n| `/opt/Autodesk/user/\u003cusername\u003e/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 Unix socket is absent, the bridge falls back to TCP; run `lsof -i :4444` to confirm Flame is listening\n\n**Low RAG relevance scores on common operations**\n- If a pattern scores \u003c 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 `ANTHROPIC_API_KEY` is set 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 \u0026\u0026 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**Port 4444 is already in use**\nThe bridge uses a Unix domain socket by default (`~/flame-mcp/run/flame_mcp.sock`), so TCP port 4444 is only used as a fallback when AF_UNIX is unavailable. If you still need to change the TCP fallback port, edit `BRIDGE_PORT = 4444` in both `flame_mcp_bridge.py` and `src/flame_mcp/server.py`. To override the socket path: set `FLAME_BRIDGE_SOCKET=/path/to/custom.sock` in your environment.\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 preview  | 3.13.3         | PySide6  | ✓ Compatible |\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabrahamadsk%2Fflame-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabrahamadsk%2Fflame-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabrahamadsk%2Fflame-mcp/lists"}