mcp-printable 0.1.0__tar.gz

mcp_printable-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/
+
+# Generated texture pipeline outputs
+texture_maps/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Blender checkpoints
+*.blend1
+printable_blender_checkpoint.blend
+printable_blender_scene.blend
+
+# Eval runtime
+evals/results/latest.json
+evals/results/baseline.json
+evals/results/logs/
+
+# Local MCP client config — user-specific, not part of the project
+.mcp.json
+
+# Experiment scratch — local work that shouldn't ship.
+# Drop one-off STLs / blends / scad / textures here.
+experiments/
+
+# Stray model artifacts at repo root (agents sometimes write here).
+# Subdirectories are unaffected — only catches accidental root pollution.
+/*.stl
+/*.blend
+/*.scad
+
+# Claude Code local state
+.claude/settings.local.json
+.claude/worktrees/

mcp_printable-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Goldsmith
+
+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.

mcp_printable-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: mcp-printable
+Version: 0.1.0
+Summary: MCP server for AI-driven 3D modeling and print validation (FDM-focused). Agent-agnostic; works with any MCP client (Claude Code, Goose, Cursor, Codex, ...).
+Project-URL: Homepage, https://github.com/AaronGoldsmith/mcp-printable
+Project-URL: Repository, https://github.com/AaronGoldsmith/mcp-printable
+Project-URL: Issues, https://github.com/AaronGoldsmith/mcp-printable/issues
+Author-email: Aaron Goldsmith <aargoldsmith@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d-printing,ai-agents,blender,claude,fdm,mcp,model-context-protocol,openscad
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: trimesh>=4.0.0
+Description-Content-Type: text/markdown
+
+# Printable
+
+**MCP server for AI-driven 3D modeling, optimized for FDM-printable geometry.**
+
+Connect any MCP-capable agent (Claude Code, Goose, Cursor, Codex, Cline, etc.) to a 3D modeling backend and get tools tuned for the design loop that actually produces parts you can print.
+
+## Why this exists
+
+LLMs are good at writing geometry code but bad at the things that make a part actually printable: clearances on moving joints, overhangs, bridging, units, watertight meshes. Printable encodes those constraints into both the tool surface (typed booleans, printability checks, clearance sweeps, cross-sections) and the prose rules the agent reads (cardinal print-path rule, FDM clearance values, mechanism patterns).
+
+The result: you can ask any MCP-aware agent "build me a hinge with 5mm barrel and 20×15mm flanges" and get a part that comes off the bed working.
+
+## Backends
+
+- **Blender** (`blender_*` tools, 25 of them). Full design loop with rendering, cross-sections, printability validation. Requires Blender 3.6+ installed and the included addon enabled.
+- **OpenSCAD** (`scad_*` tools, 5 of them, see [`docs/openscad/README.md`](docs/openscad/README.md)). Code-first parametric backend. No app, no addon — shells out to the `openscad` CLI and uses [`trimesh`](https://github.com/mikedh/trimesh) for mesh validation. Requires OpenSCAD installed.
+
+Cross-backend handoff happens via STL — both backends import and export it.
+
+## Architecture
+
+```
+Agent  <--stdio/MCP-->  server.py  <--TCP :9876-->  Blender addon
+                              \
+                               +----shell-out------>  openscad CLI + trimesh
+```
+
+- `server.py` — FastMCP server. Exposes the tool surface and embeds the always-on rules in the MCP `instructions` field, with pointers into `docs/` for deeper guidance.
+- `addon/` — Blender addon. TCP server on `127.0.0.1:9876`. Commands run on Blender's main thread via `bpy.app.timers`.
+- `docs/` — agent-agnostic prose guidance: print-in-place rules, design loop, image displacement. Also exposed as **MCP resources** under `printable://…` URIs (see [Documents](#documents) below) so any resource-aware MCP client can pull them via the protocol — no filesystem access required.
+- `.claude/skills/` — thin Claude shims (description-triggered loading) that point into `docs/`. Other agents use resources or filesystem.
+- `evals/` — policy-based regression tests that verify agents actually follow the rules. See [`evals/README.md`](evals/README.md).
+
+## Status
+
+v0.1.0 — alpha. Blender backend is feature-complete and dogfooded against real prints; OpenSCAD backend covers the parametric workflow but has fewer validation tools. API is stable enough to use but may shift before 1.0.
+
+## Setup
+
+### Install from PyPI
+
+```bash
+pip install mcp-printable       # or: uv pip install mcp-printable
+printable-install-addon         # copies the bundled addon into Blender's addon dir
+```
+
+Then in Blender: Preferences → Add-ons → enable **"Printable Blender Bridge"**.
+
+### Install from source
+
+```bash
+git clone https://github.com/AaronGoldsmith/mcp-printable
+cd mcp-printable
+uv sync                         # or: pip install .
+python install.py               # equivalent to printable-install-addon
+```
+
+> [!IMPORTANT]
+> Run the install step from a terminal — **NOT** Blender's "Install from Disk" dialog. See [`SETUP.md`](SETUP.md) for why and other gotchas.
+
+### Wire into your agent
+
+For Claude Code (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "printable-blender": {
+    "command": "printable"
+  }
+}
+```
+
+(Key is namespaced so the planned `printable-openscad` backend can register alongside without collision.)
+
+For other agents (Goose, Cursor, etc.) — wire it up using your agent's standard MCP server configuration. The command is `printable`; no args needed.
+
+### Agent skills (optional)
+
+This repo bundles four [Claude Code skills](https://code.claude.com/docs/en/skills) under [`.claude/skills/`](.claude/skills/) — short shims that point at the same `docs/` content the MCP exposes as resources. Claude Code auto-discovers them when you launch it in the repo:
+
+```bash
+git clone https://github.com/AaronGoldsmith/mcp-printable
+cd mcp-printable && claude
+```
+
+The 4 skills:
+- `print-in-place` — design rules for moving-parts mechanisms (hinges, ball-sockets, snap fits)
+- `blender-design-loop` — plan→build→verify→validate→export workflow
+- `image-displacement` — turn a 2D image into 3D printable relief
+- `blender-app` — launch / restart / multi-instance Blender setup
+
+For Claude Code, copy a skill into `~/.claude/skills/` to make it available across all projects. **For other agents** (Codex, Cursor, Goose, ...) — see [AGENTS.md](AGENTS.md), which links each skill into the equivalent location for your agent and explains the MCP-resource fallback for agents that don't load project skills.
+
+## Tool families
+
+### Blender (25 tools)
+
+**Scene** — `blender_get_scene_info`, `blender_get_object_info`, `blender_clear_scene`, `blender_rename_object`
+
+**Code** — `blender_execute_code` (arbitrary bpy/bmesh; auto-checkpoints), `blender_boolean` (typed UNION/DIFFERENCE/INTERSECT — *prefer this over execute_code*)
+
+**Visual feedback** — `blender_get_screenshot`, `blender_render_tiled`, `blender_render_turntable`, `blender_cross_section`, `blender_cross_section_gallery`, `blender_render_printability_heatmap`, `blender_render_with_dimensions`, `blender_render_before_after`
+
+**Print validation** — `blender_check_overhangs`, `blender_check_thin_walls`, `blender_check_clearance`, `blender_check_clearance_sweep`, `blender_check_intersection`, `blender_check_retention`, `blender_mesh_health`, `blender_full_printability_check`
+
+**Export** — `blender_export_stl`, `blender_import_stl`, `blender_save_blend`
+
+### OpenSCAD (5 tools)
+
+`scad_compile`, `scad_render_views`, `scad_cross_section`, `scad_validate_printability`, `scad_import_stl`. Shells out to the `openscad` CLI; uses [`trimesh`](https://github.com/mikedh/trimesh) for mesh validation. Full docs: [`docs/openscad/README.md`](docs/openscad/README.md).
+
+## The Design Loop
+
+Always-on rules embedded in the MCP server's `instructions` field — every agent that connects sees them automatically. Summary:
+
+1. **Plan.** Compute coordinates and dimensions in one `execute_code` call that PRINTS them. Verify the math BEFORE creating geometry.
+2. **Build.** 1–3 operations per `execute_code`, then `blender_mesh_health`.
+3. **Verify.** Renders for shape, cross-sections for internal truth.
+4. **Validate.** `blender_check_clearance_sweep` for any joint. `blender_full_printability_check` before export.
+5. **Export.** `blender_export_stl` (no args = bundle all parts).
+
+Full doc: [`docs/blender/design-loop.md`](docs/blender/design-loop.md).
+
+For mechanism design (hinges, ball-sockets, snap fits, articulated chains): [`docs/design/print-in-place.md`](docs/design/print-in-place.md). This is backend-agnostic — same rules apply if you're using OpenSCAD.
+
+## Documents
+
+Every doc below is served two ways:
+
+1. **As an MCP resource** under `printable://…` — the **preferred** path. Resource-aware clients fetch via `resources/read`, get the same content the maintainer ships, and don't need filesystem access to the project. Resources travel with the MCP server itself, so a `pip install mcp-printable` user has the docs even without cloning the repo.
+2. **As a file in `docs/`** — fallback for filesystem-based clients, and for humans browsing the repo.
+
+If you're writing an MCP client, prefer the URI. The filesystem path is documented mainly so a human can click through from this README.
+
+| URI | File | Purpose |
+|---|---|---|
+| `printable://design/print-in-place` | [docs/design/print-in-place.md](docs/design/print-in-place.md) | FDM mechanism design: cardinal print-path rule, clearances, patterns, validation checklist (**backend-agnostic**) |
+| `printable://blender/design-loop` | [docs/blender/design-loop.md](docs/blender/design-loop.md) | Plan→build→verify→validate→export workflow, boolean rules, failure modes |
+| `printable://blender/image-displacement` | [docs/blender/image-displacement.md](docs/blender/image-displacement.md) | 2D image → printable 3D relief |
+| `printable://blender/blender-app` | [docs/blender/blender-app.md](docs/blender/blender-app.md) | Launch / restart / multi-instance setup |
+| `printable://openscad/backend` | [docs/openscad/README.md](docs/openscad/README.md) | OpenSCAD backend setup, tool reference, validator details, cross-backend handoff |
+
+```
+docs/
+├── design/                          # backend-agnostic design rules
+│   └── print-in-place.md
+├── blender/                         # Blender-specific
+│   ├── design-loop.md
+│   ├── image-displacement.md
+│   └── blender-app.md
+└── openscad/                        # OpenSCAD-specific
+    └── README.md
+```
+
+## Testing
+
+```bash
+python -m pytest tests/ -v          # unit tests, no Blender required
+python evals/runner.py              # policy-based regression evals (see evals/README.md)
+```
+
+Unit tests cover TCP protocol framing, image compositing (PIL), MCP tool registration. The eval suite checks that agents using the MCP actually follow the always-on rules (e.g. clear scene first, prefer `blender_boolean`, no monolithic `execute_code` blocks) — procedural checks from the tool trace, plus LLM-judged outcome policies for things like "moving parts have a continuous print path to the bed."
+
+## Roadmap
+
+Things on the list, not yet shipped:
+
+- **Validated parameter recipes** — turnkey parameter sets for common print-in-place mechanisms (wheel-on-axle, flip-tile, ball-and-socket, snap fit) so an agent can ask for "a toy car wheel" and get a known-good geometry without re-solving the clearance + retention math each time. Earlier drafts existed but weren't dialed in enough to ship as authoritative; new ones will land once they're validated against real prints.
+- **Blender app-lifecycle tools** (`blender_launch` / `blender_status` / `blender_kill`) — let the agent spin Blender up itself instead of needing the user to start it first.
+- **Second OpenSCAD parity pass** — match Blender's clearance-sweep / retention / thin-wall checks on the SCAD side.
+
+## Contributing
+
+The interesting design surface is in `docs/`. New always-on rules belong in [`docs/design/`](docs/design/) (backend-agnostic) or [`docs/blender/`](docs/blender/) / [`docs/openscad/`](docs/openscad/) (backend-specific). If a rule should be enforced, also add a policy file under [`evals/policies/`](evals/policies/) and a scenario under [`evals/scenarios/`](evals/scenarios/) so the eval runner picks it up.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

mcp_printable-0.1.0/README.md

@@ -0,0 +1,178 @@
+# Printable
+
+**MCP server for AI-driven 3D modeling, optimized for FDM-printable geometry.**
+
+Connect any MCP-capable agent (Claude Code, Goose, Cursor, Codex, Cline, etc.) to a 3D modeling backend and get tools tuned for the design loop that actually produces parts you can print.
+
+## Why this exists
+
+LLMs are good at writing geometry code but bad at the things that make a part actually printable: clearances on moving joints, overhangs, bridging, units, watertight meshes. Printable encodes those constraints into both the tool surface (typed booleans, printability checks, clearance sweeps, cross-sections) and the prose rules the agent reads (cardinal print-path rule, FDM clearance values, mechanism patterns).
+
+The result: you can ask any MCP-aware agent "build me a hinge with 5mm barrel and 20×15mm flanges" and get a part that comes off the bed working.
+
+## Backends
+
+- **Blender** (`blender_*` tools, 25 of them). Full design loop with rendering, cross-sections, printability validation. Requires Blender 3.6+ installed and the included addon enabled.
+- **OpenSCAD** (`scad_*` tools, 5 of them, see [`docs/openscad/README.md`](docs/openscad/README.md)). Code-first parametric backend. No app, no addon — shells out to the `openscad` CLI and uses [`trimesh`](https://github.com/mikedh/trimesh) for mesh validation. Requires OpenSCAD installed.
+
+Cross-backend handoff happens via STL — both backends import and export it.
+
+## Architecture
+
+```
+Agent  <--stdio/MCP-->  server.py  <--TCP :9876-->  Blender addon
+                              \
+                               +----shell-out------>  openscad CLI + trimesh
+```
+
+- `server.py` — FastMCP server. Exposes the tool surface and embeds the always-on rules in the MCP `instructions` field, with pointers into `docs/` for deeper guidance.
+- `addon/` — Blender addon. TCP server on `127.0.0.1:9876`. Commands run on Blender's main thread via `bpy.app.timers`.
+- `docs/` — agent-agnostic prose guidance: print-in-place rules, design loop, image displacement. Also exposed as **MCP resources** under `printable://…` URIs (see [Documents](#documents) below) so any resource-aware MCP client can pull them via the protocol — no filesystem access required.
+- `.claude/skills/` — thin Claude shims (description-triggered loading) that point into `docs/`. Other agents use resources or filesystem.
+- `evals/` — policy-based regression tests that verify agents actually follow the rules. See [`evals/README.md`](evals/README.md).
+
+## Status
+
+v0.1.0 — alpha. Blender backend is feature-complete and dogfooded against real prints; OpenSCAD backend covers the parametric workflow but has fewer validation tools. API is stable enough to use but may shift before 1.0.
+
+## Setup
+
+### Install from PyPI
+
+```bash
+pip install mcp-printable       # or: uv pip install mcp-printable
+printable-install-addon         # copies the bundled addon into Blender's addon dir
+```
+
+Then in Blender: Preferences → Add-ons → enable **"Printable Blender Bridge"**.
+
+### Install from source
+
+```bash
+git clone https://github.com/AaronGoldsmith/mcp-printable
+cd mcp-printable
+uv sync                         # or: pip install .
+python install.py               # equivalent to printable-install-addon
+```
+
+> [!IMPORTANT]
+> Run the install step from a terminal — **NOT** Blender's "Install from Disk" dialog. See [`SETUP.md`](SETUP.md) for why and other gotchas.
+
+### Wire into your agent
+
+For Claude Code (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "printable-blender": {
+    "command": "printable"
+  }
+}
+```
+
+(Key is namespaced so the planned `printable-openscad` backend can register alongside without collision.)
+
+For other agents (Goose, Cursor, etc.) — wire it up using your agent's standard MCP server configuration. The command is `printable`; no args needed.
+
+### Agent skills (optional)
+
+This repo bundles four [Claude Code skills](https://code.claude.com/docs/en/skills) under [`.claude/skills/`](.claude/skills/) — short shims that point at the same `docs/` content the MCP exposes as resources. Claude Code auto-discovers them when you launch it in the repo:
+
+```bash
+git clone https://github.com/AaronGoldsmith/mcp-printable
+cd mcp-printable && claude
+```
+
+The 4 skills:
+- `print-in-place` — design rules for moving-parts mechanisms (hinges, ball-sockets, snap fits)
+- `blender-design-loop` — plan→build→verify→validate→export workflow
+- `image-displacement` — turn a 2D image into 3D printable relief
+- `blender-app` — launch / restart / multi-instance Blender setup
+
+For Claude Code, copy a skill into `~/.claude/skills/` to make it available across all projects. **For other agents** (Codex, Cursor, Goose, ...) — see [AGENTS.md](AGENTS.md), which links each skill into the equivalent location for your agent and explains the MCP-resource fallback for agents that don't load project skills.
+
+## Tool families
+
+### Blender (25 tools)
+
+**Scene** — `blender_get_scene_info`, `blender_get_object_info`, `blender_clear_scene`, `blender_rename_object`
+
+**Code** — `blender_execute_code` (arbitrary bpy/bmesh; auto-checkpoints), `blender_boolean` (typed UNION/DIFFERENCE/INTERSECT — *prefer this over execute_code*)
+
+**Visual feedback** — `blender_get_screenshot`, `blender_render_tiled`, `blender_render_turntable`, `blender_cross_section`, `blender_cross_section_gallery`, `blender_render_printability_heatmap`, `blender_render_with_dimensions`, `blender_render_before_after`
+
+**Print validation** — `blender_check_overhangs`, `blender_check_thin_walls`, `blender_check_clearance`, `blender_check_clearance_sweep`, `blender_check_intersection`, `blender_check_retention`, `blender_mesh_health`, `blender_full_printability_check`
+
+**Export** — `blender_export_stl`, `blender_import_stl`, `blender_save_blend`
+
+### OpenSCAD (5 tools)
+
+`scad_compile`, `scad_render_views`, `scad_cross_section`, `scad_validate_printability`, `scad_import_stl`. Shells out to the `openscad` CLI; uses [`trimesh`](https://github.com/mikedh/trimesh) for mesh validation. Full docs: [`docs/openscad/README.md`](docs/openscad/README.md).
+
+## The Design Loop
+
+Always-on rules embedded in the MCP server's `instructions` field — every agent that connects sees them automatically. Summary:
+
+1. **Plan.** Compute coordinates and dimensions in one `execute_code` call that PRINTS them. Verify the math BEFORE creating geometry.
+2. **Build.** 1–3 operations per `execute_code`, then `blender_mesh_health`.
+3. **Verify.** Renders for shape, cross-sections for internal truth.
+4. **Validate.** `blender_check_clearance_sweep` for any joint. `blender_full_printability_check` before export.
+5. **Export.** `blender_export_stl` (no args = bundle all parts).
+
+Full doc: [`docs/blender/design-loop.md`](docs/blender/design-loop.md).
+
+For mechanism design (hinges, ball-sockets, snap fits, articulated chains): [`docs/design/print-in-place.md`](docs/design/print-in-place.md). This is backend-agnostic — same rules apply if you're using OpenSCAD.
+
+## Documents
+
+Every doc below is served two ways:
+
+1. **As an MCP resource** under `printable://…` — the **preferred** path. Resource-aware clients fetch via `resources/read`, get the same content the maintainer ships, and don't need filesystem access to the project. Resources travel with the MCP server itself, so a `pip install mcp-printable` user has the docs even without cloning the repo.
+2. **As a file in `docs/`** — fallback for filesystem-based clients, and for humans browsing the repo.
+
+If you're writing an MCP client, prefer the URI. The filesystem path is documented mainly so a human can click through from this README.
+
+| URI | File | Purpose |
+|---|---|---|
+| `printable://design/print-in-place` | [docs/design/print-in-place.md](docs/design/print-in-place.md) | FDM mechanism design: cardinal print-path rule, clearances, patterns, validation checklist (**backend-agnostic**) |
+| `printable://blender/design-loop` | [docs/blender/design-loop.md](docs/blender/design-loop.md) | Plan→build→verify→validate→export workflow, boolean rules, failure modes |
+| `printable://blender/image-displacement` | [docs/blender/image-displacement.md](docs/blender/image-displacement.md) | 2D image → printable 3D relief |
+| `printable://blender/blender-app` | [docs/blender/blender-app.md](docs/blender/blender-app.md) | Launch / restart / multi-instance setup |
+| `printable://openscad/backend` | [docs/openscad/README.md](docs/openscad/README.md) | OpenSCAD backend setup, tool reference, validator details, cross-backend handoff |
+
+```
+docs/
+├── design/                          # backend-agnostic design rules
+│   └── print-in-place.md
+├── blender/                         # Blender-specific
+│   ├── design-loop.md
+│   ├── image-displacement.md
+│   └── blender-app.md
+└── openscad/                        # OpenSCAD-specific
+    └── README.md
+```
+
+## Testing
+
+```bash
+python -m pytest tests/ -v          # unit tests, no Blender required
+python evals/runner.py              # policy-based regression evals (see evals/README.md)
+```
+
+Unit tests cover TCP protocol framing, image compositing (PIL), MCP tool registration. The eval suite checks that agents using the MCP actually follow the always-on rules (e.g. clear scene first, prefer `blender_boolean`, no monolithic `execute_code` blocks) — procedural checks from the tool trace, plus LLM-judged outcome policies for things like "moving parts have a continuous print path to the bed."
+
+## Roadmap
+
+Things on the list, not yet shipped:
+
+- **Validated parameter recipes** — turnkey parameter sets for common print-in-place mechanisms (wheel-on-axle, flip-tile, ball-and-socket, snap fit) so an agent can ask for "a toy car wheel" and get a known-good geometry without re-solving the clearance + retention math each time. Earlier drafts existed but weren't dialed in enough to ship as authoritative; new ones will land once they're validated against real prints.
+- **Blender app-lifecycle tools** (`blender_launch` / `blender_status` / `blender_kill`) — let the agent spin Blender up itself instead of needing the user to start it first.
+- **Second OpenSCAD parity pass** — match Blender's clearance-sweep / retention / thin-wall checks on the SCAD side.
+
+## Contributing
+
+The interesting design surface is in `docs/`. New always-on rules belong in [`docs/design/`](docs/design/) (backend-agnostic) or [`docs/blender/`](docs/blender/) / [`docs/openscad/`](docs/openscad/) (backend-specific). If a rule should be enforced, also add a policy file under [`evals/policies/`](evals/policies/) and a scenario under [`evals/scenarios/`](evals/scenarios/) so the eval runner picks it up.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

mcp_printable-0.1.0/SETUP.md

@@ -0,0 +1,118 @@
+# Setup
+
+End-to-end install for the Printable MCP server + Blender addon, plus the gotchas that aren't obvious until they bite.
+
+## 1. Install dependencies
+
+```bash
+uv sync                  # or: pip install .
+```
+
+## 2. Install the Blender addon — from a terminal
+
+```bash
+python install.py
+```
+
+This copies `addon/` to `<blender-config>/scripts/addons/printable_blender/`.
+
+> [!WARNING]
+> **Do NOT use Blender's `Edit > Preferences > Add-ons > Install from Disk`** on `install.py`.
+> That dialog treats the file you point at as the addon itself, copies the lone `install.py`
+> into `scripts/addons/`, and then registers nothing because `install.py` has no `bl_info`.
+> You'll see a misleading **`Modules Installed ()`** popup (note the empty parens) and the
+> TCP server will never start.
+>
+> Always run `python install.py` from a shell in the project root.
+
+After install, verify the directory exists:
+
+```
+<blender-config>/scripts/addons/printable_blender/
+  __init__.py
+  handlers.py
+  utils.py
+```
+
+If you instead see `install.py` and/or `addon.py` loose in `scripts/addons/`, the GUI-install
+pitfall above happened. Delete those stray files and re-run `python install.py` from the terminal.
+
+## 3. Enable the addon in Blender
+
+`Edit > Preferences > Add-ons` → search **`Printable`** → tick **"Printable Blender Bridge"**.
+
+You should see this in Blender's system console:
+
+```
+[Printable Bridge] Listening on 127.0.0.1:9876
+```
+
+## 4. Verify the TCP bridge
+
+From any terminal:
+
+```bash
+python - <<'PY'
+import socket, struct, json, uuid
+s = socket.socket(); s.connect(('127.0.0.1', 9876))
+msg = json.dumps({'id': str(uuid.uuid4()), 'command': 'get_scene_info', 'params': {}}).encode()
+s.sendall(struct.pack('>I', len(msg)) + msg)
+n = struct.unpack('>I', s.recv(4))[0]
+print(json.loads(s.recv(n)))
+PY
+```
+
+A successful response means the agent can talk to Blender.
+
+## 5. Wire the MCP server into your agent
+
+See [README.md](README.md#setup) for the per-agent config snippet.
+
+---
+
+## Reinstalling / updating the addon
+
+Python modules don't hot-reload in Blender. After running `python install.py` again:
+
+- **First-time install of a new module name** (e.g. you renamed the addon): toggling enabled in
+  Preferences is enough — the new module loads fresh.
+- **Updating an already-loaded addon**: you must **fully restart Blender**. Disabling and
+  re-enabling the addon does *not* re-import the Python modules.
+
+Save your `.blend` first if you want to keep the scene.
+
+### Dev-mode hot-reload (advanced)
+
+Inside the running Blender, via `blender_execute_code`:
+
+```python
+import importlib
+from printable_blender import handlers, utils
+importlib.reload(utils)
+importlib.reload(handlers)
+```
+
+This reloads handler logic without a restart. The version shown in `bl_info` may still read
+the old number, but the running code is current. Note: changes to `__init__.py` (the TCP server
+itself) still require a full restart.
+
+## "Missing Add-ons" warnings after a rename
+
+If the addon was previously installed under a different module name (e.g. `claude_blender`)
+and you've since renamed/replaced it (e.g. with `printable_blender`), Blender will show the
+old name under **Preferences → Add-ons → Missing Add-ons** because it's still listed in
+`userpref.blend` as previously enabled, but the directory no longer exists.
+
+This is harmless. To clean it up: click the trash/X next to the missing entry, or just save
+preferences after enabling the new addon — Blender will drop the dead reference on next load.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| `ConnectionRefusedError` on port 9876 | Addon not enabled, or addon errored on load — check Blender's system console |
+| `Modules Installed ()` (empty parens) | You used Blender's "Install from Disk" on `install.py` — see [step 2](#2-install-the-blender-addon--from-a-terminal) |
+| Addon enables but immediately disables | Python error during `register()` — open `Window > Toggle System Console` to read it |
+| Code changes not taking effect | Module cache — restart Blender, or use the dev-mode reload above |
+| Missing Add-ons shows `claude_blender` (or other old name) | Stale reference from a previous install — see above, harmless |
+| TCP listening but commands hang | Blender is in a modal state (e.g. modal operator running, viewport editing) — main-thread timer is blocked |