# design-os-3d-blender

> AI agent operating system for Blender 5.2 LTS: agent skills, verified bpy knowledge base, AGENT_OK/AGENT_FAIL execution contract, and production gate for 3D-printable parts.

An AI agent system that builds mechanical and industrial parts natively inside Blender via bpy scripts, accompanied by evidence-graded reviews in interactive Three.js 3D viewers.

## Model Context Protocol (MCP) Server

`design-os-3d-blender` exposes a certified First-Party Model Context Protocol server for AI coding agents (Claude Code, Codex, Antigravity, Cursor, Cline).

### Quickstart Command
```bash
uvx design-os-3d-blender
```

### Client Configuration (JSON)
```json
{
  "mcpServers": {
    "design-os-3d-blender": {
      "command": "uvx",
      "args": ["design-os-3d-blender"],
      "env": {
        "BLENDER_BIN": "/Applications/Blender.app/Contents/MacOS/Blender"
      }
    }
  }
}
```

### MCP Tools for LLMs
- `blender_runtime_status`: Check host OS, python version, and Blender binary availability. Call this first to verify execution capabilities.
- `query_blender_knowledge`: Search verified bpy 5.2 knowledge base (00-foundations, 10-modeling, 20-shading, 60-pipeline). Use this before authoring bpy scripts to prevent hallucinated APIs.
- `validate_part_spec`: Validate a mechanical part specification (`spec.json`) against schema requirements (`units: "mm"`, `target_dims_mm`, `tol_mm`, `min_wall_mm`).
- `execute_blender_pass`: Run headless pass script in Blender and evaluate the `AGENT_OK` sentinel.

### MCP Prompts
- `design_parametric_part`: Guidance template for designing parametric mechanical parts in Blender 5.2.
- `review_geometry_gate`: Protocol for auditing 3D print gate reports.

### MCP Resources
- `blender://knowledge/index`: Full index of bpy 5.2 knowledge packs.
- `blender://specs/bracket-example`: Reference M3 bracket specification fixture.

---

## AI Agent Operational Protocol & Execution Contract

1. **Knowledge-First**: Query `query_blender_knowledge` before generating any complex Blender script to ensure accurate Blender 5.2 data API syntax.
2. **Data API First**: Avoid `bpy.ops` whenever possible; prefer `bpy.data` and `bmesh`.
3. **Unit System**: Specifications are declared in millimeters (`mm`), but Blender internal units are meters (`1 BU = 1 m`). Convert explicitly: `1 mm = 0.001 BU`.
4. **Sentinel Contract**: Every headless pass must conclude with:
   `print('AGENT_OK')` on verified success, or `print('AGENT_FAIL: <reason>')` on failure.
   Never evaluate success by process returncode alone.

---

## Documentation Links

- [Project Landing](https://jangtrinh.github.io/design-os-3d-blender/): Overview of worked builds, verification contracts, and CLI commands.
- [DC-01 Desktop Companion Review](https://jangtrinh.github.io/design-os-3d-blender/reviews/dc-01/r03/): Interactive Three.js review with 3D model, carousel, and bill of materials.
- [CK-001 Reference Keyboard Review](https://jangtrinh.github.io/design-os-3d-blender/reviews/ck-001/r02/): Mechanical keyboard delivery package with CAD proof.
- [GitHub Repository](https://github.com/jangtrinh/design-os-3d-blender): Python automation scripts, test suites, and Blender runner.

## Nodestack project story

- [Nodestack Review r03](https://jangtrinh.github.io/design-os-3d-blender/reviews/nodestack/r03/): Modular desk-storage reconstruction and engineering study, referencing SMACKMAX_'s NODESTACK // SERVICE PACK. Features an authorized 102-second procedural assembly-guide video (1080p60, 7 chapters), verified 7-view native still gallery, and base-seating engineering cross-section analysis. OpenAI Dots coordinated Antigravity planning/building and separate evidence-based reviews with human direction and feedback. The v16b digital package covers three configurations (32/45/68 parts); physical qualification remains unverified. Raw geometry and unreviewed videos held pending reference-design rights verification. ([Revision r02 stills](https://jangtrinh.github.io/design-os-3d-blender/reviews/nodestack/r02/), [Archive r01](https://jangtrinh.github.io/design-os-3d-blender/reviews/nodestack/r01/)). Tool attribution does not imply endorsement.

## DESIGN:OS Ecosystem

- [design-os](https://jangtrinh.github.io/design-os/): DESIGN:OS CLI — Multi-runtime design CLI for Claude Code, Codex & Antigravity (cli)
- [design-os-knowledge-builder](https://jangtrinh.github.io/design-os-knowledge-builder/): Knowledge Builder — Multimodal knowledge compiler with UKMC.v1 contract & epistemic gate (compiler)
- [design-os-figma-plugin](https://jangtrinh.github.io/design-os-figma-plugin/): Figma Plugin & CLI — Live canvas bridge for AI coding agents on Figma Free (plugin)
- [design-os-svg-animation](https://jangtrinh.github.io/design-os-svg-animation/): SVG Animation Engine — Deterministic vector animation & 1080p 60fps video pipeline (engine)
- [design-os-3d-blender](https://jangtrinh.github.io/design-os-3d-blender/): 3D Blender Agent — Mechanical parts generation with embedded Three.js CAD viewer (3d / cad)
- [design-os-drone-showcase](https://jangtrinh.github.io/design-os-drone-showcase/): OPAH ONE — 249g indoor drone showcase with scroll-scrub kinematics (hardware)
- [design-os-github-page](https://jangtrinh.github.io/design-os-github-page/): GitHub Pages Engine — 9-tier zero-dependency scaffolder with SEO, AEO & GEO (pages)
- [design-os-apple](https://jangtrinh.github.io/design-os-apple/): Apple Design OS — Native SwiftUI 6.2 component system for iOS, iPadOS & macOS (swiftui)
- [design-os-pedagogy](https://jangtrinh.github.io/design-os-pedagogy/): Agent Teacher — Evidence-graded pedagogy library and curriculum tree runtime (pedagogy)
- [design-os-origami](https://jangtrinh.github.io/design-os-origami/): Origami CAD — Parametric packaging dielines, spot-color PDFs & 3D fold previews (packaging)
- [design-os-voice-ux](https://jangtrinh.github.io/design-os-voice-ux/): Voice UX & AI Agent Architecture — Full-duplex barge-in FSMs & sub-500ms voice specs (voice-ai)
- [design-os-code2flow](https://jangtrinh.github.io/design-os-code2flow/): Code2Flow — Local-first codebase-to-user-flow audit CLI across 7 UI frameworks (ast / audit)
- [design-os-generative-ui](https://jangtrinh.github.io/design-os-generative-ui/): Generative UI — Streaming interactive visual runtime with morphdom & WebGL (runtime)

## Videos

- [How to use design os 3d blender repo - ep 1](https://www.youtube.com/watch?v=J2Malrlb_PM): Episode 1: building a keyboard (CK-001) end to end with design-os-3d-blender: photo, spec, gates, STL and GLB export. Vietnamese.
- [How to use design os 3d blender repo - ep 2](https://www.youtube.com/watch?v=LKL7ZHMz5KI): Episode 2: the DC-01 desk robot with 29 mechanical revisions, four gated runs and a printable kit. Vietnamese.
- [Fanmade 3D model for Nowa planet - by design os 3d blender](https://www.youtube.com/watch?v=XSKZYudfMt8): 27-second fan-made 3D model of the Nowa desktop product, built with design-os-3d-blender.
- [design:os by Jang on YouTube](https://www.youtube.com/@designosbyjang): channel.