security-game/docs/blender-mcp.md

# Optional Blender MCP

Status: **optional interactive tooling, not a build dependency.** Blender MCP is
useful for exploring a local part scene, moving the viewport and iterating on a
head/hand mesh without a manual UI walkthrough. The authoritative asset
pipeline remains the headless CLI plus `audit`/`fit`/`inspect`; CI, tests and
release builds must continue to work with no Blender process and no MCP server.

This project does not vend the third-party addon or pin a runtime MCP
dependency. Install it outside the repository and keep generated scenes under
`tmp/`.

## What it adds

With Blender MCP connected, an agent can:

- query the current scene and object data;
- run small `bpy` snippets through the MCP bridge;
- capture a viewport screenshot for visual checks;
- inspect or modify a local part scene before exporting a GLB.

It does **not** replace:

- `python3 tools/blender_assets.py audit/fit/inspect`;
- `python3 tools/npc_proportions.py`;
- the Godot capture and smoke gates;
- the project's licence/provenance review.

## Prerequisites

- Blender 5.2 LTS, installed as the `org.blender.Blender` flatpak (the project
  standard).
- An MCP-capable client.
- The upstream [BlenderMCP addon](https://github.com/ahujasid/blender-mcp)
  (`addon.py`) and its MCP server.
- `uv`/`uvx` if you use the server's `uvx blender-mcp` launcher; a local install
  of the server package is equally valid.

Check the upstream README for the current package/addon version and any command
changes before installing. Do not copy the addon into this repository.

## Setup

### 1. Install the Blender addon

1. Download or clone the upstream BlenderMCP project.
2. In Blender: **Edit → Preferences → Add-ons → Install from Disk**, select
   `addon.py` from that checkout.
3. Enable **Interface: Blender MCP**.
4. Open the 3D View sidebar (N panel), find the **BlenderMCP** tab, and click
   **Connect to MCP server**. The default server listens on
   `localhost:9876`.

The addon must be running inside the Blender process that has the scene open.
Starting a second Blender instance does not connect the first one.

### 2. Configure the MCP client

For Pi, add the server at user scope so it is not committed into the project:

```bash
pi mcp add blender -- uvx blender-mcp
pi mcp list
```

Then start/reload Pi and use `/mcp` to inspect the connection. Other clients
use their normal MCP server configuration. A generic JSON example:

```json
{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}
```

For a client with a different config schema, use the equivalent server command
and keep the server name `blender`. Restart/reload the client after adding it,
then request the tool list and run a harmless `get_scene_info` before editing.

### 3. Connect through the flatpak

Start Blender through the project's normal flatpak command, open the local part
scene, and connect from the sidebar. If the client cannot reach the addon:

- confirm the addon panel says connected;
- confirm the client is launching the MCP server, not just a shell;
- check port `9876` is not occupied;
- if the flatpak sandbox is blocking localhost networking, grant network
  permission only for this interactive use, for example:
  `flatpak override --user --share=network org.blender.Blender`
  (review the permission change afterwards; do not add it to CI or build
  scripts).
- restart both the MCP client and Blender after changing the addon or config.

## Recommended part-workflow

1. Create a local scene, for example
   `tmp/npc-parts/npc_casual/head.blend`, or open a copy of an exported part GLB.
   Never save over the tracked `assets/models/npc/npc_base.blend`.
2. Ask the MCP client for `get_scene_info`, then inspect the object/bone/mesh
   names it reports.
3. Use `execute_blender_code` for small, reversible edits. Prefer adding a new
   object or modifier over deleting existing geometry; keep a backup copy.
4. Use `get_viewport_screenshot` after camera/material changes to check the
   head/face/hand before exporting.
5. Export a **local** GLB under `tmp/npc-parts/`, not directly into
   `assets/models/`.
6. Run the normal gates on the exported file:

   ```bash
   flatpak run org.blender.Blender --background \
     --python "$PWD/tools/blender_assets.py" -- \
     inspect --file "$PWD/tmp/npc-parts/head.glb" --category npc --json
   python3 tools/blender_assets.py audit
   python3 tools/blender_assets.py fit
   python3 tools/npc_proportions.py report
   ```

7. Only after the part is reviewed and the contract passes should it be
   assembled into a character and rebuilt through the headless pipeline.

## Safety and project rules

- MCP is **not** part of `project.godot`, the build, CI, tests, release packages
  or runtime.
- Do not commit `.blend` part scenes, MCP configuration, API keys or generated
  previews. The working set stays in `tmp/`.
- Do not use MCP to bypass the contract, budgets, AO/UV rules or licence gate.
- The 13 core bones must remain at their rest positions; extra optional bones
  are allowed only if `NpcAvatar` and the audit/tests still pass.
- Prefer scripted headless changes for reproducible work; MCP is for the
  interactive exploration and review that is awkward in a one-shot script.
- If MCP is unavailable, use the headless CLI and document the manual step; never
  make the project depend on MCP being present.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| Client cannot find `blender` | MCP client config path/schema; restart client; confirm server command exists |
| `Connection refused` | Addon **Connect to MCP server** pressed; Blender still running; port 9876 |
| Tools return stale scene data | Refresh scene/object query after edits; restart the connection if needed |
| Flatpak cannot reach localhost | Check flatpak network permission; grant only for interactive use |
| Changes look wrong in export | Re-import the GLB with `inspect`; check transforms, scale, UVs and materials |
| Contract audit fails | Fix the mesh/bones first; do not edit the audit expectations around a broken asset |