# zkbkb/fusion-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/zkbkb/fusion-mcp
- Repository: https://github.com/zkbkb/fusion-mcp

## Overview

##### Project type and purpose
- This is a hybrid tool+plugin project: a Python-based MCP (Model Context Protocol) server plus a Fusion 360 add-in.
- Purpose: run a FastMCP server exposing 44 CAD “tools” over JSON-RPC/TCP to drive Fusion 360 via natural-language AI clients (Cursor, Claude).
- Dual-mode: “Plugin Mode” for production (real Fusion 360 API), “Simulation Mode” for development/testing (mock data).

##### File structure
- Top-level:
- setup.py, requirements.txt, install_addin.py, mcp_config.json
- src/ (all source code)
- tests/ subdivided into unit, integration, performance, platform
- src/ subdirectories:
- fusion360/ – the add-in code (addin.py + manifest)
- mcp_server.py – MCP server entrypoint using FastMCP
- tools/ – 5 tool categories (sketch, modeling, assembly, analysis, general utils)
- core/ – bridge.py (API bridge), config.py, resources.py
- context/ – persistence.py, tools.py (state & design-intent management)
- utils/ – error handling, logging, helpers, validators
- Configuration & build:
- mcp_config.json – example AI client config
- install_addin.py – script to copy plugin into Fusion 360 add-ins folder
- manifest file (FusionMCP.manifest) under src/fusion360

##### README for additional insights
- Lists core components with file locations and description (MCP Server, Socket Bridge, Fusion360 Plugin, Tool Modules, Context Manager, Core Bridge).
- Shows communication flow:
AI Command → MCP Client → stdio → MCP Server → TCP Socket → Fusion360 Plugin → Fusion360 API → CAD Operation.

a. Main components:
- AI Client (Cursor/Claude)
- MCP Server (FastMCP)
- Socket Bridge (Fusion360SocketBridge in core/bridge.py)
- Fusion 360 Plugin (addin.py + manifest)
- Fusion 360 Application & API
- Tool modules (sketch, modeling, assembly, analysis under src/tools/)
- Context Manager (persistence & tools for design history)
- Configuration & Logging (config.py, logging_config.py)
- External: MCP protocol (JSON-RPC 2.0), TCP Socket

b. Relationships and interactions:
- AI Client ↔ (JSON-RPC stdio) ↔ MCP Server
- MCP Server registers each tool (via decorators) and dispatches to tool modules
- MCP Server ↔ (TCP socket) ↔ Socket Bridge ↔ Fusion 360 Plugin
- Fusion 360 Plugin calls Fusion 360 API to perform CAD operations
- Context Manager persists design intent between tool calls
- Core Bridge handles mode switching (real vs simulation)

c. Architectural patterns & principles:
- Dual-mode operation: real vs mock environment
- Modular design: each tool category self-contained
- Asynchronous event-driven server (asyncio + FastMCP)
- Separation of concerns:
- API layer (core/bridge)
- Business logic (tools/)
- Persistence (context/)
- Plugin hosting (fusion360/)
- JSON-RPC 2.0 for tool invocation

d. Key technologies/frameworks:
- Python 3.8+
- FastMCP (Model Context Protocol server framework)
- asyncio, JSON-RPC
- TCP Sockets (localhost:8765)
- Fusion 360 API (adsk.core, adsk.fusion)
- pytest for testing

##### Final advice
- Be exhaustive: show all subcomponents (tools/, core/, context/, utils/)
- Both modes (production vs simulation)
- Three-layer call chain (AI → MCP → Plugin → API)
- Special features: asynchronous processing, design persistence, automatic mode switching

## Diagram (Mermaid)

