# dughogan/nuke_mcp architecture

> Architecture diagram of the GitHub repository dughogan/nuke_mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dughogan/nuke_mcp
- Repository: https://github.com/dughogan/nuke_mcp

## Overview

##### Project Type and Purpose
- This is an integration/middleware tool that bridges The Foundry’s Nuke application with AI systems via the Model Context Protocol (MCP).
- It consists of three runtime components: a Nuke Addon (in-process plugin), an external MCP Server (Python process), and an AI Client (e.g., Claude Desktop).

##### Main Components
a. AI Client
- Runs in a separate application (e.g., Claude Desktop).
- Uses FastMCP to speak MCP over a TCP socket.
b. MCP Server (nuke_mcp_server.py + main.py)
- A Python process you launch via `main.py`.
- Imports FastMCP, registers @mcp.tool() endpoints.
- Forwards tool calls to the Nuke Addon over a second socket.
c. Nuke Addon (nuke_mcp_addon.py)
- Runs inside Nuke via nukescripts.PythonPanel.
- Starts a socket server on startup.
- Implements handlers to create/modify/delete nodes, control playback, execute code.
d. Nuke Application
- Hosts the Addon and node graph UI.
e. Optional External Services
- Firewalls/network for socket connectivity.
- Asset management or template systems (future extension).

##### Relationships and Data Flows
1. AI Client ⇄ MCP Server (MCP protocol over TCP)
2. MCP Server ⇄ Nuke Addon (custom JSON commands over TCP)
3. Nuke Addon → Nuke API (nukescripts)

##### Architectural Patterns and Design Principles
- Client-server: decouples AI logic from Nuke process.
- Plugin architecture: Nuke Addon loads dynamically into host.
- Tool-based RPC: each @mcp.tool() is a remote procedure.
- Separation of concerns: UI (panel), transport (sockets), business logic (tools).

##### Technologies and Frameworks
- Python 3.7+
- FastMCP package for MCP protocol
- sockets (TCP) for communication
- nukescripts.PythonPanel for UI in Nuke
- JSON for payloads
- Context and logger utilities (in server and addon)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Layer
    Firewall["Firewall/Network"]:::external
    AssetMgmt["Asset Management\n(Template Systems)"]:::external

    %% Out-of-Process Layer
    subgraph "Out-of-Process (Python)"
        direction TB
        AIClient["AI Client\n(FastMCP over TCP)"]:::client
        MCPServer["MCP Server\n(main.py + nuke_mcp_server.py)"]:::server
    end

    %% In-Process Layer
    subgraph "In-Process (Nuke)"
        direction TB
        NukeAddon["Nuke Addon\n(nuke_mcp_addon.py)"]:::addon
        NukeApp["Nuke Application\n(nukescripts.UI & API)"]:::host
    end

    %% Documentation
    Documentation["Project Documentation\n(readme.md, nuke-mcp-guidelines.md)"]:::external

    %% Connections
    Firewall --> AIClient
    Firewall --> MCPServer
    Firewall --> NukeAddon

    AIClient -->|MCP/TCP| MCPServer
    MCPServer -->|JSON/TCP| NukeAddon
    NukeAddon -->|nukescripts API| NukeApp

    %% Click Events
    click MCPServer "https://github.com/dughogan/nuke_mcp/blob/main/main.py"
    click MCPServer "https://github.com/dughogan/nuke_mcp/blob/main/nuke_mcp_server.py"
    click NukeAddon "https://github.com/dughogan/nuke_mcp/blob/main/nuke_mcp_addon.py"
    click Documentation "https://github.com/dughogan/nuke_mcp/blob/main/readme.md"
    click Documentation "https://github.com/dughogan/nuke_mcp/blob/main/nuke-mcp-guidelines.md"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef server fill:#C8E6C9,stroke:#66BB6A,color:#1B5E20;
    classDef addon fill:#FFECB3,stroke:#FFD54F,color:#BF360C;
    classDef host fill:#FFCDD2,stroke:#EF9A9A,color:#B71C1C;
    classDef external fill:#E0E0E0,stroke:#BDBDBD,color:#424242;
```
