blenderwright 2.0.0__tar.gz

blenderwright-2.0.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: jabberwock

blenderwright-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install ruff==0.15.7
+      - run: ruff check .
+
+  security:
+    name: Security (bandit + pip-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install bandit pip-audit
+      - name: Upgrade build tooling
+        # The runner image ships its own setuptools/pip. pip-audit reports
+        # vulnerabilities in those even though this project does not depend
+        # on them (the build backend is hatchling), so keep them current
+        # rather than let runner drift fail the build.
+        run: pip install --upgrade pip setuptools wheel
+      - name: bandit
+        run: bandit -r src/ -ll  # low severity threshold; skip install_addon.py (subprocess by design)
+      - name: Install project dependencies
+        run: pip install -e ".[dev]"
+      - name: pip-audit
+        # Audits the environment, which now contains this project's declared
+        # dependencies. The upgrade step above keeps the runner's own build
+        # tooling current so drift in the image does not fail the build.
+        run: pip-audit
+
+  tests:
+    name: Tests (${{ matrix.os }} / Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v --tb=short --ignore=tests/test_addon
+
+  coverage:
+    name: Tests + Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests with coverage
+        run: pytest tests/ --cov=src/blenderwright --cov-report=term-missing --ignore=tests/test_addon

blenderwright-2.0.0/.github/workflows/pylint.yml

@@ -0,0 +1,24 @@
+name: Pylint
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint
+        pip install -e .
+    - name: Lint MCP server
+      run: |
+        pylint src/blenderwright/ --disable=C,R,W0622 --fail-under=9.0

blenderwright-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  build-extension:
+    name: Build extension zip
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download Blender 4.2 LTS
+        run: |
+          curl -sSfL -o blender.tar.xz \
+            https://download.blender.org/release/Blender4.2/blender-4.2.0-linux-x64.tar.xz
+          mkdir -p blender
+          tar -xf blender.tar.xz -C blender --strip-components=1
+          echo "$PWD/blender" >> "$GITHUB_PATH"
+
+      - name: Validate manifest
+        run: blender --command extension validate addon/
+
+      - name: Build extension zip
+        run: |
+          mkdir -p dist
+          blender --command extension build --source-dir addon --output-dir dist
+          ls -la dist/
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: blenderwright-extension
+          path: dist/blenderwright-*.zip
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/blenderwright-*.zip
+          generate_release_notes: true
+          draft: false
+          prerelease: false
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Refuse to publish a version that does not match the tag
+        run: |
+          version="$(uv version --short)"
+          test "v${version}" = "${GITHUB_REF_NAME}" || {
+            echo "pyproject version ${version} does not match tag ${GITHUB_REF_NAME}"; exit 1; }
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

blenderwright-2.0.0/.github/workflows/test-bpy51.yml

@@ -0,0 +1,32 @@
+name: Handler Tests (bpy 5.1)
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  handler-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install bpy==5.1.0
+          pip install pytest pytest-cov
+
+      - name: Run handler tests
+        run: pytest tests/test_addon/test_handlers/ -v --tb=short
+
+      - name: Run full test suite
+        run: |
+          pip install -e ".[dev]"
+          pytest tests/ -v --tb=short

blenderwright-2.0.0/.gitignore

@@ -0,0 +1,31 @@
+blenderwright-v*.zip
+blenderwright_addon*.zip
+.DS_Store
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+*.blend1
+*.blend2
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+.claude/
+.python-version
+CLAUDE.md
+README.html
+
+# Planning artifacts - do not reintroduce
+.planning/
+ollama-config.json

blenderwright-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HoldMyBeer-gg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blenderwright-2.0.0/PKG-INFO

@@ -0,0 +1,386 @@
+Metadata-Version: 2.5
+Name: blenderwright
+Version: 2.0.0
+Summary: The most intuitive and efficient MCP Server for Blender
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.26.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: chat
+Requires-Dist: ollama>=0.4; extra == 'chat'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# blenderwright
+
+<small>Formerly blend-ai. Same project, new name, nothing else changed.</small>
+
+The most intuitive and efficient MCP Server for Blender. Control Blender entirely through AI assistants like Claude: create 3D models, set up scenes, animate, render, and more, all through natural language.
+
+**blenderwright goes beyond tool exposure: it guides the LLM to produce professional 3D results** through expert prompts, proven workflows, visual feedback, and mesh quality analysis.
+
+<small>A two-storey Western saloon from a single sentence: "create a Western style 2-story saloon, the outside is more important than any inside detail." Claude Code (Fable 5.1) built the false front, plank siding, balcony, batwing doors and street dressing, then relit it for dusk, all through blenderwright, in about twenty minutes with no manual modelling:</small>
+
+![blenderwright saloon built from one prompt](./saloon.png)
+
+<small>This was created via Claude Code using the Haiku model and 20 random reference images. It took 5 minutes:</small>
+
+![blenderwright screenshot](./screenshot.png)
+
+<small>Fifteen procedural materials, each built by a single `create_procedural_material` call. The selected ball's node graph below was generated entirely by that one call: coordinates, mapping, noise, height mask, colour ramp, and Principled BSDF, laid out and wired:</small>
+
+![blenderwright procedural shader preview](./shader-preview.png)
+
+## Key Features
+
+- **[186 tools](https://blenderwright.holdmybeer.gg/)** across 27 modules covering every major Blender domain: modeling, mesh editing, materials, shader nodes, lighting, camera, animation, rendering, sculpting, UV mapping, physics, geometry nodes, rigging, curves, sweeps along a path, 3D-print checking, annotations, collections, file I/O, Bool Tool, viewport control, mesh quality analysis, and extension suggestions
+- **12 expert prompts**: topology best practices, real-world scale references, lighting principles, studio setup, character basemesh workflow, PBR material guide, auto-critique feedback loop, and more
+- **Visual feedback loop**: fast viewport screenshots via OpenGL render (~ms, not seconds) with auto-critique prompts that guide the LLM to check its own work
+- **Mesh quality analysis**: structured reports covering non-manifold edges, loose vertices, zero-area faces, duplicate vertices, and wire edges
+- **Extension suggestions**: proactively recommends Bool Tool, LoopTools, and Node Wrangler when a task would benefit from them (skips already-installed extensions)
+- **Sandboxed code execution**: `execute_blender_code` blocks dangerous imports (`os`, `subprocess`, `socket`, etc.) and dangerous builtins (`exec`, `eval`, `open`) while allowing safe Blender operations
+- **Render-aware**: automatically detects when Blender is rendering and queues commands. Recovers from stuck render guards via `load_post` handler and reset command
+- **Blender 4.2+ compatible**: ships as a Blender Extension; tested against Blender 5.1 with EEVEE identifier, Annotation API, sculpt stroke_method, SLIM UV unwrap, Raycast shader node, and EEVEE light path intensity controls
+- **Custom port**: configure the server port from the N-panel UI (default: 9876, range: 1024–65535)
+- **Zero telemetry**: no usage tracking, no analytics, no data collection. Everything runs locally on `127.0.0.1`
+- **Zero-dependency addon**: the Blender addon uses only Python stdlib + `bpy`. Nothing to pip install inside Blender
+- **Thread-safe architecture**: background TCP server with queue-based main-thread execution, TCP keepalive for stale connection detection
+- **1190 tests**: coverage across tools, handlers, validators, prompts, and the cross-platform installer (ubuntu/macos/windows × py3.11/3.13 in CI)
+
+## Quickstart
+
+### 1. Install the MCP server
+
+```bash
+git clone https://github.com/HoldMyBeer-gg/blenderwright.git
+cd blenderwright
+uv pip install -e .
+```
+
+### 2. Install the Blender addon
+
+1. Download the latest addon zip from [GitHub Releases](https://github.com/HoldMyBeer-gg/blenderwright/releases)
+2. Open Blender 4.2 or later
+3. Go to **Edit > Preferences > Get Extensions**, click the dropdown (▾) top-right, and choose **Install from Disk...**
+4. Select the downloaded `.zip` file
+5. Enable **"blenderwright"** in the extensions list
+
+> **Blender 4.0 / 4.1 users:** Not supported. blenderwright ships as a Blender Extension, which requires Blender 4.2 (LTS) or later. Please upgrade Blender from [blender.org/download](https://www.blender.org/download/).
+
+<details>
+<summary><strong>Developer install (symlink)</strong></summary>
+
+If you're developing on blenderwright, symlink the addon folder into Blender's user extensions directory instead. Replace `<ver>` with your Blender version (e.g. `4.2`, `5.1`).
+
+```bash
+# macOS
+ln -s "$(pwd)/addon" ~/Library/Application\ Support/Blender/<ver>/extensions/user_default/blenderwright
+
+# Linux
+ln -s "$(pwd)/addon" ~/.config/blender/<ver>/extensions/user_default/blenderwright
+
+# Windows (run as admin)
+mklink /D "%APPDATA%\Blender Foundation\Blender\<ver>\extensions\user_default\blenderwright" "%cd%\addon"
+```
+
+Then enable the extension in Blender preferences under **Get Extensions > User**.
+
+</details>
+
+### 3. Start the server in Blender
+
+In Blender's 3D Viewport, open the **N-panel** (press `N`), find the **blenderwright** tab. Set your preferred port (default: 9876), then click **Start Server**.
+
+### 4. Connect your AI assistant
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add blenderwright -- uv run --directory /path/to/blenderwright blenderwright
+```
+
+Replace `/path/to/blenderwright` with the actual path to your clone. Make sure Blender is running with the addon server started before using the tools.
+
+**Usage:**
+
+```
+$ claude
+
+> Create a red metallic sphere on a white plane with three-point lighting
+
+> Add a subdivision surface modifier to the sphere and set it to level 3
+
+> Analyze the mesh quality of the sphere and fix any issues
+
+> Set up a turntable animation and render it to /tmp/turntable/
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add blenderwright to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "blenderwright": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/blenderwright", "blenderwright"]
+    }
+  }
+}
+```
+
+Replace `/path/to/blenderwright` with the actual path to your clone.
+
+Restart Claude Desktop. The Blender tools will appear in the tool list.
+
+</details>
+
+<details>
+<summary><strong>Other MCP Clients</strong></summary>
+
+blenderwright is a standard MCP server using stdio transport. Any MCP-compatible client can connect by running the server directly:
+
+```bash
+uv run --directory /path/to/blenderwright blenderwright
+# or: python -m blenderwright.server
+```
+
+The exact config location and format vary by client (typically JSON or TOML under `~/.<client>/`). The `command` is `uv` and the `args` are `["run", "--directory", "/path/to/blenderwright", "blenderwright"]`.
+
+The server communicates over stdin/stdout using the MCP protocol. It connects to Blender's addon over TCP on `127.0.0.1:9876` (or your configured port).
+
+</details>
+
+## Updating
+
+Whichever way you installed, **Blender must be fully restarted**, not "Reload Scripts".
+The addon runs a background TCP server thread that survives a script reload, so reloading
+leaves a stale handler registered and the old socket still bound.
+
+### One command (zip installs)
+
+```bash
+python install_addon.py upgrade
+```
+
+With no argument it finds your Blender installations and offers them as a numbered
+list, so there is no path to get wrong. You can still pass one explicitly:
+
+```bash
+# macOS - the binary inside the bundle, not the .app itself
+python install_addon.py upgrade /Applications/Blender.app/Contents/MacOS/Blender
+
+# Linux
+python install_addon.py upgrade /usr/local/bin/blender
+
+# Windows
+python install_addon.py upgrade "C:\Program Files\Blender Foundation\Blender 4.2\blender.exe"
+```
+
+It refuses to run while Blender is open, checks the path before touching anything,
+removes every blenderwright install across *all* Blender version directories, rebuilds the
+zip from `addon/`, and installs it through Blender's own extension machinery. It also
+handles the case that bites people most: an older copy left behind under a previous
+Blender version.
+
+Two companion commands:
+
+```bash
+python install_addon.py doctor          # list every blenderwright install found, and where
+python install_addon.py uninstall --yes # remove them all (omit --yes for a dry run)
+```
+
+Start with `doctor` if the addon is behaving strangely: a duplicate install under an
+old Blender version is the usual cause.
+
+### Developer symlink installs
+
+If you symlinked `addon/` into Blender's extensions directory, there is nothing to
+install. `git pull` and restart Blender. Use `doctor` to confirm which kind of install
+you have; it reports symlinks distinctly.
+
+### By hand, through the GUI
+
+<details>
+<summary><strong>Manual steps, if you would rather not run the script</strong></summary>
+
+1. If the server is running, open the N-panel **blenderwright** tab and click **Stop Server**.
+2. In Blender, open **Edit > Preferences > Get Extensions**, find **blenderwright**, and click **Uninstall**.
+3. Quit and restart Blender (this clears cached `blenderwright` modules).
+4. Install the new `.zip` via the **▾ > Install from Disk...** menu and enable it.
+
+</details>
+
+## Expert Guidance
+
+blenderwright includes 12 MCP prompts that guide the LLM toward professional-quality results:
+
+| Prompt | What It Teaches |
+|--------|----------------|
+| `blender_best_practices` | Bool Tool preference, mesh editing patterns, modifier workflow |
+| `topology_best_practices` | Quad topology, edge flow, poles, n-gon cleanup, face density |
+| `scale_reference_guide` | Real-world dimensions for 8 common objects, unit system setup |
+| `lighting_principles` | Three-point lighting, HDRI, EEVEE vs Cycles, color temperature |
+| `studio_lighting_setup` | 6-step studio lighting workflow with specific energy values |
+| `character_basemesh_workflow` | 7-step character base mesh from cube with mirror + subdivision |
+| `material_workflow_guide` | PBR materials, Principled BSDF recipes, texture color spaces |
+| `auto_critique_workflow` | Visual feedback loop: when to screenshot, what to check, token budget |
+| `product_shot_setup` | Professional product shot setup guide |
+| `character_base_mesh` | Character modeling guide |
+| `scene_cleanup` | Scene organization workflow |
+| `animation_turntable` | Turntable animation setup |
+
+## Tool Domains
+
+<details>
+<summary><strong>All 186 tools across 27 modules</strong></summary>
+
+Full reference with every parameter: **[blenderwright.holdmybeer.gg](https://blenderwright.holdmybeer.gg/)**
+
+| Domain | Tools | Highlights |
+|--------|-------|-----------|
+| Scene | 6 | Get scene info, set frame range, manage scenes, suggest helpful extensions |
+| Objects | 15 | Create primitives, duplicate, parent, join, visibility, origin, convert, auto-smooth |
+| Transforms | 6 | Position, rotation (euler/quat), scale, apply, snap |
+| Modeling | 13 | Modifiers, booleans, subdivide, extrude, bevel, loop cut, bridge edge loops |
+| Mesh Editing | 16 | Inset, fill, grid fill, mark seam/sharp, normals, dissolve, knife project, spin, crease |
+| Selection | 6 | Select by index, by axis, by face sides, by similarity; invert; report what is selected |
+| Mesh Quality | 3 | Analyze mesh defects: non-manifold, loose verts, zero-area faces, duplicates and repair them; decimate to reduce polycount |
+| Bool Tool | 4 | Auto union, difference, intersect, slice (via Blender's Bool Tool addon) |
+| Materials | 25 | Principled BSDF, procedural and raster textures, textures, blend modes, shader node graph (add/connect/remove nodes, including 5.1 Raycast node) |
+| Lighting | 7 | Point/sun/spot/area lights, HDRIs, light rigs, shadows |
+| Camera | 6 | Create, aim, DOF, viewport capture, active camera |
+| Animation | 8 | Keyframes, interpolation, frame range, follow path |
+| Rendering | 7 | Engine, resolution, samples, output format, render, EEVEE light path intensity |
+| Curves | 10 | Bezier/NURBS/path, 3D text, convert, reverse, handle types, cyclic, subdivide |
+| Sweep | 2 | Sweep a profile along a 3D path for tubes, hoses, cables and rails, with flip-free framing; check a path for bends too tight for the profile |
+| 3D Printing | 1 | Reversed normals, self-intersection, thin walls, shells and overhangs via Blender's 3D Print Toolbox |
+| Sculpting | 8 | Brushes, remesh, multires, symmetry, dynamic topology, stroke_method |
+| UV Mapping | 4 | Smart project, unwrap (ANGLE_BASED, CONFORMAL, SLIM), projection, pack islands |
+| Physics | 9 | Rigid body, cloth, fluid, particles (velocity, rendering, delete), bake |
+| Geometry Nodes | 5 | Create node trees, add/connect nodes, set inputs |
+| Armature | 6 | Bones, constraints, auto weights, pose |
+| Annotations | 5 | Annotation layers and strokes (5.1 Annotation API) |
+| Collections | 4 | Create, move objects, visibility, delete |
+| File I/O | 5 | Import/export (FBX, OBJ, glTF, USD, STL...), save/open |
+| Viewport | 3 | Shading mode, overlays, focus on object |
+| Screenshot | 1 | Fast viewport capture (OpenGL) or full render, base64 output |
+| Code Exec | 1 | Sandboxed Python execution in Blender (dangerous imports blocked) |
+
+</details>
+
+## Architecture
+
+```
+AI Assistant <--stdio/MCP--> blenderwright server <--TCP socket--> Blender addon <--bpy--> Blender
+```
+
+<details>
+<summary><strong>How it works</strong></summary>
+
+- **MCP Server** (`src/blenderwright/`): Python process using the `mcp` SDK. Exposes tools, resources, and prompts over stdio. Validates all inputs before forwarding to Blender.
+- **Blender Addon** (`addon/`): Runs a TCP socket server inside Blender on a background thread. Commands are queued and executed on the main thread via `bpy.app.timers` to respect Blender's threading model.
+- **Render Guard**: Tracks render state via `bpy.app.handlers`. During renders, the server immediately returns a "busy" status. Automatically recovers from crashed renders via `load_post` handler. Can be force-reset via MCP command.
+- **Protocol**: Length-prefixed JSON messages over TCP with SO_KEEPALIVE for stale connection detection. Each message is a 4-byte big-endian length header followed by a UTF-8 JSON payload.
+
+</details>
+
+## Privacy & Security
+
+<details>
+<summary><strong>Privacy</strong></summary>
+
+- **Zero telemetry**: blenderwright collects no usage data, sends no analytics, and makes no network requests beyond the local TCP connection to Blender.
+- **Fully local**: all communication stays on your machine. No cloud services, no external APIs, no phone-home behavior.
+- **Open source**: the entire codebase is auditable. What you see is what runs.
+
+</details>
+
+<details>
+<summary><strong>Security</strong></summary>
+
+- **Localhost only**: The TCP socket binds to `127.0.0.1`, never exposed to the network.
+- **Sandboxed code execution**: `execute_blender_code` blocks 25 dangerous imports (`os`, `subprocess`, `socket`, `shutil`, `sys`, `ctypes`, `importlib`, `pathlib`, `signal`, `multiprocessing`, `pickle`, `shelve`, `tempfile`, `http`, `urllib`, `ftplib`, `smtplib`, `xmlrpc`, `code`, `codeop`, `compileall`, `webbrowser`, `antigravity`, `turtle`, `tkinter`) and removes dangerous builtins (`__import__`, `exec`, `eval`, `compile`, `open`, `globals`, `locals`, `vars`, `input`, `breakpoint`, `exit`, `quit`, `help`, `memoryview`). Safe Blender imports (`bpy`, `bmesh`, `mathutils`, `math`, `json`) are allowed.
+- **Input validation**: All inputs pass through validators before reaching Blender: name sanitization, path traversal prevention, numeric range checks, enum allowlists.
+- **File safety**: Import operations disable `use_scripts_auto_execute` to prevent script injection from imported files. File extensions are checked against allowlists.
+- **Command allowlist**: The addon dispatcher only processes explicitly registered commands. Unknown commands are rejected.
+- **Shader node allowlist**: Only 64 known shader node types can be created, which prevents arbitrary type injection.
+
+</details>
+
+## Limitations
+
+<details>
+<summary><strong>Known limitations</strong></summary>
+
+- **Blender must be running**: The MCP server communicates with Blender over TCP. Blender must be open with the addon enabled and server started.
+- **Single connection**: The addon accepts one client connection at a time. Multiple AI assistants cannot control the same Blender instance simultaneously.
+- **Selection is persistent, not per-call**: Selection lives on the mesh in Blender, so it stays set between calls. Choose geometry with the `select_*` tools, then pass `selection="CURRENT"` to a mesh tool. The default is still `"ALL"`. Because the selection is shared state, two assistants working on the same mesh would step on each other.
+- **Sculpt strokes cannot be simulated**: You can configure brushes, symmetry, dyntopo, and remeshing, but actual brush strokes are not yet exposed.
+- **Node graphs require sequential calls**: Both shader node trees and geometry node trees must be built one node/connection at a time.
+- **No undo integration**: Operations appear in Blender's undo history individually but there's no MCP-level undo/redo or transaction grouping.
+- **Viewport capture requires a visible 3D viewport**: Headless Blender may not support viewport screenshots.
+- **No real-time feedback**: The MCP protocol is request/response. There's no streaming of viewport updates or render progress.
+
+</details>
+
+## Development
+
+```bash
+# Install with dev dependencies
+uv pip install -e ".[dev]"
+
+# Run tests (1190 tests)
+uv run --extra dev pytest
+
+# Run tests with coverage
+uv run --extra dev pytest --cov=blenderwright
+
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+```
+
+<details>
+<summary><strong>Project structure</strong></summary>
+
+```
+blenderwright/
+├── src/blenderwright/          # MCP server
+│   ├── server.py           # FastMCP entry point
+│   ├── connection.py       # TCP client to Blender (with busy-retry)
+│   ├── validators.py       # Input validation
+│   ├── tools/              # 27 tool modules (186 tools)
+│   ├── resources/          # MCP resources (scene, objects, materials)
+│   └── prompts/            # 12 expert prompt templates
+├── addon/                  # Blender addon (zero external deps)
+│   ├── blender_manifest.toml  # Blender 4.2+ Extension manifest
+│   ├── __init__.py         # bl_info (legacy fallback) + register/unregister
+│   ├── server.py           # TCP socket server (SO_KEEPALIVE)
+│   ├── dispatcher.py       # Command routing + allowlist
+│   ├── thread_safety.py    # Main-thread execution queue
+│   ├── render_guard.py     # Render state tracking + crash recovery
+│   ├── ui_panel.py         # N-panel UI (start/stop + port config)
+│   └── handlers/           # 23 handler modules
+└── tests/                  # 1186 unit tests
+```
+
+</details>
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Copyright © 2026 jabberwock.