```mermaid
graph TD
  classDef external fill:#cccccc,stroke:#333,stroke-width:1px
  classDef server fill:#ccffcc,stroke:#333,stroke-width:1px
  classDef plugin fill:#ffcc99,stroke:#333,stroke-width:1px
  classDef network fill:#99ccff,stroke:#333,stroke-width:1px
  classDef config fill:#eeeeee,stroke:#333,stroke-width:1px

  subgraph "External"
    AI["AI Client (JSON-RPC)"]:::external
  end

  AI -->|"JSON-RPC stdio"| MCP["MCP Server"]:::server

  subgraph "MCP Server"
    MSP["MCP Server\n(mcp_server.py)"]:::server
    subgraph "Tool Modules"
      SKETCH["Sketch Tools"]:::server
      MODEL["Modeling Tools"]:::server
      ASSEM["Assembly Tools"]:::server
      ANAL["Analysis Tools"]:::server
      UTILTOOLS["General Utils"]:::server
    end
    subgraph "Core Modules"
      BRIDGE["Fusion360SocketBridge\n(bridge.py)"]:::server
      CONFIG["Core Config\n(config.py)"]:::server
      RES["Core Resources\n(resources.py)"]:::server
    end
    subgraph "Context Manager"
      PERSIST["Persistence\n(persistence.py)"]:::server
      CONTEXT["State & Intent\n(tools.py)"]:::server
    end
    subgraph "Utilities"
      LOGCFG["Logging Config\n(logging_config.py)"]:::server
      ERR["Error Handling\n(error_handler.py)"]:::server
      VAL["Validators\n(validators.py)"]:::server
    end
    MSP -->|registers tools| SKETCH & MODEL & ASSEM & ANAL & UTILTOOLS
    MSP -->|uses| BRIDGE & CONFIG & RES & PERSIST & CONTEXT & LOGCFG & ERR & VAL
  end

  MCP -->|"TCP Socket (8765)"| BRIDGE
  BRIDGE -->|"Bridge TCP"| PLUGIN["Fusion 360 Plugin\n(addin.py)"]:::plugin
  PLUGIN -->|"calls"| API["Fusion 360 API"]:::plugin
  API -->|"exec CAD Op"| CAD["CAD Engine"]:::plugin

  MCP -->|"Simulation Mode"| SIM["Mock Tools"]:::server

  MCP -.-> CONFIGFILE["mcp_config.json"]:::config
  MCP -.-> REQ["requirements.txt"]:::config
  install["install_addin.py"]:::config --> PLUGIN

  click MSP "https://github.com/zkbkb/fusion-mcp/blob/main/src/mcp_server.py"
  click BRIDGE "https://github.com/zkbkb/fusion-mcp/blob/main/src/core/bridge.py"
  click CONFIG "https://github.com/zkbkb/fusion-mcp/blob/main/src/core/config.py"
  click RES "https://github.com/zkbkb/fusion-mcp/blob/main/src/core/resources.py"
  click PLUGIN "https://github.com/zkbkb/fusion-mcp/blob/main/src/fusion360/addin.py"
  click SKETCH "https://github.com/zkbkb/fusion-mcp/tree/main/src/tools/sketch/"
  click MODEL "https://github.com/zkbkb/fusion-mcp/tree/main/src/tools/modeling/"
  click ASSEM "https://github.com/zkbkb/fusion-mcp/tree/main/src/tools/assembly/"
  click ANAL "https://github.com/zkbkb/fusion-mcp/tree/main/src/tools/analysis/"
  click UTILTOOLS "https://github.com/zkbkb/fusion-mcp/blob/main/src/tools/utils.py"
  click PERSIST "https://github.com/zkbkb/fusion-mcp/blob/main/src/context/persistence.py"
  click CONTEXT "https://github.com/zkbkb/fusion-mcp/blob/main/src/context/tools.py"
  click LOGCFG "https://github.com/zkbkb/fusion-mcp/blob/main/src/utils/logging_config.py"
  click ERR "https://github.com/zkbkb/fusion-mcp/blob/main/src/utils/error_handler.py"
  click VAL "https://github.com/zkbkb/fusion-mcp/blob/main/src/utils/validators.py"
  click install "https://github.com/zkbkb/fusion-mcp/blob/main/install_addin.py"
  click CONFIGFILE "https://github.com/zkbkb/fusion-mcp/blob/main/mcp_config.json"
  click REQ "https://github.com/zkbkb/fusion-mcp/blob/main/requirements.txt"

  class AI external
  class MCP server
  class SIM server
  class API plugin
  class CAD plugin
```
