# Ceratops-Blender-MCP and Ceratops-Blender-Kit

Ceratops-Blender-MCP is a local, goal-oriented MCP server for versioned Blender
character and shot production. Ceratops-Blender-Kit is its companion workflow
skill. The server exposes fixed production transitions, not arbitrary Python or
an alternative low-level Blender console.

This v1 is a working local control plane and Blender CLI integration. It creates
simple production-ready starting structures, versioned `.blend` files, review
renders, frame sequences, and ZIP packages. Artistic refinement remains a human
and agent workflow; the low-level Blender MCP can still be used separately when
an approved version needs bespoke editing.

## Skills

| Skill | Purpose |
| --- | --- |
| `ceratops-blender-kit` | Orchestrate versioned Blender character and shot production, including exact-source selection, review gates, approvals, and packaging. |

## What works

- Read-only project and asset inspection, exact version comparison, and
  character content checks.
- Immutable character stages: reference import, blockout, mesh, retopology,
  look development, groom, rig, face rig, and review renders.
- Immutable shot stages: layout, assembly from exact character versions,
  camera, lighting, blocking animation, lip sync, secondary motion, preview,
  and final frame sequences.
- Explicit appearance, groom, rig, facial-expression, and animation review
  gates. Promotion records approval without changing version bytes.
- Versioned asset and episode ZIP packages.
- Current-worker status with fresh monitoring identifiers.
- Repeated desired-state actions reuse matching completed output.
- Archival without permanent production-version deletion.

Write tools take ordinary production inputs. A fresh invocation checks the
actual project, selected versions and lifecycle state; it never reads a failed
job to decide what to execute. A still-live matching operation shares its worker.
There are no caller request IDs, job continuation or job mutation operations.

## Run locally

Requirements:

- Windows x64 CPython 3.14
- [`uv`](https://docs.astral.sh/uv/)
- Blender available as `blender` on `PATH`, or an absolute binary path in
  `CERATOPS_BLENDER_EXECUTABLE`

```powershell
$server = "mcp-servers/ceratops_blender_mcp"
uv sync --project $server --extra dev --locked
$env:CERATOPS_BLENDER_EXECUTABLE = 'C:\Program Files\Blender Foundation\Blender 4.5\blender.exe'
uv run --project $server --locked ceratops-blender-mcp
```

The source entry point uses MCP stdio. After managed deployment, a host should
launch `%USERPROFILE%\.codex\mcp\ceratops-blender-mcp\bin\ceratops-blender-mcp.cmd
--mcp` and pass the Blender executable through its environment when Blender is
not on `PATH`.

The server uses the maintained MCP Python SDK v2 (`mcp>=2,<3`) and its
`MCPServer` API. The package name and Python module use lowercase ecosystem
forms; the server identity presented to users is Ceratops-Blender-MCP.

## Monitor Blender RAM on Windows

Run the standalone monitor in a PowerShell console:

```powershell
powershell.exe -NoProfile -File .\scripts\limit-blender-ram.ps1
```

It runs until Ctrl+C, monitors existing and newly started `blender.exe` processes,
and adjusts their combined pageable working-set allowance to target **1.5 GiB of
available system RAM**. Windows can page Blender's larger allocations to disk;
the monitor does not impose a total allocation limit. The optional parameters
`-AvailableGiB`, `-IntervalSeconds`, and `-SettleSeconds` default to 1.5, 1, and
5.
Caps respect existing hard minimum/maximum limits, use a 64 MiB per-process floor,
and allow time for paging between adjustments. Other applications, shared pages,
and nonpageable memory can prevent the target from being reached; it is not a
guaranteed reserve. Expect slower rendering under memory pressure.

Keep the console open. Normal stopping restores the prior sizes and enforcement
flags when they still belong to this monitor. Force-killing the monitor bypasses
cleanup and leaves its last limits on surviving Blender processes; a subsequent
monitor run can adjust them again, but cannot recover originals lost with the
killed process. Limits also disappear when Blender exits. Access or job-object
restrictions are reported per process, without changing privileges or job limits.
Only one monitor may run on the computer. The script creates no runtime
files, logs, startup entries, or scheduled tasks and runs no model calls.

## Tool contract

Read tools never initialize a project or alter production state:

- `inspect_project`, `list_assets`, `inspect_asset`
- `compare_asset_versions`, `validate_character`
- `get_job_status`

Version and lifecycle writes:

- `import_character_reference`, `promote_version`, `archive_version`
- `create_character`, `create_character_mesh`, `retopologize_character`
- `create_uv_and_materials`, `groom_character`, `rig_character`
- `build_face_rig`, `render_character_review`
- `create_shot`, `assemble_shot`, `setup_camera`, `light_shot`
- `animate_shot`, `sync_lips`, `add_secondary_motion`
- `render_shot_preview`, `render_shot_final`
- `package_asset`, `package_episode`

A Blender-producing operation reuses matching completed output or creates a
new `vNNNN` directory. Callers must
pass exact source versions; the server does not silently choose “latest.”
Downstream gated tools accept only the exact version approved at the required
gate. `render_shot_final`, for example, requires the selected preview version to
have passed the animation gate.

## Production data ownership and retention

The source repository owns code, tests, documentation, and the skill. Each
caller-selected Blender project owns its runtime data:

```text
<project>/.ceratops-blender/
  project.json
  state.lock
  characters/<id>/versions/vNNNN/
  characters/<id>/events/
  shots/<id>/versions/vNNNN/
  shots/<id>/events/
  deliveries/<id>/versions/vNNNN/
  jobs/job_<worker-uuid>.json
```

A version request is written first, output bytes are written into that reserved
directory, and `record.json` is written last. Completed version records and
artifacts are immutable. A failed partial may retain a bounded error until the
next production call discards abandoned partials under the project production
lock. Partial numbers may be reused; completed version identities never are.
Promotion and archive events describe current business state; repeating the
current choice is a no-op, while selecting a prior version after another
promotion records the new choice.

Projects permit 25 active versions per entity by default. Creation stops at the
limit until the caller archives an older version; archived production data is
retained because v1 offers no permanent-delete tool. Job history is operational
data: active jobs are always retained and the 100 most recently updated terminal
job records are kept. Atomic control writes remove their temporary sibling on
success or failure. Blender subprocess output is held only in bounded memory and
is not persisted as an unbounded log.

## Development and repository lifecycle

The repository's single lifecycle contract is `sdlc/sdlc.yml`. It declares the
real validation and test entry points created by current Ceratops compatibility
tooling. Run them through the repository lifecycle operation runner, or use the
narrow developer commands while editing:

```powershell
uv run --project mcp-servers/ceratops_blender_mcp --extra dev --locked ruff check .
uv run --project mcp-servers/ceratops_blender_mcp --extra dev --locked mypy
uv run --project mcp-servers/ceratops_blender_mcp --extra dev --locked pytest
```

Tests use a recording Blender runtime so versioning, gating, packaging, and MCP
contracts are exercised without pretending that a local Blender installation
was rendered in CI.
`mcp-servers/ceratops_blender_mcp/tests/test_blender_integration.py` adds a real
Blender smoke case and runs only when `CERATOPS_BLENDER_EXECUTABLE` is explicitly
set.

## Current boundaries

- GitHub source publication and Ceratops-managed local deployment are supported;
  no PyPI release or hosted Blender service is provided.
- The unfinished exact-artifact lifecycle described in the Ceratops refactor
  plan is not implemented here. There are no fabricated build receipts,
  artifact declarations, delivery actions, or deployment claims.
- V1 does not permanently delete production versions, invoke arbitrary Blender
  Python, synthesize high-end character art, run a render farm, or coordinate
  distributed Blender workers.
- Internal shutdown is cooperative around the owned local Blender subprocess. A
  machine-level crash can leave Blender work that the operating system must end;
  the future Ceratops worktree process-group design is not claimed here.

See [`docs/DESIGN.md`](docs/DESIGN.md) for component boundaries and failure
behavior, and [`skills/ceratops-blender-kit/SKILL.md`](skills/ceratops-blender-kit/SKILL.md)
for the user-facing production workflow.